Solution Architecture

Solution Architecture

Overview

Solution architecture defines how code is organized into layers and components. This skill covers Domain-Driven Design (DDD) layered architecture and essential coding principles like DRY and SOLID.

Core principle: The domain is the heart of your application. All other layers exist to support it.

When to Use

• Starting a new project or module
• Refactoring monolithic code into layers
• Deciding where business logic belongs
• Implementing repositories, services, or domain models
• Reviewing code for architectural violations

Not for: Simple CRUD apps, scripts, or prototypes where layering adds unnecessary complexity.

The Four Layers

┌─────────────────────────────────────┐
│         PRESENTATION LAYER          │  ← UI, Controllers, ViewModels
├─────────────────────────────────────┤
│         APPLICATION LAYER           │  ← Use Cases, Orchestration, CQRS
├─────────────────────────────────────┤
│           DOMAIN LAYER              │  ← Entities, Value Objects, Domain Services
├─────────────────────────────────────┤
│        INFRASTRUCTURE LAYER         │  ← Database, External APIs, Messaging
└─────────────────────────────────────┘

Dependency Rule: Each layer only depends on the layer directly inside it. Domain is innermost and has NO external dependencies.

Presentation Layer

Responsibility: User interaction and display

Contains:

• UI components (pages, views, components)
• Controllers / API endpoints
• ViewModels / DTOs for display
• Input validation (format only, not business rules)

Rules:

• No business logic
• Thin controllers - delegate to Application layer
• Platform-specific concerns only

// ✅ GOOD: Thin controller
[HttpPost]
public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
{
    var result = await _orderService.CreateOrderAsync(request.ToCommand());
    return result.IsSuccess ? Ok(result.Value) : BadRequest(result.Error);
}

// ❌ BAD: Business logic in controller
[HttpPost]
public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
{
    if (request.Items.Sum(i => i.Price) < 10)
        return BadRequest("Minimum order is $10");
    // ... more business logic
}

Application Layer

Responsibility: Use case orchestration and conditional business rules

Contains:

• Application Services (use case handlers)
• Commands and Queries (CQRS)
• DTOs for input/output
• Conditional business rules (context-dependent, policy-based)
• Cross-cutting concerns (authorization, validation, logging)
• Domain event handlers

Rules:

• Implements conditional/use-case specific business rules
• One use case = one unit of work (atomic)
• Publishes domain events
• Uses repository interfaces (not implementations)

// ✅ GOOD: Conditional rules in Application Service
public async Task<Result<OrderDto>> CreateOrderAsync(CreateOrderCommand command)
{
    var customer = await _customerRepository.GetByIdAsync(command.CustomerId);
    if (customer is null) return Result.Fail("Customer not found");
    
    // Conditional rule: Check credit limit (depends on external data)
    var pendingTotal = await _orderRepository.GetPendingTotalAsync(customer.Id);
    if (pendingTotal + command.Total > customer.CreditLimit)
        return Result.Fail("Order exceeds credit limit");
    
    // Conditional rule: Discount policy (may vary by context)
    var discount = customer.IsLoyal ? 0.1m : 0m;
    
    // Conditional rule: Minimum order for online channel
    if (command.IsOnlineOrder && command.Total < 25)
        return Result.Fail("Minimum online order is $25");
    
    var order = Order.Create(customer, command.Items, discount);
    
    await _orderRepository.AddAsync(order);
    await _unitOfWork.SaveChangesAsync();
    
    return Result.Ok(order.ToDto());
}

Domain Layer

Responsibility: Core business rules and invariants

Contains:

• Entities (identity + behavior)
• Value Objects (no identity, immutable)
• Aggregates (consistency boundaries)
• Domain Services (logic spanning entities within same aggregate)
• Domain Events
• Repository Interfaces (not implementations)
• Specifications
• Core business rules (invariants that must ALWAYS hold)

Rules:

• No dependencies on other layers
• No infrastructure concerns (no ORM attributes, no HTTP)
• Entities encapsulate behavior, not just data
• Aggregates enforce invariants

Core vs Conditional Rules

How to decide:

• Can the entity enforce this alone? → Domain
• Does it need database queries? → Application
• Does it vary by use case/channel? → Application
• Would violation create impossible state? → Domain
• Is it a business policy that might change? → Application

// ✅ GOOD: Entity with behavior
public class Order : Entity<OrderId>
{
    private readonly List<OrderLine> _lines = new();
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();
    public Money Total => _lines.Sum(l => l.Subtotal);
    
    public static Order Create(Customer customer, IEnumerable<OrderLineDto> items)
    {
        var order = new Order(OrderId.New(), customer.Id);
        foreach (var item in items)
            order.AddLine(item.ProductId, item.Quantity, item.Price);
        return order;
    }
    
    public void AddLine(ProductId productId, int quantity, Money price)
    {
        if (quantity <= 0) throw new DomainException("Quantity must be positive");
        _lines.Add(new OrderLine(productId, quantity, price));
        AddDomainEvent(new OrderLineAddedEvent(Id, productId));
    }
}

// ❌ BAD: Anemic entity (data only)
public class Order
{
    public int Id { get; set; }
    public List<OrderLine> Lines { get; set; } = new();
    public decimal Total { get; set; }
}

Infrastructure Layer

Responsibility: Technical implementations and external systems

Contains:

• Repository implementations
• Database context / ORM configuration
• External API clients
• Message queue implementations
• File system access
• Email/SMS services

Rules:

• Implements interfaces defined in Domain/Application
• Contains all platform-specific code
• "Get in, get out quick" - minimal logic

// ✅ GOOD: Repository implementation
public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;
    
    public async Task<Order?> GetByIdAsync(OrderId id)
        => await _context.Orders
            .Include(o => o.Lines)
            .FirstOrDefaultAsync(o => o.Id == id);
    
    public async Task AddAsync(Order order)
        => await _context.Orders.AddAsync(order);
}

DDD Building Blocks

Quick Reference

Entity vs Value Object

// Entity: tracked by identity
public class Customer : Entity<CustomerId>
{
    public string Name { get; private set; }
    public Email Email { get; private set; }
}

// Value Object: tracked by value, immutable
public record Email
{
    public string Value { get; }
    
    public Email(string value)
    {
        if (!IsValid(value)) throw new DomainException("Invalid email");
        Value = value;
    }
    
    private static bool IsValid(string email) => /* validation */;
}

Aggregates

Rules:

• One entity is the Aggregate Root
• External references only via root's ID
• Root enforces all invariants
• One aggregate = one transaction

// Order is aggregate root
public class Order : AggregateRoot<OrderId>
{
    private readonly List<OrderLine> _lines = new();
    
    // Only root can modify children
    public void AddLine(ProductId productId, int quantity, Money price)
    {
        ValidateCanAddLine();
        _lines.Add(new OrderLine(productId, quantity, price));
    }
}

// ❌ BAD: External code modifying aggregate internals
order.Lines.Add(new OrderLine(...)); // Bypasses invariant checks

Coding Principles

DRY (Don't Repeat Yourself)

Every piece of knowledge has a single, unambiguous representation.

// ❌ BAD: Duplicated validation
public void CreateUser(string email) { if (!email.Contains("@")) throw ...; }
public void UpdateEmail(string email) { if (!email.Contains("@")) throw ...; }

// ✅ GOOD: Single source of truth
public record Email(string Value)
{
    public Email(string value) : this(value)
    {
        if (!value.Contains("@")) throw new DomainException("Invalid email");
    }
}

SOLID Principles

Additional Principles

• YAGNI - Don't build it until you need it
• KISS - Keep solutions simple
• Separation of Concerns - Each module handles one thing
• Explicit Dependencies - No hidden service locators

Common Mistakes

Layer Dependency Violations

// ❌ Domain layer importing Infrastructure
using Microsoft.EntityFrameworkCore; // VIOLATION

// ❌ Domain layer importing Application
using MyApp.Application.DTOs; // VIOLATION

// ✅ Domain layer - only domain concerns
using MyApp.Domain.ValueObjects;
using MyApp.Domain.Events;

Project Structure Example

src/
├── MyApp.Presentation/          # UI, Controllers
│   ├── Controllers/
│   └── ViewModels/
├── MyApp.Application/           # Use Cases, CQRS
│   ├── Commands/
│   ├── Queries/
│   └── Services/
├── MyApp.Domain/                # Core Business Logic
│   ├── Entities/
│   ├── ValueObjects/
│   ├── Services/
│   ├── Events/
│   └── Repositories/            # Interfaces only
├── MyApp.Infrastructure/        # External Concerns
│   ├── Persistence/
│   ├── ExternalServices/
│   └── Messaging/
└── MyApp.Domain.Shared/         # Shared enums, constants

Decision Guide

Where does this code belong?

Is it UI/display related?
  → Presentation Layer

Is it orchestrating a use case?
  → Application Layer

Is it a core business rule?
  → Domain Layer

Is it talking to external systems?
  → Infrastructure Layer