Clean Architecture and CQRS

Why architecture?

In a small app, everything can live in Program.cs. As an application grows to dozens of features and several developers, you need a structure that keeps business rules understandable, testable and independent of frameworks and databases that will change over the app's lifetime.

Layered architecture

The traditional approach splits code by technical concern:

Presentation   (API endpoints, controllers, views)
     ↓
Application    (use cases: PlaceOrder, CancelOrder)
     ↓
Domain         (entities, business rules: Order, Money)
     ↓
Infrastructure (EF Core, email, payment SDKs)

Clean Architecture: point dependencies inward

Clean Architecture (also: Onion, Hexagonal / Ports and Adapters) flips the bottom dependency. The domain is at the center and depends on nothing; infrastructure sits at the edge and implements interfaces defined inside:

        ┌───────────────────────────────────────┐
        │  Infrastructure & Presentation        │   EF Core, SMTP, ASP.NET Core
        │   ┌───────────────────────────────┐   │
        │   │  Application (use cases)      │   │   defines IOrderRepository, IEmailSender
        │   │   ┌───────────────────────┐   │   │
        │   │   │  Domain (entities,    │   │   │   pure C#, no framework references
        │   │   │  rules, value objects)│   │   │
        │   │   └───────────────────────┘   │   │
        │   └───────────────────────────────┘   │
        └───────────────────────────────────────┘
              dependencies point inward →

A typical solution:

Shop.Domain           — Order, OrderLine, Money, domain rules
Shop.Application      — PlaceOrderHandler, IOrderRepository, DTOs
Shop.Infrastructure   — ShopDbContext, EfOrderRepository, SmtpEmailSender
Shop.Api              — Program.cs, endpoints, DI wiring

Business rules can be unit-tested without a database or web server, and swapping SQL Server for PostgreSQL touches only infrastructure.

Vertical slices

Layers spread one feature across many folders: adding "cancel order" touches a controller, a service, a repository, DTOs… Vertical slice architecture groups code by feature instead:

Features/
  Orders/
    PlaceOrder.cs        ← request, validator, handler and endpoint together
    CancelOrder.cs
    GetOrderDetails.cs
  Products/
    SearchProducts.cs

Each slice can be as simple or as sophisticated as it needs. Many teams combine slices for application code with a shared, rich domain model.

CQRS: commands and queries

Command Query Responsibility Segregation separates:

• Commands — change state: PlaceOrder, CancelOrder. Validate, apply business rules, save. Return little (an id, or nothing).
• Queries — read state: GetOrderDetails, SearchProducts. No side effects; free to project straight into DTOs, use AsNoTracking, Dapper, or a read-optimized store.

public record PlaceOrder(int CustomerId, List<LineDto> Lines) : IRequest<int>;
 
public class PlaceOrderHandler(ShopDb db) : IRequestHandler<PlaceOrder, int>
{
    public async Task<int> Handle(PlaceOrder command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Lines);   // domain rules inside
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return order.Id;
    }
}

CQRS at this level is just a clear way to organize use cases. "Full" CQRS with separate read and write databases is a heavier tool for specific scaling needs.

The mediator

Endpoints shouldn't need to know which class handles a request. A mediator dispatches each request to its registered handler:

app.MapPost("/orders", async (PlaceOrder command, IMediator mediator) =>
    Results.Created($"/orders/{await mediator.Send(command)}", null));

MediatR is the popular library; it also supports pipeline behaviors — decorators around every handler for validation, logging or transactions. In the exercise you'll build the core idea in a few lines.

Domain events

When an order is placed, several things should follow — email, stock reservation, analytics. Rather than calling them all from the handler, the domain raises an event:

public class Order
{
    private readonly List<object> events = [];
    public IReadOnlyList<object> Events => events;
 
    public static Order Create(...) { var o = new Order(...); o.events.Add(new OrderPlaced(o.Id)); return o; }
}

After saving, the events are dispatched to handlers — in-process, or via a message broker to other services.

Key takeaways

• Clean Architecture keeps the domain at the center; dependencies point inward, infrastructure implements inner interfaces.
• Vertical slices organize code by feature, keeping each use case together.
• CQRS separates commands (change state) from queries (read state).
• A mediator dispatches requests to handlers; domain events decouple side effects. Use as much structure as the problem needs.