.NET Architecture at Scale: Visual Guide to Modern Design Patterns

mindmap
  root((Design Patterns))
    Foundational
      Layered
      Hexagonal
      Onion
    Communication
      CQRS
      Event-Driven
      Saga
    Integration
      API Gateway
      BFF
      Serverless
      Strangler Fig
    Resilience
      Circuit Breaker
      Bulkhead
      Outbox
    Infrastructure
      Sidecar
      Ambassador
    Data
      Event Sourcing

sequenceDiagram
    participant C as Client
    participant P as Presentation Layer
    participant B as Business Layer
    participant D as Data Layer
    participant DB as Database

    C->>P: HTTP Request
    P->>P: Validate Input
    P->>B: Call Business Logic
    B->>B: Apply Business Rules
    B->>D: Repository Call
    D->>DB: SQL Query
    DB-->>D: Data
    D-->>B: Domain Objects
    B-->>P: Processing Result
    P-->>C: HTTP Response

// Business Logic Layer - Service
public class ProductService : IProductService
{
    private readonly IProductRepository _productRepository;

    public ProductService(IProductRepository productRepository)
    {
        _productRepository = productRepository;
    }

    public async Task<IEnumerable<Product>> GetAllProductsAsync()
    {
        return await _productRepository.GetAllAsync();
    }

    public async Task<Product> CreateProductAsync(CreateProductRequest request)
    {
        var product = new Product
        {
            Name = request.Name,
            Price = request.Price,
            CreatedAt = DateTime.UtcNow
        };

        return await _productRepository.CreateAsync(product);
    }
}

// Data Access Layer - Repository
public class ProductRepository : IProductRepository
{
    private readonly AppDbContext _context;

    public ProductRepository(AppDbContext context)
    {
        _context = context;
    }

    public async Task<IEnumerable<Product>> GetAllAsync()
    {
        return await _context.Products.ToListAsync();
    }

    public async Task<Product> CreateAsync(Product product)
    {
        _context.Products.Add(product);
        await _context.SaveChangesAsync();
        return product;
    }
}

// Core Contracts - Keep Minimal
public interface IProductRepository
{
    Task<Product> GetByIdAsync(int id);
    Task<Product> SaveAsync(Product product);
}

public interface IProductService
{
    Task<ProductDto> CreateProductAsync(CreateProductRequest request);
}

// Port - Interface defined by business needs
public interface IProductRepository
{
    Task<Product> GetByIdAsync(int id);
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product> SaveAsync(Product product);
}

// Application Service - Orchestrates business logic
public class ProductService
{
    private readonly IProductRepository _productRepository;
    private readonly INotificationService _notificationService;

    public ProductService(IProductRepository productRepository,
                         INotificationService notificationService)
    {
        _productRepository = productRepository;
        _notificationService = notificationService;
    }

    public async Task<Product> CreateProductAsync(string name, decimal price)
    {
        var product = new Product(name, price);
        var savedProduct = await _productRepository.SaveAsync(product);

        await _notificationService.SendProductCreatedNotificationAsync(savedProduct);

        return savedProduct;
    }
}

sequenceDiagram
    participant UI as Presentation
    participant App as Application
    participant Dom as Domain
    participant Inf as Infrastructure

    UI->>App: Execute Use Case
    App->>Dom: Business Logic Call
    Dom->>Dom: Apply Business Rules
    Dom->>App: Domain Events
    App->>Inf: Persist Changes
    Inf-->>App: Confirmation
    App-->>UI: Response DTO

    Note over Dom: Core business logic<br/>remains isolated

Property.Management.Domain/
├── Entities/
├── ValueObjects/
├── DomainServices/
└── Events/

Property.Management.Application/
├── UseCases/
├── Services/
├── DTOs/
└── Interfaces/

Property.Management.Infrastructure/
├── Persistence/
├── ExternalServices/
└── Configuration/

Property.Management.Presentation/
├── Controllers/
├── Models/
└── Views/

// Domain Layer - Rich domain model
public class Order
{
    private readonly List<OrderItem> _items = new();

    public int Id { get; private set; }
    public string CustomerName { get; private set; }
    public DateTime OrderDate { get; private set; }
    public OrderStatus Status { get; private set; }
    public decimal TotalAmount => _items.Sum(i => i.Price * i.Quantity);

    public Order(string customerName)
    {
        OrderDate = DateTime.UtcNow;
        Status = OrderStatus.Draft;
    }

    public void AddItem(string productName, decimal price, int quantity)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Cannot modify confirmed order");

        _items.Add(new OrderItem(productName, price, quantity));
    }

    public void ConfirmOrder()
    {
        if (!_items.Any())
            throw new InvalidOperationException("Cannot confirm empty order");
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Order already confirmed");

        Status = OrderStatus.Confirmed;
    }
}

// Application Layer - Use cases
public class OrderService : IOrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly IEmailService _emailService;

    public OrderService(IOrderRepository orderRepository, IEmailService emailService)
    {
        _orderRepository = orderRepository;
        _emailService = emailService;
    }

    public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
    {
        var order = new Order(request.CustomerName);
        var savedOrder = await _orderRepository.SaveAsync(order);

        return new OrderDto
        {
            Id = savedOrder.Id,
            CustomerName = savedOrder.CustomerName,
            OrderDate = savedOrder.OrderDate,
            Status = savedOrder.Status.ToString(),
            TotalAmount = savedOrder.TotalAmount
        };
    }

    public async Task<OrderDto> ConfirmOrderAsync(int orderId)
    {
        var order = await _orderRepository.GetByIdAsync(orderId);
        if (order == null)
            throw new ArgumentException("Order not found");

        order.ConfirmOrder();
        var confirmedOrder = await _orderRepository.SaveAsync(order);

        await _emailService.SendOrderConfirmationAsync(confirmedOrder);

        return MapToDto(confirmedOrder);
    }
}

sequenceDiagram
    participant C as Client
    participant API as API Gateway
    participant CH as Command Handler
    participant WS as Write Store
    participant EB as Event Bus
    participant QH as Query Handler
    participant RS as Read Store

    Note over C,RS: Command Flow
    C->>API: Create Order Command
    API->>CH: Process Command
    CH->>WS: Store Write Model
    CH->>EB: Publish Domain Event
    EB->>QH: Update Read Model
    QH->>RS: Store Read Model

    Note over C,RS: Query Flow
    C->>API: Get Order Query
    API->>QH: Process Query
    QH->>RS: Retrieve Read Model
    RS-->>QH: Read Model Data
    QH-->>API: Query Result
    API-->>C: Response

// Keep contracts minimal and focused
public interface ICommand<TResult> : IRequest<TResult> { }
public interface IQuery<TResult> : IRequest<TResult> { }

// Example command
public record CreateOrderCommand(string CustomerId, List<OrderItem> Items) : ICommand<int>;

// Example query
public record GetOrderQuery(int OrderId) : IQuery<OrderDto>;

// Controllers using MediatR
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IMediator _mediator;

    public ProductsController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpPost]
    public async Task<IActionResult> CreateProduct([FromBody] CreateProductCommand command)
    {
        var productId = await _mediator.Send(command);
        return CreatedAtAction(nameof(GetProduct), new { id = productId }, productId);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetProduct(int id)
    {
        var product = await _mediator.Send(new GetProductByIdQuery(id));
        return Ok(product);
    }
}

stateDiagram-v2
    [*] --> EventPublished
    EventPublished --> Processing
    Processing --> Success: All Handlers Complete
    Processing --> PartialFailure: Some Handlers Fail
    Processing --> TotalFailure: Critical Handler Fails

    PartialFailure --> Retry: Retry Failed Handlers
    TotalFailure --> Compensate: Execute Compensation

    Retry --> Success: Retry Successful
    Retry --> Dead Letter: Max Retries Exceeded

    Success --> [*]
    Compensate --> [*]
    Dead Letter --> [*]

// Minimal event contract
public record OrderCreatedEvent(
    int OrderId,
    string CustomerId,
    decimal Amount,
    DateTime CreatedAt);

// Event handler interface
public interface IEventHandler<in TEvent>
{
    Task HandleAsync(TEvent eventData);
}

// Command Handler using MediatR
public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, int>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IMediator _mediator;

    public async Task<int> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        var order = new Order(request.CustomerId, request.Items);
        await _orderRepository.SaveAsync(order);

        // Publish domain event
        await _mediator.Publish(new OrderCreatedEvent
        {
            OrderId = order.Id,
            CustomerId = request.CustomerId,
            Items = request.Items,
            TotalAmount = order.TotalAmount
        }, cancellationToken);

        return order.Id;
    }
}
    }
}

// Event Handlers
public class InventoryEventHandler : INotificationHandler<OrderCreatedEvent>
{
    private readonly IInventoryService _inventoryService;

    public async Task Handle(OrderCreatedEvent notification, CancellationToken cancellationToken)
    {
        foreach (var item in notification.Items)
        {
            await _inventoryService.ReserveInventoryAsync(item.ProductId, item.Quantity);
        }
    }
}

public class EmailNotificationHandler : INotificationHandler<OrderCreatedEvent>
{
    private readonly IEmailService _emailService;

    public async Task Handle(OrderCreatedEvent notification, CancellationToken cancellationToken)
    {
        await _emailService.SendOrderConfirmationAsync(
            notification.CustomerId,
            notification.OrderId);
    }
}

stateDiagram-v2
    [*] --> Started
    Started --> PaymentProcessed: Process Payment
    PaymentProcessed --> InventoryReserved: Reserve Inventory
    InventoryReserved --> OrderConfirmed: Confirm Order
    OrderConfirmed --> [*]

    PaymentProcessed --> Compensating: Payment Failed
    InventoryReserved --> Compensating: Inventory Failed
    Compensating --> Failed: Rollback Complete
    Failed --> [*]

    Compensating: Execute compensating transactions in reverse order

// Saga State Machine
public class OrderProcessingSaga
{
    public string OrderId { get; set; }
    public string CustomerId { get; set; }
    public decimal Amount { get; set; }
    public SagaState State { get; set; }
    public List<string> CompletedSteps { get; set; } = new();

    public enum SagaState
    {
        Started,
        PaymentProcessed,
        InventoryReserved,
        OrderConfirmed,
        Failed,
        Compensating
    }
}

// Saga Orchestrator
public class OrderSagaOrchestrator
{
    private readonly IMediator _mediator;
    private readonly ISagaRepository _sagaRepository;

    public async Task HandleOrderCreatedAsync(OrderCreatedEvent orderCreated)
    {
        var saga = new OrderProcessingSaga
        {
            OrderId = orderCreated.OrderId.ToString(),
            CustomerId = orderCreated.CustomerId,
            Amount = orderCreated.TotalAmount,
            State = OrderProcessingSaga.SagaState.Started
        };

        await _sagaRepository.SaveAsync(saga);

        // Start the saga by processing payment
        await _mediator.Send(new ProcessPaymentCommand(
            saga.OrderId,
            saga.CustomerId,
            saga.Amount));
    }

    public async Task HandlePaymentProcessedAsync(PaymentProcessedEvent paymentProcessed)
    {
        var saga = await _sagaRepository.GetByOrderIdAsync(paymentProcessed.OrderId);
        saga.State = OrderProcessingSaga.SagaState.PaymentProcessed;
        saga.CompletedSteps.Add("Payment");

        await _sagaRepository.UpdateAsync(saga);

        // Next step: Reserve inventory
        await _mediator.Send(new ReserveInventoryCommand(
            saga.OrderId,
            paymentProcessed.Items));
    }

    public async Task HandleStepFailedAsync(SagaStepFailedEvent stepFailed)
    {
        var saga = await _sagaRepository.GetByOrderIdAsync(stepFailed.OrderId);
        saga.State = OrderProcessingSaga.SagaState.Compensating;

        await _sagaRepository.UpdateAsync(saga);

        // Execute compensating transactions in reverse order
        await ExecuteCompensatingTransactionsAsync(saga);
    }

    private async Task ExecuteCompensatingTransactionsAsync(OrderProcessingSaga saga)
    {
        var completedSteps = saga.CompletedSteps.AsEnumerable().Reverse();

        foreach (var step in completedSteps)
        {
            switch (step)
            {
                case "Inventory":
                    await _mediator.Send(new ReleaseInventoryCommand(saga.OrderId));
                    break;
                case "Payment":
                    await _mediator.Send(new RefundPaymentCommand(saga.OrderId, saga.Amount));
                    break;
            }
        }

        saga.State = OrderProcessingSaga.SagaState.Failed;
        await _sagaRepository.UpdateAsync(saga);
    }
}

// Rate limiting policy
@{
    return context.Request.IpAddress == "192.168.1.1" ? 1000 : 100;
}

// Route based on User-Agent
@{
    return context.Request.Headers.GetValueOrDefault("User-Agent", "").Contains("Mobile")
        ? "mobile-backend"
        : "web-backend";
}

// Mobile BFF Service
[ApiController]
[Route("api/mobile/[controller]")]
public class MobileProductController : ControllerBase
{
    private readonly IProductService _productService;
    private readonly IImageService _imageService;

    [HttpGet("{id}")]
    public async Task<MobileProductDto> GetProduct(int id)
    {
        var product = await _productService.GetByIdAsync(id);

        // Mobile-specific optimization: smaller images, essential data only
        return new MobileProductDto
        {
            Id = product.Id,
            Name = product.Name,
            Price = product.Price,
            ThumbnailUrl = await _imageService.GetThumbnailAsync(product.ImageUrl, "mobile"),
            Rating = product.AverageRating,
            InStock = product.StockLevel > 0
        };
    }
}

// Web BFF Service
[ApiController]
[Route("api/web/[controller]")]
public class WebProductController : ControllerBase
{
    private readonly IProductService _productService;
    private readonly IReviewService _reviewService;

    [HttpGet("{id}")]
    public async Task<WebProductDto> GetProduct(int id)
    {
        var product = await _productService.GetByIdAsync(id);
        var reviews = await _reviewService.GetRecentReviewsAsync(id, 10);

        // Web-specific: full data with reviews, recommendations
        return new WebProductDto
        {
            Id = product.Id,
            Name = product.Name,
            Description = product.Description,
            Price = product.Price,
            ImageUrls = product.ImageUrls,
            Specifications = product.Specifications,
            Reviews = reviews,
            StockLevel = product.StockLevel,
            EstimatedDelivery = CalculateDeliveryDate(product)
        };
    }
}

// .NET Isolated Worker Model
[Function("ProcessOrder")]
public async Task<IActionResult> ProcessOrder(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
    [CosmosDBOutput("OrdersDB", "Orders", Connection = "CosmosDB")] IAsyncCollector<Order> orders)
{
    var order = await req.ReadFromJsonAsync<Order>();
    await orders.AddAsync(order);

    return new OkObjectResult(new { OrderId = order.Id, Status = "Processing" });
}

// Durable Functions Orchestration
[Function("OrderProcessingOrchestrator")]
public async Task<string> RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var order = context.GetInput<Order>();

    // Function chaining pattern
    await context.CallActivityAsync("ValidateOrder", order);
    await context.CallActivityAsync("ProcessPayment", order);
    await context.CallActivityAsync("UpdateInventory", order);
    await context.CallActivityAsync("ShipOrder", order);

    return "Order processed successfully";
}

// Routing Facade Implementation
public class StranglerFacade : IHostedService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly IConfiguration _configuration;

    public async Task RouteRequest(HttpContext context)
    {
        var feature = DetermineFeature(context.Request.Path);

        if (IsModernizedFeature(feature))
        {
            await RouteToModernService(context, feature);
        }
        else
        {
            await RouteToLegacySystem(context);
        }
    }

    private bool IsModernizedFeature(string feature)
    {
        return _configuration.GetValue<bool>($"Features:{feature}:Modernized");
    }

    private async Task RouteToModernService(HttpContext context, string feature)
    {
        // Route to new microservice
        var modernServiceUrl = _configuration[$"Services:{feature}:Url"];
        // Implementation details...
    }

    private async Task RouteToLegacySystem(HttpContext context)
    {
        // Route to legacy system
        var legacyUrl = _configuration["LegacySystem:BaseUrl"];
        // Implementation details...
    }
}

stateDiagram-v2
    [*] --> Closed
    Closed --> Open: Failure Threshold Exceeded
    Open --> HalfOpen: Timeout Expires
    HalfOpen --> Closed: Test Request Succeeds
    HalfOpen --> Open: Test Request Fails

    Closed: Normal Operation<br/>Requests Pass Through<br/>Monitor Failures
    Open: Circuit Tripped<br/>Fail Fast<br/>No Requests Allowed
    HalfOpen: Testing Recovery<br/>Limited Test Requests<br/>Evaluate Health

    note right of Closed
        Success Rate > Threshold
        Reset Failure Counter
    end note

    note right of Open
        Immediate Rejection
        Resource Protection
        Wait for Recovery
    end note

    note right of HalfOpen
        Single Test Request
        Quick Failure Detection
        Gradual Recovery
    end note

// Modern .Net Implementation
services.AddHttpClient<PaymentService>()
    .AddStandardResilienceHandler(options =>
    {
        options.CircuitBreaker.FailureRatio = 0.5;
        options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10);
        options.CircuitBreaker.MinimumThroughput = 8;
        options.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(30);
    });

// Custom Circuit Breaker with Polly v8
var circuitBreakerOptions = new CircuitBreakerStrategyOptions
{
    FailureRatio = 0.5,
    SamplingDuration = TimeSpan.FromSeconds(10),
    MinimumThroughput = 8,
    BreakDuration = TimeSpan.FromSeconds(30),
    ShouldHandle = new PredicateBuilder()
        .Handle<HttpRequestException>()
        .Handle<TimeoutRejectedException>()
        .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
};

var resiliencePipeline = new ResiliencePipelineBuilder()
    .AddCircuitBreaker(circuitBreakerOptions)
    .Build();

sequenceDiagram
    participant App as Application
    participant DB as Database
    participant OT as Outbox Table
    participant BP as Background Processor
    participant MB as Message Bus
    participant CS as Consuming Services

    Note over App,CS: Business Transaction with Reliable Messaging

    App->>DB: Begin Transaction
    App->>DB: Save Business Data
    App->>OT: Store Outbox Event
    App->>DB: Commit Transaction

    Note over BP: Polling Process (every 5s)

    BP->>OT: Query Unprocessed Events
    OT-->>BP: Pending Events

    loop For Each Event
        BP->>MB: Publish Event
        MB-->>BP: Acknowledge
        BP->>OT: Mark as Processed
    end

    MB->>CS: Deliver Event
    CS-->>MB: Acknowledge

    Note over App,CS: Guaranteed Delivery:<br/>At-least-once semantics

erDiagram
    OUTBOX_EVENTS {
        guid Id PK
        string Type
        string Data
        datetime CreatedAt
        boolean IsProcessed
        datetime ProcessedAt
        int RetryCount
        string LastError
    }

    BUSINESS_DATA {
        int Id PK
        string Content
        datetime CreatedAt
    }

    OUTBOX_EVENTS ||--o{ BUSINESS_DATA : references

// Outbox Event Entity
public class OutboxEvent
{
    public Guid Id { get; set; }
    public string Type { get; set; }
    public string Data { get; set; }
    public DateTime CreatedAt { get; set; }
    public bool IsProcessed { get; set; }
    public DateTime? ProcessedAt { get; set; }
}

// Service Implementation
public class OrderService
{
    private readonly ApplicationDbContext _context;

    public async Task CreateOrderAsync(Order order)
    {
        using var transaction = await _context.Database.BeginTransactionAsync();

        try
        {
            // Save business data
            _context.Orders.Add(order);

            // Save outbox event
            var outboxEvent = new OutboxEvent
            {
                Id = Guid.NewGuid(),
                Type = "OrderCreated",
                Data = JsonSerializer.Serialize(new OrderCreatedEvent(order.Id)),
                CreatedAt = DateTime.UtcNow,
                IsProcessed = false
            };

            _context.OutboxEvents.Add(outboxEvent);

            await _context.SaveChangesAsync();
            await transaction.CommitAsync();
        }
        catch
        {
            await transaction.RollbackAsync();
            throw;
        }
    }
}

// Outbox Processor
public class OutboxProcessor : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await ProcessOutboxEventsAsync();
            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }
    }

    private async Task ProcessOutboxEventsAsync()
    {
        using var scope = _serviceProvider.CreateScope();
        var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
        var serviceBus = scope.ServiceProvider.GetRequiredService<IServiceBus>();

        var pendingEvents = await context.OutboxEvents
            .Where(e => !e.IsProcessed)
            .OrderBy(e => e.CreatedAt)
            .Take(100)
            .ToListAsync();

        foreach (var outboxEvent in pendingEvents)
        {
            try
            {
                await serviceBus.PublishAsync(outboxEvent.Type, outboxEvent.Data);

                outboxEvent.IsProcessed = true;
                outboxEvent.ProcessedAt = DateTime.UtcNow;

                await context.SaveChangesAsync();
            }
            catch (Exception ex)
            {
                // Log error and continue
            }
        }
    }
}

sequenceDiagram
    participant Dev as Developer
    participant Aspire as .NET Aspire
    participant Docker as Docker
    participant ACA as Azure Container Apps
    participant Dapr as Dapr Runtime
    participant Azure as Azure Services

    Dev->>Aspire: Define Distributed App
    Aspire->>Docker: Generate Containers
    Docker->>ACA: Deploy to Container Apps
    ACA->>Dapr: Initialize Dapr Sidecar
    Dapr->>Azure: Connect to Azure Services

    Note over Dev,Azure: Simplified Cloud-Native Development

    Azure-->>Dapr: Service Responses
    Dapr-->>ACA: Process Results
    ACA-->>Aspire: Runtime Telemetry
    Aspire-->>Dev: Monitoring Dashboard

// .NET Aspire Integration
var builder = DistributedApplication.CreateBuilder(args);

var catalog = builder.AddProject<Projects.Catalog_API>("catalog")
    .WithDaprSidecar();

var ordering = builder.AddProject<Projects.Ordering_API>("ordering")
    .WithDaprSidecar();

var gateway = builder.AddProject<Projects.Gateway>("gateway")
    .WithReference(catalog)
    .WithReference(ordering);

builder.Build().Run();

sequenceDiagram
    participant C as Client
    participant P as Proxy Sidecar
    participant M as Main App
    participant L as Logging Sidecar
    participant Mon as Monitoring Sidecar
    participant E as External Services

    C->>P: HTTP Request
    P->>P: Apply Security Policies
    P->>M: Forward Request
    P->>Mon: Record Metrics

    M->>M: Process Business Logic
    M->>L: Write Application Logs
    M->>P: Return Response

    P->>Mon: Record Response Metrics
    P->>C: Forward Response

    L->>E: Ship Logs to ELK
    Mon->>E: Send Metrics to Prometheus

// Main Application Service
[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
    private readonly IOrderService _orderService;

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // Main business logic - sidecar handles logging, monitoring automatically
        var order = await _orderService.CreateAsync(request);
        return Ok(order);
    }
}

// Sidecar Configuration (docker-compose.yml)