The Problem With Layers

In a layered architecture, a simple "Get Order by ID" feature touches:

1. OrdersController (Presentation)
2. IOrderService + OrderService (Application)
3. IOrderRepository + OrderRepository (Infrastructure)
4. OrderDto, OrderResponse (Mapping)

Four files across four folders for a database query that returns one object. Adding a new feature means touching every layer. Modifying a feature means jumping between folders.

What Changes Together Should Live Together

Vertical Slice Architecture organizes code by feature instead of layer, and it's easier to adopt than most people think:

// Layered: related code is scattered
Controllers/OrdersController.cs    ← GetOrder, CreateOrder, DeleteOrder
Services/OrderService.cs           ← GetOrder, CreateOrder, DeleteOrder
Repositories/OrderRepository.cs    ← GetOrder, CreateOrder, DeleteOrder

// VSA: related code is co-located
Features/Orders/GetOrder.cs        ← everything for GetOrder
Features/Orders/CreateOrder.cs     ← everything for CreateOrder
Features/Orders/DeleteOrder.cs     ← everything for DeleteOrder

When you work on "Get Order," you open one file. When you review a pull request, the diff shows one file per feature.

Choose VSA When...

Your Features Are Independent

If most features don't share logic, VSA reduces unnecessary abstractions:

// This feature needs no repository, no service layer
public static class GetOrder
{
    public sealed record Query(Guid Id);

    public sealed record OrderResponse(
        Guid Id, string Status, decimal TotalAmount, DateTime CreatedAt);

    public sealed class Handler(ApplicationDbContext db)
    {
        public async Task<OrderResponse?> Handle(
            Query query, CancellationToken ct)
        {
            return await db.Orders
                .Where(o => o.Id == query.Id)
                .Select(o => new OrderResponse(
                    o.Id, o.Status, o.TotalAmount, o.CreatedAt))
                .FirstOrDefaultAsync(ct);
        }
    }
}

No interface, no repository, no service. Just a query that returns data.

Your Team Is Growing

With layers, two developers working on separate features often edit the same files - the same controller, the same service. Merge conflicts happen frequently.

With VSA, each developer works in separate files. Feature A doesn't touch Feature B's code.

You Want Fast Iteration

VSA has less ceremony. Adding a new feature:

1. Create one file
2. Define the request, handler, and endpoint
3. Done

No interface to define, no repository to implement, and assembly scanning handles the registration.

Your Application Is CRUD-Heavy

Many business applications are variations of create-read-update-delete. VSA handles this cleanly:

Features/
  Products/
    CreateProduct.cs      ← 60 lines
    GetProduct.cs         ← 40 lines
    GetProducts.cs        ← 50 lines
    UpdateProduct.cs      ← 70 lines
    DeleteProduct.cs      ← 30 lines

Each file is small and self-contained. No layered abstractions adding complexity without value.

You're Using CQRS

CQRS and VSA are a natural pair. Commands and queries are already separate operations - putting each in its own file is the logical next step:

Features/
  Orders/
    Commands/
      PlaceOrder.cs
      CancelOrder.cs
    Queries/
      GetOrder.cs
      GetOrders.cs

Choose Layers When...

You Have Complex Shared Business Logic

If 10 features all need the same pricing calculation, a PricingService in a service layer makes sense. Duplicating that logic across 10 slices is worse.

You Need Strict Architectural Boundaries

Layers enforce compile-time boundaries. The presentation layer physically cannot reference the database. VSA in a single project doesn't prevent a handler from doing whatever it wants.

Your Team Is Familiar With Layers

Architecture decisions are team decisions. If your team knows layered architecture well and productivity is good, switching to VSA for the sake of switching creates churn without value.

You Have a Rich Domain Model

Domain-Driven Design with a rich domain model benefits from a dedicated domain layer. The domain layer contains complex business rules that multiple features share. Clean Architecture is a better fit here.

The Middle Ground

You don't have to be all-in on either approach. Many successful projects combine both:

src/
  MyApp.Api/
    Features/           ← Vertical slices for individual operations
      Orders/
        PlaceOrder.cs
        GetOrder.cs
    Domain/             ← Shared domain entities (from Clean Architecture)
      Order.cs
      Customer.cs
    Shared/             ← Cross-cutting concerns
      Behaviors/
        ValidationBehavior.cs

Use slices for application logic. Use a domain layer for shared business rules. Use pipeline behaviors for cross-cutting concerns.

Migrating From Layers, Incrementally

Choosing VSA doesn't mean rewriting your layered application. The migration path I recommend:

1. New features go in a Features folder as self-contained slices. Don't touch the existing layers yet.
2. When you modify an existing feature, consider moving it into a slice as part of the change. The controller action, service method, and repository method collapse into one handler.
3. Leave stable code alone. A feature nobody has touched in a year gains nothing from being restructured.
4. Delete layers as they empty out. When OrderService has one method left, inline it and remove the class.

After a few months you have a codebase that's mostly slices with a small legacy core, and you got there without a big-bang rewrite or a feature freeze.

Decision Matrix

Signals that point toward Vertical Slice Architecture:

• Features are largely independent of each other
• The application is CRUD-heavy
• You need fast iteration with minimal ceremony
• The team is growing and works on many features in parallel
• You're already using CQRS

Signals that point toward layers:

• Heavy shared business logic across features
• A rich domain model with DDD
• You need strict compile-time boundaries
• The team is experienced and productive with layers

If your signals land on both sides, that's normal. It usually means the hybrid approach (slices plus a shared domain layer) is your answer.

Making the Call

Choose Vertical Slice Architecture when:

1. Features are independent and rarely share logic
2. Your team needs parallel development without merge conflicts
3. You value simplicity - one file per feature, no unnecessary abstractions
4. You're already using CQRS (with or without MediatR)
5. The application is CRUD-heavy without complex domain logic

Choose layers when shared business logic, strict boundaries, or DDD richness justifies the overhead.

The best architecture is the one your team can maintain and evolve. Start with what fits your problem, not what's trending.

Thanks for reading, and stay awesome!

Two Different Philosophies

Clean Architecture organizes code by technical layer - Domain, Application, Infrastructure, Presentation. Each layer has clear responsibilities, and dependencies point inward.

Vertical Slice Architecture organizes code by feature - each feature is a self-contained slice that cuts through all layers from UI to database. You don't share code between slices unless it's a genuine cross-cutting concern.

Both are valid. But they optimize for different things.

Clean Architecture in Brief

Clean Architecture separates your solution into concentric layers:

Presentation → Application → Domain ← Infrastructure

The dependency rule: inner layers define abstractions, outer layers implement them.

A typical project structure:

MyApp.Domain/         ← Entities, Value Objects, Interfaces
MyApp.Application/    ← Use Cases, DTOs, Validators
MyApp.Infrastructure/ ← EF Core, External APIs
MyApp.Api/            ← Controllers, Endpoints

Adding a new feature means touching multiple projects: define the entity in Domain, add a command/handler in Application, configure persistence in Infrastructure, add an endpoint in Presentation.

Vertical Slice Architecture in Brief

Vertical Slice Architecture groups everything for a feature together:

Features/
  PlaceOrder/
    PlaceOrderEndpoint.cs
    PlaceOrderCommand.cs
    PlaceOrderHandler.cs
    PlaceOrderValidator.cs
  GetOrderById/
    GetOrderByIdEndpoint.cs
    GetOrderByIdQuery.cs
    GetOrderByIdHandler.cs
    OrderResponse.cs

Adding a new feature means creating a new folder with all the code for that feature. You don't modify existing features.

Key Differences

Coupling Direction

Clean Architecture couples by layer. All repositories live together. All entities live together. Changing how repositories work could affect many features.

Vertical Slices couple by feature. Each feature is independent. Changing the PlaceOrder feature doesn't affect GetOrderById.

Code Reuse

Clean Architecture encourages code reuse across features. A shared OrderRepository serves every use case that needs orders.

Vertical Slices minimize shared code. Each feature can query the database differently. PlaceOrder might use a repository; GetOrderById might use raw Dapper.

Consistency

Clean Architecture enforces consistency. Every feature follows the same patterns - same handler structure, same validation approach, same repository layer.

Vertical Slices allow variation. Simple CRUD features can be simple. Complex features can use rich domain models. Each slice uses what it needs.

Indirection

Clean Architecture adds layers of indirection. To trace a request from endpoint to database, you pass through multiple abstractions: endpoint → handler → repository → DbContext.

Vertical Slices minimize indirection. A simple query handler might go straight to the database with no intermediate abstractions.

Side-by-Side Comparison

Here's how the two approaches stack up, dimension by dimension:

• Organization: Clean Architecture groups by technical layer; vertical slices group by feature.
• Coupling: Clean Architecture couples code within layers; VSA couples code within features.
• Code reuse: high in Clean Architecture (shared services and repositories); intentionally low in VSA.
• Consistency: enforced by Clean Architecture's uniform patterns; optional in VSA, where each slice picks its own level of abstraction.
• New feature effort: Clean Architecture touches multiple projects; VSA adds one folder.
• Learning curve: moderate to high for Clean Architecture; low for VSA.
• Best for: complex domain logic (Clean Architecture) versus features with varied complexity (VSA).
• Main risk: over-engineering simple features (Clean Architecture) versus duplication between features (VSA).

When to Choose Clean Architecture

Choose Clean Architecture when:

1. Your domain is complex. If you have rich business rules, invariants, and domain events, Clean Architecture gives you the structure to manage that complexity.

2. Multiple features share domain logic. If your Order entity is used by PlaceOrder, CancelOrder, RefundOrder, and ShipOrder - sharing it through a Domain layer makes sense.

3. You want strict architectural boundaries. Clean Architecture's layers can be enforced with architecture tests, giving you confidence that infrastructure doesn't leak into your domain.

4. Your team is large and values uniformity. One enforced pattern for every use case keeps dozens of developers producing code that looks the same, which pays off in reviews and onboarding.

5. The project is long-lived. The upfront investment in structure pays off over years as the codebase grows.

When to Choose Vertical Slice Architecture

Choose Vertical Slices when:

1. Features have different complexity. Some endpoints are simple CRUD, others have complex workflows. Vertical slices let each feature use the appropriate level of abstraction.

2. You want fast feature delivery. New features are self-contained. You don't need to understand the entire repository layer to add a new query.

3. Your team is small. Less infrastructure to maintain. Fewer abstractions to navigate.

4. You're building a CRUD-heavy API. If most features are thin wrappers around database operations, layers add overhead without value.

5. You want to minimize coupling. Features that don't share code can be modified and tested in isolation, without touching the rest of the system.

Can You Combine Them?

Yes. And many teams do.

A common approach: use Vertical Slices for feature organization inside a Clean Architecture solution structure.

MyApp.Application/
  Features/
    Orders/
      PlaceOrder/
        PlaceOrderCommand.cs
        PlaceOrderCommandHandler.cs
      GetOrderById/
        GetOrderByIdQuery.cs
        GetOrderByIdQueryHandler.cs
    Customers/
      RegisterCustomer/
        RegisterCustomerCommand.cs
        RegisterCustomerCommandHandler.cs

You get:

• Feature-based organization (vertical slices)
• Layer boundaries enforced at the project level (Clean Architecture)
• Shared domain model for complex business rules
• Independent use cases that don't affect each other

This hybrid approach is what I use in my Pragmatic Clean Architecture course. It gives you the best of both worlds.

Common Mistakes

1. Using Clean Architecture for everything. A simple API with five CRUD endpoints doesn't need four projects and a dozen abstractions.

2. Duplicating everything in Vertical Slices. If three features need the same validation logic, extract it. "Minimize code sharing" doesn't mean "never share code."

3. Choosing based on popularity, not fit. Clean Architecture is more popular in .NET. That doesn't make it the right choice for every project.

4. Thinking it's permanent. You can start with Vertical Slices and introduce layer boundaries as complexity grows. Architecture should evolve with your project. If you're unsure where your project falls, I've written about when to choose Vertical Slice Architecture in more detail.

Takeaway

Clean Architecture and Vertical Slice Architecture solve different problems:

• Clean Architecture manages complexity through layer discipline
• Vertical Slices manage complexity through feature isolation

For complex domains with shared business rules → Clean Architecture. For varied features with different complexity levels → Vertical Slices. For most real projects → a pragmatic combination of both.

Thanks for reading, and stay awesome!

The Problem With Layered Folders

In a traditional layered project, you get folders like this:

Controllers/
  OrdersController.cs
  CustomersController.cs
  ProductsController.cs
Services/
  OrderService.cs
  CustomerService.cs
  ProductService.cs
Repositories/
  OrderRepository.cs
  CustomerRepository.cs
  ProductRepository.cs
Models/
  Order.cs
  Customer.cs
  Product.cs

To understand how "Place Order" works, you jump between 4+ folders. Adding a feature means touching multiple folders. Related code is scattered.

Vertical Slice Architecture fixes this by organizing code around features. This article is about the practical part: the actual folder and solution layout, and how it holds up as the feature count grows.

For what goes inside a slice (the command, handler, and validator structure), see my newsletter issue on structuring vertical slices. Here we stay at the folder level.

The Starting Layout: 5-15 Features

One project, one Features folder, one file per use case:

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    GetOrders.cs
    CancelOrder.cs
    OrdersModule.cs
  Customers/
    RegisterCustomer.cs
    GetCustomer.cs
    UpdateCustomer.cs
    CustomersModule.cs
  Products/
    CreateProduct.cs
    GetProducts.cs
    SearchProducts.cs
    ProductsModule.cs

Everything for "Place Order" is in one file. Everything for orders is in one folder. The *Module.cs file per folder registers that feature group's endpoints (a Carter module or a plain extension method, your choice).

Two naming rules keep this navigable:

• Files are verbs: PlaceOrder.cs, not OrderService.cs. The folder listing reads like a feature list.
• One use case per file: if a file handles two operations, it's two slices pretending to be one.

Full Project Structure

Here's the complete single-project layout I use:

src/
  MyApp.Api/
    Features/
      Orders/
        PlaceOrder.cs
        GetOrder.cs
        GetOrders.cs
        CancelOrder.cs
        UpdateOrderStatus.cs
        OrdersModule.cs
      Customers/
        RegisterCustomer.cs
        GetCustomer.cs
        GetCustomers.cs
        UpdateCustomer.cs
        CustomersModule.cs
      Products/
        CreateProduct.cs
        GetProducts.cs
        SearchProducts.cs
        ProductsModule.cs
    Domain/
      Order.cs
      Customer.cs
      Product.cs
      Common/
        Entity.cs
        Result.cs
        Error.cs
    Data/
      ApplicationDbContext.cs
      Configurations/
        OrderConfiguration.cs
        CustomerConfiguration.cs
        ProductConfiguration.cs
      Migrations/
    Shared/
      Behaviors/
        ValidationBehavior.cs
        LoggingBehavior.cs
      Middleware/
        ExceptionHandlingMiddleware.cs
    Program.cs
tests/
  MyApp.Api.Tests/
    Features/
      Orders/
        PlaceOrderTests.cs
        GetOrderTests.cs
      Customers/
        RegisterCustomerTests.cs

Note that the test project mirrors the Features tree exactly. Finding the tests for a slice should never require a search.

Key Decisions

One Project or Multiple?

Single project - the default for VSA. Keep it simple:

MyApp.Api/
  Features/
  Domain/
  Data/
  Shared/

Multiple projects - only when you need strict compile-time enforcement:

MyApp.Api/          ← entry point
MyApp.Features/     ← all features
MyApp.Domain/       ← domain entities
MyApp.Data/         ← EF Core, migrations

Start with one project. Split when you have a reason. Folder boundaries are cheap to change; project boundaries are not. If you want boundary enforcement without extra projects, architecture tests on namespaces get you most of the way.

Where Do Domain Entities Live?

In a Domain/ folder within the same project:

Domain/
  Order.cs
  LineItem.cs
  Customer.cs
  Product.cs
  Common/
    Entity.cs
    AggregateRoot.cs
    IDomainEvent.cs

Domain entities are shared across features. An Order entity is used by PlaceOrder, GetOrder, and CancelOrder. Slices own their request and response types; they share the domain model underneath.

Where Does the DbContext Live?

In a Data/ folder:

Data/
  ApplicationDbContext.cs
  Configurations/
    OrderConfiguration.cs
    CustomerConfiguration.cs
  Migrations/

EF Core configurations are separate from features - they're infrastructure, not business logic.

Shared Code (Cross-Cutting Concerns)

Pipeline behaviors, middleware, and shared abstractions in Shared/:

Shared/
  Behaviors/
    ValidationBehavior.cs
    LoggingBehavior.cs
    CachingBehavior.cs
  Middleware/
    ExceptionHandlingMiddleware.cs
    RequestLoggingMiddleware.cs
  Abstractions/
    ICommand.cs
    IQuery.cs
    ICacheable.cs
  Extensions/
    ResultExtensions.cs

Keep this folder small and boring. If Shared starts accumulating business logic, a slice boundary is leaking; see cross-cutting concerns in Vertical Slice Architecture for what belongs here and what doesn't.

When Features Get Complex

A simple feature fits in one file. A complex feature graduates to a folder:

Features/
  Orders/
    PlaceOrder/
      PlaceOrderCommand.cs
      PlaceOrderHandler.cs
      PlaceOrderValidator.cs
      PlaceOrderResponse.cs
    GetOrder/
      GetOrderQuery.cs
      GetOrderHandler.cs
    Shared/
      OrderResponse.cs
    OrdersModule.cs

My threshold: split into a folder when the single file grows past roughly 150-200 lines, or when a slice needs private helper classes that would pollute the file.

A feature-local Shared/ folder (like Orders/Shared/) is fine for DTOs reused by two or three sibling slices, like the OrderResponse that both GetOrder and GetOrders return. It's still inside the feature boundary, which is very different from a global shared folder.

Scaling to 50+ Features

A flat Features folder stops working around a few dozen slices. The fix is one more level: group by domain area.

Features/
  Ordering/
    PlaceOrder.cs
    GetOrder.cs
    CancelOrder.cs
    OrderingModule.cs
  Catalog/
    CreateProduct.cs
    SearchProducts.cs
    CatalogModule.cs
  Identity/
    RegisterUser.cs
    Login.cs
    RefreshToken.cs
    IdentityModule.cs
  Shipping/
    CreateShipment.cs
    TrackShipment.cs
    ShippingModule.cs

These groups aren't arbitrary. They mirror bounded contexts, and each one is a candidate module if you later evolve toward a modular monolith. At that point each domain area gets its own project (or set of projects), and the folder structure you already have becomes the module structure. I've written about exactly where vertical slices fit inside a modular monolith.

The practical signals that you've hit this stage:

• You scroll to find anything in Features/
• Two domain areas keep reaching into each other's entities
• Different teams own different feature groups and step on each other in PRs

Restructuring is mechanical: create the domain-area folders, move files, fix namespaces. Do it in one PR before the pain compounds.

Conventions That Keep the Structure Healthy

A folder structure only stays clean if a few conventions back it up:

• Namespace mirrors folder. MyApp.Api.Features.Ordering.PlaceOrder tells you exactly where the file lives. Most IDEs enforce this automatically.
• Handlers are internal. Nothing outside the slice should call a handler directly. The endpoint (or dispatcher) is the only entry point.
• One route prefix per module. OrdersModule owns /api/orders; no other module maps routes under it.
• No slice-to-slice references. If PlaceOrder needs something from Shipping, that's a domain service or a domain event, not a using statement. A couple of architecture tests will hold this line for you.

Takeaway

A practical VSA folder structure:

1. Features folder - one file per use case, named as a verb
2. Domain folder - shared entities and value objects
3. Data folder - DbContext, configurations, migrations
4. Shared folder - pipeline behaviors, middleware, abstractions (keep it boring)
5. Single project to start, split only when you need compile-time boundaries
6. Single-file slices first, folders past ~150-200 lines
7. Domain-area grouping at 50+ features, mirroring bounded contexts

The structure should make it obvious what your application does by reading the feature folder names.

Thanks for reading, and stay awesome!

What Is Carter?

Carter is a library that adds convention-based routing to ASP.NET Core Minimal APIs. It lets you define endpoints in self-contained modules instead of one giant Program.cs.

Combined with Vertical Slice Architecture, Carter gives each feature its own endpoint module, handler, and model - all in one place.

Setting Up Carter

Install the package:

dotnet add package Carter

Register it:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCarter();

builder.Services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(typeof(Program).Assembly);
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
});

builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

var app = builder.Build();

app.MapCarter();
app.Run();

MapCarter() automatically discovers all ICarterModule implementations and registers their routes.

ValidationBehavior is the FluentValidation pipeline behavior that runs each slice's validator before the handler and returns failures as a failed Result. I break it down in validation in Vertical Slice Architecture.

A Feature Slice With Carter

Here's a complete feature slice for placing an order:

// Features/Orders/PlaceOrder.cs
public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<OrderItemRequest> Items) : IRequest<Result<Guid>>;

    public sealed record OrderItemRequest(Guid ProductId, int Quantity);

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId).NotEmpty();
            RuleFor(x => x.Items).NotEmpty();
            RuleForEach(x => x.Items).ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).NotEmpty();
                item.RuleFor(x => x.Quantity).GreaterThan(0);
            });
        }
    }

    public sealed class Handler : IRequestHandler<Command, Result<Guid>>
    {
        private readonly ApplicationDbContext _db;

        public Handler(ApplicationDbContext db) => _db = db;

        public async Task<Result<Guid>> Handle(
            Command request, CancellationToken ct)
        {
            var customer = await _db.Customers
                .FirstOrDefaultAsync(c => c.Id == request.CustomerId, ct);

            if (customer is null)
            {
                return Result.Failure<Guid>(
                    new Error("Customer.NotFound", "Customer not found."));
            }

            var order = new Order
            {
                Id = Guid.NewGuid(),
                CustomerId = request.CustomerId,
                Items = request.Items.Select(i => new OrderItem
                {
                    ProductId = i.ProductId,
                    Quantity = i.Quantity
                }).ToList(),
                CreatedAt = DateTime.UtcNow
            };

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            return order.Id;
        }
    }
}

Now the Carter module:

// Features/Orders/OrdersModule.cs
public class OrdersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders");

        group.MapPost("", async (
            PlaceOrder.Command command,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(command, ct);

            return result.IsSuccess
                ? Results.Created($"/api/orders/{result.Value}", result.Value)
                : result.ToProblemDetails();
        });

        group.MapGet("{id:guid}", async (
            Guid id,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(new GetOrder.Query(id), ct);

            return result.IsSuccess
                ? Results.Ok(result.Value)
                : result.ToProblemDetails();
        });

        group.MapGet("", async (
            int page,
            int pageSize,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(
                new GetOrders.Query(page, pageSize), ct);

            return Results.Ok(result.Value);
        });
    }
}

ToProblemDetails() is a small extension method that maps a failed Result to Results.Problem or Results.ValidationProblem, so every endpoint returns consistent Problem Details responses.

Project Structure

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    GetOrders.cs
    CancelOrder.cs
    OrdersModule.cs
  Customers/
    RegisterCustomer.cs
    GetCustomer.cs
    CustomersModule.cs
  Products/
    CreateProduct.cs
    GetProducts.cs
    ProductsModule.cs

Each feature folder contains:

• One file per use case (command/query + handler + validator)
• One Carter module for routing all endpoints in that domain

Everything for orders lives in Features/Orders/. No jumping between Controllers, Services, Models, and Repositories folders.

Route Groups and Common Configuration

Carter modules support route groups with shared configuration:

public class OrdersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders")
            .RequireAuthorization();

        group.MapPost("", HandlePlaceOrder);
        group.MapGet("{id:guid}", HandleGetOrder);
        group.MapDelete("{id:guid}", HandleCancelOrder)
            .RequireAuthorization("Admin");
    }

    private static async Task<IResult> HandlePlaceOrder(
        PlaceOrder.Command command,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(command, ct);
        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", result.Value)
            : result.ToProblemDetails();
    }

    private static async Task<IResult> HandleGetOrder(
        Guid id,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(new GetOrder.Query(id), ct);
        return result.IsSuccess
            ? Results.Ok(result.Value)
            : result.ToProblemDetails();
    }

    private static async Task<IResult> HandleCancelOrder(
        Guid id,
        ISender sender,
        CancellationToken ct)
    {
        var result = await sender.Send(new CancelOrder.Command(id), ct);
        return result.IsSuccess
            ? Results.NoContent()
            : result.ToProblemDetails();
    }
}

Extract handler methods to keep AddRoutes readable.

Endpoint Filters

If you'd rather handle cross-cutting concerns at the HTTP boundary instead of inside the MediatR pipeline, use endpoint filters. Here's a validation filter that resolves the slice's FluentValidation validator from DI:

public class ValidationFilter<TRequest> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var request = context.Arguments
            .OfType<TRequest>()
            .FirstOrDefault();

        if (request is null)
        {
            return await next(context);
        }

        var validator = context.HttpContext.RequestServices
            .GetService<IValidator<TRequest>>();

        if (validator is not null)
        {
            var result = await validator.ValidateAsync(request);
            if (!result.IsValid)
            {
                return Results.ValidationProblem(result.ToDictionary());
            }
        }

        return await next(context);
    }
}

The filter is generic over the request type, so you apply it per endpoint:

group.MapPost("", HandlePlaceOrder)
    .AddEndpointFilter<ValidationFilter<PlaceOrder.Command>>();

Pick one place to validate (pipeline behavior or endpoint filter), not both.

Testing Carter Modules

Because Carter modules are just Minimal API routes, they test like any other endpoint through WebApplicationFactory:

public class OrdersModuleTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public OrdersModuleTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task PlaceOrder_WithInvalidBody_ReturnsProblemDetails()
    {
        var response = await _client.PostAsJsonAsync("/api/orders", new
        {
            CustomerId = Guid.Empty,
            Items = Array.Empty<object>()
        });

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }
}

MapCarter() runs during test host startup, so all modules are discovered exactly as in production. No special test setup for Carter itself.

Why Carter + VSA Works

What the combination buys you:

• Auto-discovery: Carter finds modules automatically, no manual registration in Program.cs
• Feature isolation: each module encapsulates a bounded set of endpoints
• Clean Program.cs: just app.MapCarter() instead of dozens of MapGet/MapPost calls
• Route grouping: share authorization, filters, and tags across related endpoints
• Testability: each handler is independent and easily unit-tested

Carter vs. Plain Minimal APIs

Without Carter, endpoints pile up in Program.cs or require manual extension methods:

// Without Carter - gets messy fast
app.MapPost("/api/orders", HandlePlaceOrder);
app.MapGet("/api/orders/{id}", HandleGetOrder);
app.MapGet("/api/orders", HandleGetOrders);
app.MapPost("/api/customers", HandleRegisterCustomer);
app.MapGet("/api/customers/{id}", HandleGetCustomer);
// ... 50 more lines

With Carter, each module owns its routes. Program.cs stays clean.

To be fair, Carter isn't the only way to get there. You can build the same auto-discovery yourself with an IEndpoint interface and assembly scanning, which I showed in automatically registering Minimal APIs. Choose Carter if you want the convention ready-made and don't mind a third-party dependency in your API layer; roll your own if you'd rather own those 30 lines of reflection.

Carter or Roll Your Own?

Carter doesn't change what a vertical slice is. It standardizes how a slice exposes its routes: each feature folder gets a module, each module owns its endpoints, and Program.cs shrinks to app.MapCarter().

If you want that convention ready-made, use Carter. If you'd rather avoid the dependency, the IEndpoint approach gets you the same result for 30 lines of your own code. Either way, if you're building with Minimal APIs and vertical slices, the endpoints should end up where they belong: inside the slice.

Thanks for reading, and stay awesome!

Validation Belongs in the Slice

In Vertical Slice Architecture, each feature is self-contained. The validator lives next to the handler - not in a separate "Validators" folder across the project.

Features/
  Orders/
    PlaceOrder.cs        ← Command + Handler + Validator
    GetOrder.cs
    CancelOrder.cs

The Validator

Use FluentValidation to define rules:

public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<OrderItemRequest> Items) : IRequest<Result<Guid>>;

    public sealed record OrderItemRequest(
        Guid ProductId,
        int Quantity,
        decimal UnitPrice);

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId)
                .NotEmpty()
                .WithMessage("Customer ID is required.");

            RuleFor(x => x.Items)
                .NotEmpty()
                .WithMessage("At least one item is required.");

            RuleForEach(x => x.Items).ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).NotEmpty();
                item.RuleFor(x => x.Quantity)
                    .GreaterThan(0)
                    .WithMessage("Quantity must be positive.");
                item.RuleFor(x => x.UnitPrice)
                    .GreaterThan(0)
                    .WithMessage("Price must be positive.");
            });
        }
    }

    public sealed class Handler : IRequestHandler<Command, Result<Guid>>
    {
        private readonly ApplicationDbContext _db;

        public Handler(ApplicationDbContext db) => _db = db;

        public async Task<Result<Guid>> Handle(
            Command request, CancellationToken ct)
        {
            // No input validation here - the pipeline already ran it
            var order = Order.Create(request.CustomerId, request.Items);

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            return order.Id;
        }
    }
}

The command, validator, and handler are all in one file. Everything about "Place Order" is in one place.

Automatic Validation With a Pipeline Behavior

Instead of calling the validator manually in every handler, use a MediatR pipeline behavior. This is the same approach I showed for CQRS validation with MediatR and FluentValidation:

public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(
        IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);

        var validationResults = await Task.WhenAll(
            _validators.Select(v => v.ValidateAsync(context, ct)));

        var failures = validationResults
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await next();
    }
}

Register it:

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddOpenBehavior(typeof(ValidationBehavior<,>));
});

builder.Services.AddValidatorsFromAssembly(
    typeof(Program).Assembly);

Every request that has a matching IValidator<T> is validated automatically before reaching the handler. Pair this throwing variant with a global exception handler that turns ValidationException into a 400 Problem Details response.

Result-Based Validation

Instead of throwing exceptions, return validation errors as a Result:

public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
    where TResponse : Result
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(
        IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);

        var validationResults = await Task.WhenAll(
            _validators.Select(v => v.ValidateAsync(context, ct)));

        var errors = validationResults
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .Select(f => new Error(f.PropertyName, f.ErrorMessage))
            .ToArray();

        if (errors.Length != 0)
            return (TResponse)(object)Result.Failure(
                new ValidationError(errors));

        return await next();
    }
}

The handler never runs if validation fails. The endpoint returns a 400 response with the validation errors.

One wrinkle to be aware of: the cast at the end only works when TResponse is the non-generic Result. For handlers returning Result<T>, a complete implementation creates the typed failure through a static factory or a small piece of reflection. It's a one-time cost in the behavior, and every slice benefits.

Input Validation vs Domain Validation

There are two layers of validation in any application:

Input validation (FluentValidation) - checks data format and presence:

• Is the email format valid?
• Is the quantity positive?
• Is the required field present?

Domain validation (domain invariants) - checks business rules:

• Can this customer place an order?
• Is this product in stock?
• Does the discount code apply?

// Input validation (FluentValidation) - runs BEFORE the handler
public sealed class Validator : AbstractValidator<Command>
{
    public Validator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(x => x.ProductId).NotEmpty();
            item.RuleFor(x => x.Quantity).GreaterThan(0);
        });
    }
}

// Domain validation - runs INSIDE the handler
public sealed class Handler : IRequestHandler<Command, Result<Guid>>
{
    private readonly ApplicationDbContext _db;

    public Handler(ApplicationDbContext db) => _db = db;

    public async Task<Result<Guid>> Handle(
        Command request, CancellationToken ct)
    {
        var productIds = request.Items.Select(i => i.ProductId).ToList();

        var products = await _db.Products
            .Where(p => productIds.Contains(p.Id))
            .ToDictionaryAsync(p => p.Id, ct);

        foreach (var item in request.Items)
        {
            if (!products.TryGetValue(item.ProductId, out var product))
                return Result.Failure<Guid>(ProductErrors.NotFound);

            if (product.StockQuantity < item.Quantity)
                return Result.Failure<Guid>(ProductErrors.InsufficientStock);
        }

        // Domain checks passed - create the order
        var order = Order.Create(request.CustomerId, request.Items);

        _db.Orders.Add(order);
        await _db.SaveChangesAsync(ct);

        return order.Id;
    }
}

Input validation rejects obviously bad data. Domain validation enforces business rules.

Async Validators

Some validation requires database access:

public sealed class Validator : AbstractValidator<Command>
{
    public Validator(ApplicationDbContext db)
    {
        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress()
            .MustAsync(async (email, ct) =>
                !await db.Users.AnyAsync(u => u.Email == email, ct))
            .WithMessage("Email is already registered.");
    }
}

Use async validators sparingly. Most input validation should be synchronous. Save database checks for the handler when possible.

Testing Your Validators

Co-located validators are trivially testable with FluentValidation's built-in TestHelper:

public class PlaceOrderValidatorTests
{
    private readonly PlaceOrder.Validator _validator = new();

    [Fact]
    public void Should_Fail_When_Items_Are_Empty()
    {
        var command = new PlaceOrder.Command(Guid.NewGuid(), []);

        var result = _validator.TestValidate(command);

        result.ShouldHaveValidationErrorFor(x => x.Items);
    }

    [Fact]
    public void Should_Pass_For_Valid_Command()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 2, 10m)]);

        var result = _validator.TestValidate(command);

        result.ShouldNotHaveAnyValidationErrors();
    }
}

TestValidate gives you assertion helpers that point at the exact rule that failed. These tests run in microseconds, so cover every rule. More on the broader strategy in testing vertical slices.

Endpoint Error Mapping

Map validation errors to Problem Details:

app.MapPost("/api/orders", async (
    PlaceOrder.Command command,
    ISender sender) =>
{
    var result = await sender.Send(command);

    return result.Match(
        onSuccess: id => Results.Created($"/api/orders/{id}", id),
        onFailure: error => error switch
        {
            ValidationError ve => Results.ValidationProblem(
                ve.Errors.GroupBy(e => e.Code)
                    .ToDictionary(
                        g => g.Key,
                        g => g.Select(e => e.Description).ToArray())),
            _ => Results.Problem(
                detail: error.Description,
                statusCode: StatusCodes.Status400BadRequest)
        });
});

Takeaway

Validation in Vertical Slice Architecture:

1. Co-locate validators with features - same file as the command and handler
2. Pipeline behavior validates automatically before the handler runs
3. Input validation (format, presence) goes in FluentValidation
4. Domain validation (business rules) stays in the handler or domain model
5. Throw or return Results - both work, pick one convention and stay consistent
6. Map to Problem Details for consistent API error responses

Validation is a cross-cutting concern - handle it once in the pipeline, not in every handler.

Thanks for reading, and stay awesome!

Testing Slices, Not Layers

In Vertical Slice Architecture, each feature is self-contained - request, handler, validation, persistence. This means your tests should be organized by feature, not by layer.

Instead of:

• OrderRepositoryTests
• OrderServiceTests
• OrderControllerTests

You write:

• PlaceOrderTests
• GetOrderTests
• CancelOrderTests

Each test covers one slice from input to output.

Unit Testing a Handler

The simplest test targets the handler directly:

public class PlaceOrderTests
{
    private readonly ApplicationDbContext _db;
    private readonly PlaceOrder.Handler _handler;

    public PlaceOrderTests()
    {
        _db = CreateInMemoryDbContext();
        _handler = new PlaceOrder.Handler(_db);
    }

    [Fact]
    public async Task Should_Create_Order_With_Valid_Request()
    {
        // Arrange
        var customer = new Customer { Id = Guid.NewGuid(), Name = "John" };
        _db.Customers.Add(customer);
        await _db.SaveChangesAsync();

        var command = new PlaceOrder.Command(
            customer.Id,
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 2)]);

        // Act
        var result = await _handler.Handle(command, CancellationToken.None);

        // Assert
        result.IsSuccess.Should().BeTrue();
        var order = await _db.Orders.FirstAsync();
        order.CustomerId.Should().Be(customer.Id);
        order.Items.Should().HaveCount(1);
    }

    [Fact]
    public async Task Should_Fail_When_Customer_Not_Found()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 1)]);

        var result = await _handler.Handle(command, CancellationToken.None);

        result.IsSuccess.Should().BeFalse();
        result.Error.Code.Should().Be("Customer.NotFound");
    }

    private static ApplicationDbContext CreateInMemoryDbContext()
    {
        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
            .UseInMemoryDatabase(Guid.NewGuid().ToString())
            .Options;

        return new ApplicationDbContext(options);
    }
}

This tests business logic without HTTP, serialization, or middleware.

One caveat: the in-memory DbContext keeps these tests fast, but it doesn't enforce constraints or translate real SQL. That's an acceptable trade for handler logic tests. For query-heavy slices, prefer the Testcontainers approach below (I compare the options in testing EF Core repositories).

Testing Validation

Test validators separately - they're fast and don't need infrastructure:

public class PlaceOrderValidatorTests
{
    private readonly PlaceOrder.Validator _validator = new();

    [Fact]
    public void Should_Fail_When_CustomerId_Is_Empty()
    {
        var command = new PlaceOrder.Command(
            Guid.Empty,
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 1)]);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeFalse();
        result.Errors.Should().Contain(e =>
            e.PropertyName == nameof(PlaceOrder.Command.CustomerId));
    }

    [Fact]
    public void Should_Fail_When_Items_Empty()
    {
        var command = new PlaceOrder.Command(Guid.NewGuid(), []);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeFalse();
    }

    [Fact]
    public void Should_Pass_With_Valid_Command()
    {
        var command = new PlaceOrder.Command(
            Guid.NewGuid(),
            [new PlaceOrder.OrderItemRequest(Guid.NewGuid(), 3)]);

        var result = _validator.Validate(command);

        result.IsValid.Should().BeTrue();
    }
}

Integration Testing With WebApplicationFactory

For end-to-end slice testing, use WebApplicationFactory:

public class PlaceOrderEndpointTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    private readonly HttpClient _client;

    public PlaceOrderEndpointTests(
        WebApplicationFactory<Program> factory)
    {
        _factory = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                // Replace real DB with test container or in-memory
                services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
                services.AddDbContext<ApplicationDbContext>(options =>
                    options.UseInMemoryDatabase("test"));
            });
        });

        _client = _factory.CreateClient();
    }

    [Fact]
    public async Task PlaceOrder_Returns_Created()
    {
        // The handler rejects unknown customers, so seed one first
        var customerId = await SeedCustomerAsync();

        var request = new
        {
            CustomerId = customerId,
            Items = new[]
            {
                new { ProductId = Guid.NewGuid(), Quantity = 2 }
            }
        };

        var response = await _client.PostAsJsonAsync(
            "/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.Created);
    }

    [Fact]
    public async Task PlaceOrder_Returns_BadRequest_For_Empty_Items()
    {
        var request = new
        {
            CustomerId = Guid.NewGuid(),
            Items = Array.Empty<object>()
        };

        var response = await _client.PostAsJsonAsync(
            "/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }

    private async Task<Guid> SeedCustomerAsync()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();

        var customer = new Customer { Id = Guid.NewGuid(), Name = "Test" };
        db.Customers.Add(customer);
        await db.SaveChangesAsync();

        return customer.Id;
    }
}

This tests the full HTTP pipeline - routing, model binding, validation, handler, persistence, and response serialization.

Integration Testing With Testcontainers

For realistic tests against a real database, use Testcontainers:

public class OrderApiTests : IAsyncLifetime
{
    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
        .WithImage("postgres:16-alpine")
        .Build();

    private WebApplicationFactory<Program> _factory = null!;
    private HttpClient _client = null!;

    public async Task InitializeAsync()
    {
        await _postgres.StartAsync();

        _factory = new WebApplicationFactory<Program>()
            .WithWebHostBuilder(builder =>
            {
                builder.ConfigureServices(services =>
                {
                    services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
                    services.AddDbContext<ApplicationDbContext>(options =>
                        options.UseNpgsql(_postgres.GetConnectionString()));
                });
            });

        _client = _factory.CreateClient();

        // Apply migrations
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();
        await db.Database.MigrateAsync();
    }

    [Fact]
    public async Task Full_Order_Lifecycle()
    {
        var customerId = await SeedCustomerAsync();

        // Place order
        var placeResponse = await _client.PostAsJsonAsync(
            "/api/orders",
            new
            {
                CustomerId = customerId,
                Items = new[]
                {
                    new { ProductId = Guid.NewGuid(), Quantity = 2 }
                }
            });
        placeResponse.StatusCode.Should().Be(HttpStatusCode.Created);

        var orderId = await placeResponse.Content
            .ReadFromJsonAsync<Guid>();

        // Get order
        var getResponse = await _client.GetAsync(
            $"/api/orders/{orderId}");
        getResponse.StatusCode.Should().Be(HttpStatusCode.OK);

        // Cancel order
        var cancelResponse = await _client.DeleteAsync(
            $"/api/orders/{orderId}");
        cancelResponse.StatusCode.Should().Be(HttpStatusCode.NoContent);
    }

    private async Task<Guid> SeedCustomerAsync()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider
            .GetRequiredService<ApplicationDbContext>();

        var customer = new Customer { Id = Guid.NewGuid(), Name = "Test" };
        db.Customers.Add(customer);
        await db.SaveChangesAsync();

        return customer.Id;
    }

    public async Task DisposeAsync()
    {
        await _factory.DisposeAsync();
        await _postgres.DisposeAsync();
    }
}

Where Mocks Still Fit

Slices reduce the need for mocking, but they don't eliminate it. External systems (payment gateways, email providers, third-party APIs) should still be replaced with test doubles, even in integration tests:

var factory = new WebApplicationFactory<Program>()
    .WithWebHostBuilder(builder =>
    {
        builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<IPaymentGateway>();
            services.AddScoped<IPaymentGateway, FakePaymentGateway>();
        });
    });

The rule I follow: fake what you don't own (external services), keep what you do own (your database, your handlers, your validation) real. That way a passing slice test means the feature genuinely works, minus only the third-party call you can't control anyway.

Guarding Slice Independence

One more test category worth having: a few architecture tests that keep slices from quietly coupling to each other. A PlaceOrder handler reaching into Features.Shipping internals is exactly the kind of erosion that's invisible in code review. I cover the setup in architecture testing in .NET; two or three rules per feature group are enough.

Test Organization

Mirror the feature structure:

Features/
  Orders/
    PlaceOrder.cs
    GetOrder.cs
    CancelOrder.cs
tests/
  Features/
    Orders/
      PlaceOrderTests.cs
      PlaceOrderValidatorTests.cs
      GetOrderTests.cs
      CancelOrderTests.cs

Each test file tests one slice. Finding the tests for a feature is trivial.

What to Test at Each Level

Three levels, each with a distinct job:

• Validator tests: input validation rules. Pure logic, run in microseconds.
• Handler unit tests: business logic in isolation. Fast, no HTTP.
• Integration tests: the full HTTP pipeline against a real database. Slower, but they prove the slice actually works.

Because a slice is a complete feature, integration tests here carry more weight than in layered architectures. Don't be afraid to have plenty of them; that's what I do instead of the classic test pyramid. A slice test that goes HTTP-to-database catches serialization bugs, validation wiring, and query errors in one shot.

Takeaway

Testing vertical slices in .NET:

1. Organize tests by feature, not by layer
2. Unit test handlers with in-memory DbContext for fast feedback
3. Unit test validators separately - they're pure logic
4. Integration test with WebApplicationFactory for full HTTP pipeline
5. Use Testcontainers for realistic database tests
6. Lean on integration tests - a slice test proves the whole feature works

Each slice is independently testable. That's the power of vertical slices.

Thanks for reading, and stay awesome!

The Problem With Layer-Based Organization

Most .NET projects start like this:

Controllers/
    OrdersController.cs
    CustomersController.cs
    ProductsController.cs
Services/
    OrderService.cs
    CustomerService.cs
    ProductService.cs
Models/
    Order.cs
    Customer.cs
    Product.cs
DTOs/
    OrderRequest.cs
    OrderResponse.cs
    CustomerRequest.cs
Validators/
    OrderValidator.cs
    CustomerValidator.cs

To work on one feature (placing an order), you touch files in 5+ folders. To understand a feature, you jump between directories piecing together how OrdersController calls OrderService which uses Order and OrderRequest.

This is organizing by layer - it groups files by what they are (controller, service, model), not by what they do.

Feature Folders: Organize by What Code Does

Feature folders flip the structure. Everything related to a feature lives together:

Features/
    Orders/
        PlaceOrder/
            PlaceOrderEndpoint.cs
            PlaceOrderCommand.cs
            PlaceOrderCommandHandler.cs
            PlaceOrderRequest.cs
            PlaceOrderResponse.cs
            PlaceOrderValidator.cs
        CancelOrder/
            CancelOrderEndpoint.cs
            CancelOrderCommand.cs
            CancelOrderCommandHandler.cs
        GetOrderById/
            GetOrderByIdEndpoint.cs
            GetOrderByIdQuery.cs
            GetOrderByIdQueryHandler.cs
            OrderResponse.cs
    Customers/
        RegisterCustomer/
            RegisterCustomerEndpoint.cs
            RegisterCustomerCommand.cs
            RegisterCustomerCommandHandler.cs
        GetCustomer/
            GetCustomerEndpoint.cs
            GetCustomerQuery.cs

To work on "Place Order," you open one folder. Everything is there. No jumping between directories.

This is how Vertical Slice Architecture and Screaming Architecture naturally organize code.

Implementing Feature Folders

Step 1: Create the Feature Structure

Each feature gets its own folder with everything it needs:

// Features/Orders/PlaceOrder/PlaceOrderCommand.cs
public sealed record PlaceOrderCommand(
    Guid CustomerId,
    List<OrderItemRequest> Items) : ICommand<Guid>;

// Features/Orders/PlaceOrder/PlaceOrderCommandHandler.cs
public sealed class PlaceOrderCommandHandler(
    IOrderRepository orderRepository,
    IUnitOfWork unitOfWork)
    : ICommandHandler<PlaceOrderCommand, Guid>
{
    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);
        orderRepository.Add(order);
        await unitOfWork.SaveChangesAsync(ct);
        return order.Id;
    }
}

// Features/Orders/PlaceOrder/PlaceOrderEndpoint.cs
public static class PlaceOrderEndpoint
{
    public static void Map(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/orders", async (
            PlaceOrderRequest request,
            ICommandHandler<PlaceOrderCommand, Guid> handler,
            CancellationToken ct) =>
        {
            var command = new PlaceOrderCommand(request.CustomerId, request.Items);
            var result = await handler.Handle(command, ct);

            return result.IsSuccess
                ? Results.Created($"/api/orders/{result.Value}", result.Value)
                : result.ToProblemDetails();
        });
    }
}

// Features/Orders/PlaceOrder/PlaceOrderValidator.cs
public sealed class PlaceOrderValidator : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
    }
}

The ICommand and ICommandHandler abstractions are the thin CQRS interfaces I defined in CQRS Pattern: The Way It Should Have Been From the Start.

Step 2: Auto-Register Endpoints

Scan for all endpoint classes and register them:

public static class EndpointRegistration
{
    public static void MapFeatureEndpoints(this IEndpointRouteBuilder app)
    {
        var endpointTypes = typeof(Program).Assembly
            .GetTypes()
            .Where(t => t.GetMethods(BindingFlags.Public | BindingFlags.Static)
                .Any(m => m.Name == "Map" &&
                    m.GetParameters().Length == 1 &&
                    m.GetParameters()[0].ParameterType == typeof(IEndpointRouteBuilder)));

        foreach (var type in endpointTypes)
        {
            var method = type.GetMethod("Map",
                BindingFlags.Public | BindingFlags.Static,
                [typeof(IEndpointRouteBuilder)]);

            method?.Invoke(null, [app]);
        }
    }
}

// Program.cs
app.MapFeatureEndpoints();

Step 3: Register Handlers

Use assembly scanning with the Scrutor library, so a new slice never means editing Program.cs:

dotnet add package Scrutor

builder.Services.Scan(scan => scan
    .FromAssemblyOf<PlaceOrderCommandHandler>()
    .AddClasses(c => c.AssignableTo(typeof(ICommandHandler<,>)))
    .AsImplementedInterfaces()
    .WithScopedLifetime()
    .AddClasses(c => c.AssignableTo(typeof(IQueryHandler<,>)))
    .AsImplementedInterfaces()
    .WithScopedLifetime());

One File or One Folder per Feature?

There are two popular granularities, and both are fine:

Folder per operation (shown above): PlaceOrder/ contains five or six small files. Best when slices carry validators, mappers, and multiple DTOs.

Single file per operation: the whole slice lives in PlaceOrder.cs as a static class with nested types:

// Features/Orders/PlaceOrder.cs
public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId, List<OrderItemRequest> Items) : ICommand<Guid>;

    public sealed class Validator : AbstractValidator<Command> { /* ... */ }

    internal sealed class Handler : ICommandHandler<Command, Guid> { /* ... */ }

    public static void Map(IEndpointRouteBuilder app) { /* ... */ }
}

The single-file style keeps the entire feature on one screen and makes names collision-free (PlaceOrder.Command, CancelOrder.Command). The static Map method keeps the same shape as before, so the endpoint scanner from Step 2 picks it up unchanged. It's the style I lean toward for small-to-medium slices, and I've written more about structuring vertical slices if you want the full reasoning.

Start with one file. Split into a folder when the file gets uncomfortable to scroll.

Feature Folders in Clean Architecture

You can combine feature folders with Clean Architecture:

src/
  MyApp.Domain/
    Orders/
      Order.cs
      OrderLineItem.cs
      IOrderRepository.cs
    Customers/
      Customer.cs
  MyApp.Application/
    Orders/
      PlaceOrder/
        PlaceOrderCommand.cs
        PlaceOrderCommandHandler.cs
        PlaceOrderValidator.cs
      CancelOrder/
        CancelOrderCommand.cs
        CancelOrderCommandHandler.cs
      GetOrderById/
        GetOrderByIdQuery.cs
        GetOrderByIdQueryHandler.cs
        OrderResponse.cs
  MyApp.Infrastructure/
    Persistence/
      Repositories/
        OrderRepository.cs
  MyApp.Api/
    Endpoints/
      Orders/
        PlaceOrderEndpoint.cs
        CancelOrderEndpoint.cs
        GetOrderByIdEndpoint.cs

The Application layer uses feature folders. The Domain layer groups entities by aggregate. The Presentation layer mirrors the Application structure.

When to Use Feature Folders

Feature folders work well when:

• Features are relatively independent
• The team works on features, not layers
• You want code locality (related code close together)
• You're using CQRS (commands and queries naturally form features)

Stick with layers when:

• There's extensive code sharing between features
• The project is very small (5-10 files total)
• Your team is more comfortable with the traditional structure

Shared Code

Some code is truly shared - domain entities, base classes, common helpers. Put these in a Common or Shared folder:

Features/
    Orders/
        PlaceOrder/...
        CancelOrder/...
    Customers/...
Common/
    Domain/
        Entity.cs
        ValueObject.cs
        AggregateRoot.cs
    Results/
        Result.cs
        Error.cs

Keep the shared folder minimal. If code is only used by one feature, it belongs in that feature's folder. When two features start needing the same logic, resist the reflex to abstract immediately; I've written about where shared logic should live, and the short answer is: extract when the duplication hurts, not when it merely exists.

Migrating an Existing Codebase

You don't need a rewrite to adopt feature folders. The incremental path:

1. Create the Features folder next to your existing Controllers/Services folders.
2. Move one feature end to end. Pick a small, actively developed one. Pull its controller action, service method, DTOs, and validator into a feature folder, collapsing the service and repository indirection where it adds nothing.
3. Ship it. The old layers and the new folder coexist fine; routing doesn't care where files live.
4. Repeat opportunistically. Migrate features when you touch them for other reasons. Untouched code stays where it is.

The biggest friction is usually psychological, not technical: the codebase looks "inconsistent" during the transition. That's fine. A consistent structure that hides features is worse than a mixed one that's converging on clarity.

Stop Grouping by Layer

Feature folders organize code by business capability instead of technical concern. Every file related to placing an order lives in the PlaceOrder folder.

The result: faster navigation, fewer merge conflicts, and code that screams what the application does.

Stop grouping by layer. Start grouping by feature.

Thanks for reading, and stay awesome!

The Duplication Problem

In Vertical Slice Architecture, each feature is self-contained. But certain behaviors cut across every slice - validation, logging, caching, authorization, transaction management.

You don't want to copy-paste these into every handler. That would defeat the purpose. And this question is really a special case of a broader one I keep coming back to: where does the shared logic live in a sliced codebase?

MediatR Pipeline Behaviors

The most common solution is MediatR pipeline behaviors. They wrap every request handler automatically.

Validation Behavior

Validate every command before the handler executes:

public class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
        {
            return await next();
        }

        var context = new ValidationContext<TRequest>(request);

        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(r => r.Errors)
            .Where(f => f is not null)
            .ToList();

        if (failures.Count != 0)
        {
            throw new ValidationException(failures);
        }

        return await next();
    }
}

Each slice just defines a validator:

// Features/Orders/PlaceOrder.cs
public sealed class Validator : AbstractValidator<Command>
{
    public Validator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
    }
}

The behavior picks it up automatically - zero wiring per slice.

Logging Behavior

Log every request entry, exit, and duration:

public class LoggingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(
        ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    {
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var requestName = typeof(TRequest).Name;
        _logger.LogInformation("Handling {RequestName}", requestName);

        var sw = Stopwatch.StartNew();
        var response = await next();
        sw.Stop();

        _logger.LogInformation(
            "Handled {RequestName} in {ElapsedMs}ms",
            requestName, sw.ElapsedMilliseconds);

        return response;
    }
}

Transaction Behavior

Wrap commands in a database transaction. The ICommand constraint uses the marker interface from combining vertical slices with CQRS:

public class TransactionBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICommand<TResponse>
{
    private readonly ApplicationDbContext _db;

    public TransactionBehavior(ApplicationDbContext db)
    {
        _db = db;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        await using var transaction =
            await _db.Database.BeginTransactionAsync(ct);

        try
        {
            var response = await next();
            await transaction.CommitAsync(ct);
            return response;
        }
        catch
        {
            await transaction.RollbackAsync(ct);
            throw;
        }
    }
}

Notice the constraint ICommand<TResponse> - this behavior only wraps commands, not queries. Queries don't need transactions.

Caching Behavior

Cache query results:

public interface ICacheable
{
    string CacheKey { get; }
    TimeSpan? Expiration { get; }
}

public class CachingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>, ICacheable
{
    private readonly IDistributedCache _cache;

    public CachingBehavior(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var cachedResult = await _cache.GetStringAsync(request.CacheKey, ct);
        if (cachedResult is not null)
        {
            return JsonSerializer.Deserialize<TResponse>(cachedResult)!;
        }

        var response = await next();

        await _cache.SetStringAsync(
            request.CacheKey,
            JsonSerializer.Serialize(response),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow =
                    request.Expiration ?? TimeSpan.FromMinutes(5)
            },
            ct);

        return response;
    }
}

Opt in per query:

public sealed record Query(Guid Id)
    : IRequest<ProductResponse>, ICacheable
{
    public string CacheKey => $"product-{Id}";
    public TimeSpan? Expiration => TimeSpan.FromMinutes(10);
}

Only queries that implement ICacheable get cached. The behavior ignores everything else.

Registration

Register all behaviors in order:

services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(typeof(Program).Assembly);
    config.AddOpenBehavior(typeof(LoggingBehavior<,>));
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
    config.AddOpenBehavior(typeof(TransactionBehavior<,>));
    config.AddOpenBehavior(typeof(CachingBehavior<,>));
});

Order matters. Logging wraps validation, which wraps transaction, which wraps caching.

Pitfalls to Watch For

A few ways this setup bites in practice:

• Behavior order bugs are silent. If you register CachingBehavior before TransactionBehavior, a cached response can be returned without the transaction ever opening - which is correct for queries but masks a misconfigured command that accidentally implements ICacheable. Review the registration order whenever you add a behavior.
• Caching failures, not just successes. The caching behavior above serializes whatever the handler returns, including a failed Result. Add a check so only successful responses get cached, or you'll serve a cached error for ten minutes.
• Transactions around everything. Wrapping every command in an explicit transaction is redundant when the handler makes a single SaveChangesAsync call (EF Core already wraps that in a transaction). Reserve the transaction behavior for handlers that perform multiple save operations.
• Behavior sprawl. Every behavior runs on every matching request. Ten behaviors deep, debugging a request means stepping through ten wrappers. Keep the pipeline short and boring.

Pipeline Behaviors Without MediatR

If you've moved off MediatR (or never adopted it), the same pattern works as decorators over your own handler interfaces. Define ICommandHandler<TCommand, TResponse>, then register decorators (Scrutor's Decorate makes this one line per behavior). The mechanics change; the idea (cross-cutting logic wraps the handler, slices stay clean) doesn't.

Endpoint Filters (Alternative)

If you prefer not to use MediatR, ASP.NET Core endpoint filters handle cross-cutting concerns at the HTTP layer:

public class ValidationFilter<TRequest> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var request = context.Arguments
            .OfType<TRequest>()
            .FirstOrDefault();

        if (request is null)
        {
            return await next(context);
        }

        var validator = context.HttpContext.RequestServices
            .GetService<IValidator<TRequest>>();

        if (validator is not null)
        {
            var result = await validator.ValidateAsync(request);
            if (!result.IsValid)
            {
                return Results.ValidationProblem(
                    result.ToDictionary());
            }
        }

        return await next(context);
    }
}

Base Handler Classes (Use Sparingly)

Another option - a base class for shared handler logic:

public abstract class BaseHandler
{
    protected readonly ApplicationDbContext Db;
    protected readonly ICurrentUserService CurrentUser;

    protected BaseHandler(
        ApplicationDbContext db,
        ICurrentUserService currentUser)
    {
        Db = db;
        CurrentUser = currentUser;
    }
}

I generally avoid this. It creates coupling and makes the inheritance hierarchy grow. Pipeline behaviors are more flexible.

The Pattern Summary

Here's the mapping I use, concern by concern:

• Validation: pipeline behavior + FluentValidation. Applies to every request that has a validator; slices without one pass through untouched.
• Logging: pipeline behavior. Applies to all requests.
• Transactions: pipeline behavior constrained to ICommand. Write operations only.
• Caching: pipeline behavior + ICacheable marker. Opt-in per query.
• Authorization: pipeline behavior or endpoint filter, declared per request.
• Error handling: a global exception handler at the HTTP boundary, so handlers never need try-catch blocks for presentation concerns.

Takeaway

Cross-cutting concerns in Vertical Slice Architecture are solved with:

1. Pipeline behaviors - wrap every handler automatically
2. Marker interfaces - opt in to specific behaviors (ICacheable, ICommand)
3. Endpoint filters - HTTP-level concerns
4. Convention over configuration - validators are discovered, not registered manually

Each slice stays focused on its feature. The pipeline handles everything else.

Thanks for reading, and stay awesome!

Why CQRS + VSA Works

CQRS separates reads from writes. Vertical Slice Architecture organizes code by feature. Together, each command and query becomes an independent slice with its own data access strategy.

• Commands use EF Core with the change tracker
• Queries use Dapper or raw SQL for performance
• Each slice picks the tool that fits

Project Structure

Features/
  Orders/
    Commands/
      PlaceOrder.cs
      CancelOrder.cs
      UpdateOrderStatus.cs
    Queries/
      GetOrder.cs
      GetOrders.cs
      SearchOrders.cs
    OrdersModule.cs

Or flatten it when the feature count is small:

Features/
  Orders/
    PlaceOrder.cs          ← Command
    CancelOrder.cs         ← Command
    GetOrder.cs            ← Query
    GetOrders.cs           ← Query

Command Slice

A command changes state:

public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<ItemRequest> Items) : IRequest<Result<Guid>>;

    public sealed record ItemRequest(
        Guid ProductId, int Quantity);

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId).NotEmpty();
            RuleFor(x => x.Items).NotEmpty();
            RuleForEach(x => x.Items).ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).NotEmpty();
                item.RuleFor(x => x.Quantity).GreaterThan(0);
            });
        }
    }

    public sealed class Handler : IRequestHandler<Command, Result<Guid>>
    {
        private readonly ApplicationDbContext _db;

        public Handler(ApplicationDbContext db) => _db = db;

        public async Task<Result<Guid>> Handle(
            Command request, CancellationToken ct)
        {
            var order = Order.Create(
                request.CustomerId,
                request.Items.Select(i =>
                    new LineItem(i.ProductId, i.Quantity)).ToList());

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            return order.Id;
        }
    }
}

Commands go through EF Core - the change tracker handles inserts, updates, and domain event dispatch.

Query Slice

A query reads data without side effects:

public static class GetOrder
{
    public sealed record Query(Guid OrderId) : IRequest<OrderResponse?>;

    public sealed record OrderResponse(
        Guid Id,
        string Status,
        decimal TotalAmount,
        DateTime CreatedAt,
        List<LineItemResponse> Items);

    public sealed record LineItemResponse(
        Guid ProductId,
        int Quantity,
        decimal UnitPrice);

    // Intermediate row type - Dapper maps columns to this,
    // since OrderResponse's constructor also expects Items
    private sealed record OrderRow(
        Guid Id,
        string Status,
        decimal TotalAmount,
        DateTime CreatedAt);

    public sealed class Handler : IRequestHandler<Query, OrderResponse?>
    {
        private readonly IDbConnection _connection;

        public Handler(IDbConnection connection) =>
            _connection = connection;

        public async Task<OrderResponse?> Handle(
            Query query, CancellationToken ct)
        {
            const string sql = """
                SELECT o.Id, o.Status, o.TotalAmount, o.CreatedAt
                FROM Orders o
                WHERE o.Id = @OrderId;

                SELECT li.ProductId, li.Quantity, li.UnitPrice
                FROM LineItems li
                WHERE li.OrderId = @OrderId;
                """;

            using var multi = await _connection
                .QueryMultipleAsync(sql, new { query.OrderId });

            var order = await multi
                .ReadSingleOrDefaultAsync<OrderRow>();

            if (order is null) return null;

            var items = (await multi
                .ReadAsync<LineItemResponse>()).ToList();

            return new OrderResponse(
                order.Id,
                order.Status,
                order.TotalAmount,
                order.CreatedAt,
                items);
        }
    }
}

Queries use Dapper for fast, lightweight reads. No change tracking overhead. No mapping layers.

Typed Abstractions

One caveat before you build everything on IRequest: CQRS is not MediatR. The pattern is the read/write separation; the library is one way to dispatch it. That said, marker interfaces make the separation explicit and unlock selective behaviors:

public interface ICommand<TResponse> : IRequest<TResponse>;
public interface IQuery<TResponse> : IRequest<TResponse>;

public interface ICommandHandler<TCommand, TResponse>
    : IRequestHandler<TCommand, TResponse>
    where TCommand : ICommand<TResponse>;

public interface IQueryHandler<TQuery, TResponse>
    : IRequestHandler<TQuery, TResponse>
    where TQuery : IQuery<TResponse>;

Now you can apply behaviors selectively:

// Validation only runs for commands
public sealed class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICommand<TResponse>
{
    // ...
}

// Caching only runs for queries
public sealed class CachingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IQuery<TResponse>
{
    // ...
}

Endpoint Registration

Map commands and queries to HTTP methods:

public class OrdersModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders").WithTags("Orders");

        // Commands → POST, PUT, DELETE
        group.MapPost("/", async (
            PlaceOrder.Command command, ISender sender) =>
        {
            var result = await sender.Send(command);
            return result.Match(
                id => Results.Created($"/api/orders/{id}", id),
                error => Results.Problem(error.Description));
        });

        group.MapDelete("/{id:guid}", async (
            Guid id, ISender sender) =>
        {
            var result = await sender.Send(
                new CancelOrder.Command(id));
            return result.Match(
                () => Results.NoContent(),
                error => Results.Problem(error.Description));
        });

        // Queries → GET
        group.MapGet("/{id:guid}", async (
            Guid id, ISender sender) =>
        {
            var order = await sender.Send(new GetOrder.Query(id));
            return order is not null
                ? Results.Ok(order)
                : Results.NotFound();
        });

        group.MapGet("/", async (
            [AsParameters] GetOrders.Query query, ISender sender) =>
        {
            var result = await sender.Send(query);
            return Results.Ok(result);
        });
    }
}

Separate Read and Write Models

CQRS lets commands and queries use different data shapes:

// Write model (rich domain entity)
public class Order : AggregateRoot
{
    private readonly List<LineItem> _lineItems = [];
    public OrderStatus Status { get; private set; }
    public Money TotalAmount { get; private set; }

    public void AddLineItem(Guid productId, int quantity, Money price)
    {
        // Business rules...
    }
}

// Read model (flat DTO optimized for display)
public sealed record OrderListItem(
    Guid Id,
    string CustomerName,   // Joined from Customers table
    string Status,
    decimal TotalAmount,
    int ItemCount,          // Computed
    DateTime CreatedAt);

Write models enforce domain invariants. Read models are flat DTOs optimized for the UI.

Scaling: Separate Read Database

For high-traffic applications, CQRS enables separate read and write stores. The write side doesn't change: commands keep going through EF Core to the normalized schema. The read side gets its own denormalized table (or a read replica connection), and the query slice is the only code that needs to know:

public static class GetOrderSummary
{
    // Flat read model, so Dapper maps it directly
    public sealed record OrderSummary(
        Guid Id,
        string Status,
        decimal TotalAmount,
        DateTime CreatedAt);

    public sealed record Query(Guid OrderId) : IQuery<OrderSummary?>;

    public sealed class Handler : IQueryHandler<Query, OrderSummary?>
    {
        private readonly IDbConnection _readDb; // Dapper → read replica

        public Handler(IDbConnection readDb) => _readDb = readDb;

        public async Task<OrderSummary?> Handle(
            Query query, CancellationToken ct)
        {
            const string sql = """
                SELECT Id, Status, TotalAmount, CreatedAt
                FROM OrderSummaries
                WHERE Id = @OrderId;
                """;

            return await _readDb.QuerySingleOrDefaultAsync<OrderSummary>(
                sql, new { query.OrderId });
        }
    }
}

Start with a single database. Split when performance demands it.

Where This Combination Struggles

Two honest caveats before you commit:

• Eventual consistency creeps in early. The moment queries read from a cache or replica, a command's result may not be immediately visible to the next query. Design your UI for it (return the created resource from the command, don't re-query).
• Slice independence is a discipline, not a guarantee. It's tempting to share DTOs between a command and its neighboring query "because they look the same." Resist it. The whole point is that each side can evolve without breaking the other. When slices genuinely need shared logic, pull it out deliberately, which I covered in where the shared logic lives in VSA.

Takeaway

CQRS + Vertical Slice Architecture:

1. Each command and query is its own slice - independent and self-contained
2. Commands use EF Core for change tracking and domain events
3. Queries use Dapper for fast, lightweight reads
4. Pipeline behaviors can target commands or queries selectively
5. Read and write models are separate - optimize each independently
6. Start simple - one database, split read/write stores when needed

The combination gives you the organizational clarity of VSA with the optimization potential of CQRS.

Thanks for reading, and stay awesome!

The Extraction Promise

One of the biggest selling points of a modular monolith is the ability to extract modules into independent microservices when the need arises. But "when the need arises" is dangerously vague.

Extract too early, before the module boundaries are stable, and you end up with a distributed monolith. Wait too long, and extraction becomes a multi-month rewrite.

The key is understanding the signals that tell you extraction is the right move.

Signs a Module Should Be Extracted

Independent Scaling Requirements

If one module needs 10x the compute resources of the rest, deploying everything together wastes resources. A notification module sending millions of emails shouldn't force you to scale the entire application.

Before reaching for extraction, check whether scaling the whole monolith horizontally is cheaper. It often is, until the load asymmetry gets extreme.

Module                   | Avg Load      | Peak Load
-------------------------|---------------|----------
Catalog                  | Low           | Low
Ordering                 | Medium        | Medium
NotificationProcessing   | Low           | Very High  ← extraction candidate
UserManagement           | Low           | Low

Different Deployment Cadences

If one team needs to deploy their module five times a day while the rest deploys weekly, they're blocked by the monolith's deployment cycle. Independent deployment is a microservice benefit that matters here.

Technology Requirements

A module might benefit from a different technology stack. Maybe the search module needs Elasticsearch-native code, or the ML pipeline needs Python. In a monolith, you're locked to .NET for everything.

Fault Isolation

If a bug in one module crashes the entire application, extraction provides fault isolation. The notification module throwing an out-of-memory exception shouldn't take down the ordering module.

Signs You Should NOT Extract

The Boundaries Are Still Shifting

If module boundaries are still changing - endpoints move between modules, shared types keep growing - extraction will lock in the wrong boundaries as network contracts.

Strong Data Coupling

If two modules frequently join each other's data, separating them means replacing SQL joins with API calls. That's a performance and reliability hit. Fix the data isolation first.

You Want to "Try Microservices"

Extracting a module to learn microservices is expensive learning. The modular monolith gives you most of the modularity benefits without the operational complexity.

Small Team

A modular monolith suits teams of roughly 2-15 developers. If your engineering team is still inside that range, the coordination overhead of microservices usually outweighs the benefits. A modular monolith with clear module communication is simpler to operate.

Readiness Checklist

Before extracting, verify these preconditions:

// Your module should already have:

// 1. Clean public API (no direct database access from other modules)
public interface ICatalogModule
{
    Task<ProductResponse> GetProductAsync(Guid productId);
    Task<bool> CheckAvailabilityAsync(Guid productId, int quantity);
    Task ReserveStockAsync(Guid orderId, List<OrderItem> items);
}

// 2. Own database/schema (data isolation enforced)
public class CatalogDbContext : DbContext
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("catalog");
    }
}

// 3. Event-based communication (not synchronous method calls)
public class OrderPlacedEventHandler
    : IIntegrationEventHandler<OrderPlacedIntegrationEvent>
{
    public async Task HandleAsync(
        OrderPlacedIntegrationEvent @event,
        CancellationToken cancellationToken = default) { /* ... */ }
}

The IIntegrationEvent contracts and handler abstractions come from the shared kernel.

If any of these are missing, fix them first. Extraction without these foundations creates a distributed monolith.

The Extraction Process

Step 1: Verify Data Isolation

Ensure the module uses its own database or schema. Query the database to find any cross-module references:

-- Find foreign keys crossing module boundaries (PostgreSQL)
SELECT
    con.conname AS constraint_name,
    child_ns.nspname AS child_schema,
    child.relname AS child_table,
    parent_ns.nspname AS referenced_schema,
    parent.relname AS referenced_table
FROM pg_constraint con
JOIN pg_class child ON con.conrelid = child.oid
JOIN pg_namespace child_ns ON child.relnamespace = child_ns.oid
JOIN pg_class parent ON con.confrelid = parent.oid
JOIN pg_namespace parent_ns ON parent.relnamespace = parent_ns.oid
WHERE con.contype = 'f'
  AND child_ns.nspname <> parent_ns.nspname;

If you find cross-module foreign keys, remove them and replace them with eventual consistency through integration events.

Step 2: Replace In-Process Communication With HTTP/Messaging

Module interfaces that were resolved via dependency injection now need to go over the network.

// Before: In-process call
public class OrderService
{
    private readonly ICatalogModule _catalog;

    public async Task PlaceOrder(PlaceOrderCommand command)
    {
        var available = await _catalog.CheckAvailabilityAsync(
            command.ProductId, command.Quantity);
    }
}

// After: HTTP client call
public class CatalogApiClient : ICatalogModule
{
    private readonly HttpClient _httpClient;

    public CatalogApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<bool> CheckAvailabilityAsync(
        Guid productId, int quantity)
    {
        var response = await _httpClient.GetAsync(
            $"/api/catalog/products/{productId}/availability?quantity={quantity}");

        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<bool>();
    }

    // GetProductAsync and ReserveStockAsync follow the same pattern
}

The key insight: the ICatalogModule interface doesn't change. Only the implementation switches from in-process to HTTP. This is why clean module APIs matter.

The new network hop also brings network failure modes. Wrap the HTTP client with retries and a circuit breaker, and set explicit timeouts. An in-process call could never time out; this one can.

Step 3: Replace In-Memory Events With a Message Broker

If you were using an in-memory event bus, switch to a real broker (RabbitMQ, Azure Service Bus) through a library like MassTransit. The publishing call barely changes (_publishEndpoint is MassTransit's IPublishEndpoint):

// Before: in-process event bus
await _eventBus.PublishAsync(integrationEvent, ct);

// After: message broker publish with MassTransit
await _publishEndpoint.Publish(integrationEvent, ct);

The outbox pattern becomes critical here since network calls to the broker can fail.

Step 4: Deploy Independently

Create a separate deployment pipeline for the extracted module. It gets its own:

• Repository (or folder in a monorepo)
• CI/CD pipeline
• Container/hosting environment
• Database instance

Strangler Fig Approach

Don't extract everything at once. Use the strangler fig pattern:

1. Deploy the new microservice alongside the monolith
2. Route traffic for the extracted module to the new service
3. Keep both running until the new service is proven stable
4. Remove the module from the monolith

This gives you a rollback path if the extraction causes issues.

I walk through this migration in detail in Breaking It Down: How to Migrate Your Modular Monolith to Microservices.

Takeaway

1. Extract when you have concrete scaling, deployment, or fault-isolation needs - not because microservices are trendy.
2. Verify your module has clean APIs, isolated data, and event-based communication before extracting.
3. The module interface stays the same; only the implementation changes from in-process to network calls.
4. Replace in-memory events with a message broker and use the outbox pattern for reliability.
5. Use the strangler fig approach for safe, incremental extraction.
6. If boundaries are unstable or data is tightly coupled, fix the monolith first.

Thanks for reading, and stay awesome!

The Big Rewrite Trap

You have a legacy monolith - spaghetti code, shared database, tangled dependencies. The temptation is to rewrite everything from scratch.

This almost never works. Big rewrites take longer than expected, introduce new bugs, and often get abandoned.

The Strangler Fig pattern offers a better approach. Just like the strangler fig tree gradually envelops its host tree, you gradually replace the legacy system with a Modular Monolith - one module at a time.

The same technique also works for the next step, migrating a modular monolith to microservices. Here I'll focus on the first move: legacy monolith to modular monolith.

How the Strangler Fig Pattern Works

The strategy is simple:

1. Identify a bounded context in the legacy system
2. Build a new module that handles the same functionality
3. Route traffic to the new module instead of the legacy code
4. Remove the old code once migration is complete
5. Repeat for the next bounded context

At any point, the system is fully functional. Some requests go to the new modules, others still hit the legacy code.

Step 1: Add a Routing Layer

You need a seam where each request decides whether the legacy code or the new module handles it.

The cleanest seam is an interface with two implementations, switched by a feature flag:

public class OrderServiceRouter : IOrderService
{
    private readonly LegacyOrderService _legacy;
    private readonly NewOrderModule _newModule;
    private readonly IFeatureManager _features;

    public OrderServiceRouter(
        LegacyOrderService legacy,
        NewOrderModule newModule,
        IFeatureManager features)
    {
        _legacy = legacy;
        _newModule = newModule;
        _features = features;
    }

    public async Task<OrderDto> GetOrderAsync(Guid id)
    {
        if (await _features.IsEnabledAsync("NewOrdersModule"))
        {
            return await _newModule.GetOrderAsync(id);
        }

        return await _legacy.GetOrderAsync(id);
    }
}

Register both implementations and the router in Program.cs:

builder.Services.AddFeatureManagement();

builder.Services.AddScoped<LegacyOrderService>();
builder.Services.AddScoped<NewOrderModule>();
builder.Services.AddScoped<IOrderService, OrderServiceRouter>();

The flag check happens at call time, so flipping the flag takes effect immediately - no redeploy needed. And because the same check routes in both directions, rollback is the same flag flipped back.

If the legacy system is a separate application (not code you can share a process with), the routing layer becomes a reverse proxy like YARP: migrated routes go to the new application, everything else is forwarded to the legacy one. The principle is identical; only the seam moves from an interface to an HTTP route table.

Step 2: Build the First Module

Choose the least coupled, highest-value bounded context. Common good candidates:

• Notifications - clear boundary, few dependencies
• Payments - well-defined interface, critical for business
• User profiles - self-contained data

Build the module with proper module boundaries:

Modules/
  Orders/
    Orders.Application/
    Orders.Domain/
    Orders.Infrastructure/
    Orders.Contracts/
LegacyCode/
  OrdersLegacy/         ← still running
  CustomersLegacy/      ← still running
  ShippingLegacy/       ← still running

The new module has its own:

• Database schema (or separate tables)
• Domain model
• Public API (contracts)

Step 3: Data Migration

The hardest part. You need to migrate data from the legacy schema to the new module's schema.

Option A: Shared Database, New Schema

-- Legacy table (default schema)
SELECT * FROM public.orders;

-- New module table (module schema)
SELECT * FROM orders.orders;

Both schemas coexist in the same database. The new module reads from orders.orders - its own schema. During migration, you sync data between schemas:

public class OrderDataMigrationJob : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private DateTime _lastSync = DateTime.MinValue;

    public OrderDataMigrationJob(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            using var scope = _scopeFactory.CreateScope();
            var legacyDb = scope.ServiceProvider
                .GetRequiredService<LegacyDbContext>();
            var newDb = scope.ServiceProvider
                .GetRequiredService<OrderDbContext>();

            DateTime syncStartedAt = DateTime.UtcNow;

            // Sync legacy orders modified since the last run
            var legacyOrders = await legacyDb.Orders
                .Where(o => o.ModifiedAt > _lastSync)
                .ToListAsync(ct);

            foreach (var legacyOrder in legacyOrders)
            {
                var existing = await newDb.Orders
                    .FirstOrDefaultAsync(o => o.Id == legacyOrder.Id, ct);

                if (existing is null)
                {
                    newDb.Orders.Add(MapToNewModel(legacyOrder));
                }
                else
                {
                    existing.UpdateFrom(legacyOrder);
                }
            }

            await newDb.SaveChangesAsync(ct);
            _lastSync = syncStartedAt;

            await Task.Delay(TimeSpan.FromSeconds(30), ct);
        }
    }
}

A few details that matter here. BackgroundService is a singleton, so the job resolves the scoped DbContext instances through IServiceScopeFactory on every iteration (injecting them directly into the constructor throws at startup). The job records syncStartedAt before querying, so rows modified mid-sync are picked up on the next pass instead of being skipped. MapToNewModel and UpdateFrom are plain mapping helpers that translate legacy columns into the new domain model. Register the job with builder.Services.AddHostedService<OrderDataMigrationJob>();.

Option B: Event-Based Sync

Use domain events or change data capture to keep both systems in sync. Since the legacy code and the new module share a process during the migration, MediatR notifications work well as the sync channel:

// The sync event
public sealed record OrderCreatedEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal Total,
    DateTime CreatedAt) : INotification;

// The legacy code calls this hook after every write
public class LegacyOrderEventPublisher
{
    private readonly IPublisher _publisher;

    public LegacyOrderEventPublisher(IPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task OnOrderCreatedAsync(LegacyOrder order, CancellationToken ct)
    {
        await _publisher.Publish(
            new OrderCreatedEvent(
                order.Id,
                order.CustomerId,
                order.Total,
                order.CreatedAt),
            ct);
    }
}

// New module subscribes
public class OrderCreatedEventHandler
    : INotificationHandler<OrderCreatedEvent>
{
    private readonly OrderDbContext _db;

    public OrderCreatedEventHandler(OrderDbContext db)
    {
        _db = db;
    }

    public async Task Handle(
        OrderCreatedEvent notification, CancellationToken ct)
    {
        var order = Order.Create(
            notification.OrderId,
            notification.CustomerId,
            notification.Total);

        _db.Orders.Add(order);
        await _db.SaveChangesAsync(ct);
    }
}

Step 4: Parallel Running

Run both implementations simultaneously to verify the new module produces correct results:

public class ParallelVerificationService : IOrderService
{
    private readonly LegacyOrderService _legacy;
    private readonly NewOrderModule _newModule;
    private readonly ILogger<ParallelVerificationService> _logger;

    public ParallelVerificationService(
        LegacyOrderService legacy,
        NewOrderModule newModule,
        ILogger<ParallelVerificationService> logger)
    {
        _legacy = legacy;
        _newModule = newModule;
        _logger = logger;
    }

    public async Task<OrderDto> GetOrderAsync(Guid id)
    {
        var legacyResult = await _legacy.GetOrderAsync(id);
        var newResult = await _newModule.GetOrderAsync(id);

        // OrderDto is a record, so this compares values
        if (!legacyResult.Equals(newResult))
        {
            _logger.LogWarning(
                "Mismatch for order {OrderId}. Legacy: {@Legacy}, New: {@New}",
                id, legacyResult, newResult);
        }

        // Return the legacy result until verified
        return legacyResult;
    }
}

It implements the same IOrderService seam, so during the parallel-run phase you register it in place of the router. Compare on read paths like this one; doubling up writes would create duplicate side effects.

Once you're confident the new module is correct, flip the feature flag.

Step 5: Cut Over and Clean Up

After the new module is proven:

1. Point all traffic to the new module
2. Keep the legacy code around for a rollback period
3. Stop the data sync
4. Delete the legacy code
5. Drop the legacy database tables

{
  "FeatureManagement": {
    "NewOrdersModule": true,
    "NewPaymentsModule": true,
    "NewShippingModule": false
  }
}

Here, Orders and Payments are fully migrated, and Shipping is next up.

Migration Timeline

A realistic per-module timeline looks like this:

• Module scoping (1-2 weeks): identify boundaries, define contracts
• Build the new module (2-4 weeks): domain model, use cases, persistence
• Data migration (1-2 weeks): sync data, verify consistency
• Parallel run (1-2 weeks): verify correctness under production load
• Cut over (1 day): flip the feature flag, monitor closely
• Clean up (1 week): remove legacy code, drop old tables

That adds up to roughly 6 to 11 weeks per module. Repeat for each one. Later modules go faster because the routing seam, sync tooling, and team habits already exist, and you can pipeline the work (scope the next module while the previous one is in its parallel run). A system with 5-6 modules usually lands somewhere between six months and a year.

That sounds long, but compare it honestly with a rewrite: the same scope rewritten from scratch takes at least as long, delivers nothing until the end, and carries the risk of never shipping. The strangler fig delivers a migrated, verified module every few weeks.

Common Mistakes

Migrating too much at once. One module at a time. Don't try to migrate orders, payments, and shipping simultaneously.

Skipping the parallel run. You need proof the new module is correct before cutting over. Data inconsistencies are expensive to fix.

Not investing in the routing layer. The ability to route between old and new implementations per-request is crucial. Feature flags make this safe.

Ignoring data ownership. The legacy system and new module should not read from each other's tables directly. Communicate through events or APIs.

No Big Bang Required

The Strangler Fig pattern for migrating to a Modular Monolith:

1. Add a routing layer (feature flags)
2. Build one module at a time
3. Sync data between old and new
4. Run both in parallel to verify
5. Cut over and clean up
6. Repeat

No big bang rewrites. No weekends of downtime. Just steady, incremental progress toward a better architecture.

And when the modular monolith itself needs to evolve further, the same playbook applies to extracting modules into microservices.

Thanks for reading, and stay awesome!

The Sharing Dilemma

In a modular monolith, modules should be independent. But they inevitably need to share some things - base entity classes, common interfaces, integration event contracts, and value objects.

The question isn't whether to share, but how much and how.

Teams tend toward one of two extremes: modules that share nothing (duplicating hundreds of lines of identical code) and modules that share everything (a giant "Common" project that defeats the purpose of modularity). The shared kernel pattern sits in the middle.

What Is a Shared Kernel?

The shared kernel is a DDD concept - a small, well-defined set of code that two or more bounded contexts agree to share. It's not a dumping ground for convenience. Every type in the shared kernel is there because multiple modules genuinely need it.

In a .NET modular monolith, the shared kernel is typically a single project that all modules reference:

src/
  SharedKernel/
    SharedKernel.csproj
  Modules/
    Catalog/
    Ordering/
    Shipping/

What Belongs in the Shared Kernel

Base Domain Types

Abstract base classes for entities, aggregate roots, and value objects:

public abstract class Entity
{
    public Guid Id { get; protected init; }

    private readonly List<IDomainEvent> _domainEvents = [];

    public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    public void AddDomainEvent(IDomainEvent domainEvent)
    {
        _domainEvents.Add(domainEvent);
    }

    public void ClearDomainEvents()
    {
        _domainEvents.Clear();
    }
}

public abstract class AggregateRoot : Entity
{
    // Aggregate-specific behavior
}

Common Interfaces

Interfaces that define cross-cutting contracts:

public interface IDomainEvent
{
    Guid EventId { get; }
    DateTime OccurredOnUtc { get; }
}

public interface IIntegrationEvent
{
    Guid EventId { get; }
    DateTime OccurredOnUtc { get; }
}

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

The Result Type

A result pattern implementation that all modules use for error handling:

public class Result
{
    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;
    public Error Error { get; }

    protected Result(bool isSuccess, Error error)
    {
        IsSuccess = isSuccess;
        Error = error;
    }

    public static Result Success() => new(true, Error.None);
    public static Result Failure(Error error) => new(false, error);
    public static Result<T> Success<T>(T value) => new(value, true, Error.None);
    public static Result<T> Failure<T>(Error error) => new(default!, false, error);
}

public class Result<T> : Result
{
    public T Value { get; }

    protected internal Result(T value, bool isSuccess, Error error)
        : base(isSuccess, error)
    {
        Value = value;
    }
}

public record Error(string Code, string Description)
{
    public static readonly Error None = new(string.Empty, string.Empty);
}

Integration Event Contracts

The event types that define the contract between modules for event-driven communication:

// These are the contracts between modules
public sealed record OrderPlacedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IIntegrationEvent;

public sealed record PaymentCompletedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    decimal Amount) : IIntegrationEvent;

An alternative worth considering: keep only the IIntegrationEvent interface in the shared kernel and put each module's event records in that module's Contracts project (so OrderPlacedIntegrationEvent lives in Ordering.Contracts). That scopes each contract to its owning module, at the cost of consumers referencing multiple Contracts projects. Both work; just pick one convention and stick to it.

Strongly Typed IDs

If you're using strongly typed IDs that cross module boundaries:

public readonly record struct CustomerId(Guid Value)
{
    public static CustomerId New() => new(Guid.NewGuid());
}

public readonly record struct ProductId(Guid Value)
{
    public static ProductId New() => new(Guid.NewGuid());
}

What Does NOT Belong in the Shared Kernel

This is where teams go wrong. The shared kernel should not contain:

• Module-specific domain logic - An Order entity belongs in the Ordering module, not the shared kernel
• Infrastructure concerns - Database configurations, HTTP clients, logging helpers
• Utility classes - String helpers, date formatters, extension methods that only one module uses
• DTOs/ViewModels - These are API concerns, not domain concepts

A good rule of thumb: if removing a type from the shared kernel breaks only one module, it doesn't belong there.

Project Structure

Keep the shared kernel minimal and well-organized:

<!-- SharedKernel.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <!-- Zero external dependencies! -->
</Project>

The shared kernel should have zero external NuGet dependencies. It's pure domain code. If you need EF Core or MediatR types in the shared kernel, you've gone too far.

SharedKernel/
  Domain/
    Entity.cs
    AggregateRoot.cs
    IDomainEvent.cs
    IUnitOfWork.cs
  Results/
    Result.cs
    Error.cs
  Events/
    IIntegrationEvent.cs
    OrderPlacedIntegrationEvent.cs
    PaymentCompletedIntegrationEvent.cs
  Ids/
    CustomerId.cs
    ProductId.cs

Governance

The shared kernel is shared code, which means changes to it affect all modules. You need governance:

1. Code review required - Any change to the shared kernel must be reviewed by representatives of all consuming modules
2. Backward compatibility - Don't remove or rename types. Add new ones instead
3. Small surface area - Resist the urge to add convenience methods. Keep it minimal
4. Versioning - In a monorepo this is less critical, but treat the shared kernel as a contract

// BAD: Adding a helper because it's convenient
public static class StringExtensions
{
    public static string ToSlug(this string input) =>
        input.Trim().ToLowerInvariant().Replace(' ', '-');
}

// GOOD: Adding a type that genuinely defines a cross-module contract
public interface IIntegrationEventHandler<in TEvent>
    where TEvent : IIntegrationEvent
{
    Task HandleAsync(TEvent @event, CancellationToken cancellationToken = default);
}

Registering Shared Kernel Services

If the shared kernel provides services (like a domain event dispatcher), register them in a single extension method:

public static class SharedKernelServiceExtensions
{
    public static IServiceCollection AddSharedKernel(
        this IServiceCollection services)
    {
        services.AddScoped<IDomainEventDispatcher, DomainEventDispatcher>();

        return services;
    }
}

// In Program.cs
builder.Services.AddSharedKernel();
builder.Services.AddCatalogModule();
builder.Services.AddOrderingModule();

Keep the zero-dependency rule intact: the shared kernel defines IDomainEventDispatcher, but the implementation and this registration extension live in a shared infrastructure project (which is allowed to reference Microsoft.Extensions.DependencyInjection.Abstractions).

Takeaway

1. The shared kernel is a small, explicit set of shared types - not a dumping ground for convenience code.
2. Include base domain types, common interfaces, the result pattern, integration event contracts, and shared IDs.
3. Exclude module-specific logic, infrastructure, utilities, and DTOs.
4. The shared kernel project should have zero external NuGet dependencies.
5. Require code reviews for any shared kernel change since it affects all modules.
6. Keep the surface area as small as possible - when in doubt, don't share it.

Thanks for reading, and stay awesome!

They're the two strongest levels on the data isolation spectrum, which also includes table prefixes at the weak end.

Both enforce module boundaries at the data layer. But they make very different trade-offs around complexity, consistency, and your future migration path. The right choice depends on where your system is today - not where you hope it'll be in two years.

Let me break down each strategy, show you how to wire them up in EF Core, and compare them head to head.

Schema-Per-Module

The schema-per-module strategy keeps all modules inside a single database but assigns each module its own schema. The catalog module owns catalog.products, while the ordering module owns ordering.orders. They share a database server and connection string but have logically separated table namespaces.

In EF Core, you configure this with HasDefaultSchema on each DbContext:

public class CatalogDbContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("catalog");

        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(CatalogDbContext).Assembly);
    }
}

public class OrderingDbContext : DbContext
{
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("ordering");

        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(OrderingDbContext).Assembly);
    }
}

Both contexts share the same connection string. Each one also gets its own migrations history table, inside its own schema, so the modules can add and apply migrations independently:

var connectionString = builder.Configuration
    .GetConnectionString("DefaultConnection");

builder.Services.AddDbContext<CatalogDbContext>(options =>
    options.UseNpgsql(connectionString, npgsql =>
        npgsql.MigrationsHistoryTable(
            "__EFMigrationsHistory", "catalog")));

builder.Services.AddDbContext<OrderingDbContext>(options =>
    options.UseNpgsql(connectionString, npgsql =>
        npgsql.MigrationsHistoryTable(
            "__EFMigrationsHistory", "ordering")));

Without the MigrationsHistoryTable call, both contexts record their migrations in the same default __EFMigrationsHistory table, which couples the modules' migration workflows.

This strategy works well when you're starting out or when your modules share traffic patterns and don't need independent scaling. One database means one backup strategy, one monitoring target, and one connection string in your configuration.

Database-Per-Module

The database-per-module strategy gives each module its own database entirely. The catalog module connects to myshop_catalog, and the ordering module connects to myshop_ordering. There's no way to accidentally join across module boundaries because the tables live on separate databases.

The EF Core setup uses distinct connection strings:

builder.Services.AddDbContext<CatalogDbContext>(options =>
    options.UseNpgsql(builder.Configuration
        .GetConnectionString("CatalogDb")));

builder.Services.AddDbContext<OrderingDbContext>(options =>
    options.UseNpgsql(builder.Configuration
        .GetConnectionString("OrderingDb")));

Your configuration carries multiple connection strings:

{
  "ConnectionStrings": {
    "CatalogDb": "Host=localhost;Database=myshop_catalog;Username=app;Password=secret",
    "OrderingDb": "Host=localhost;Database=myshop_ordering;Username=app;Password=secret"
  }
}

Migrations are completely independent. Each module runs its own migration at startup without any coordination:

using var scope = app.Services.CreateScope();

var catalogDb = scope.ServiceProvider.GetRequiredService<CatalogDbContext>();
await catalogDb.Database.MigrateAsync();

var orderingDb = scope.ServiceProvider.GetRequiredService<OrderingDbContext>();
await orderingDb.Database.MigrateAsync();

This strategy works well when you need physical isolation between modules. If one module has heavy write loads and another is read-heavy, separate databases let you tune each independently. It also gives you independent backup and restore capabilities.

The Real Trade-offs

Choosing between schema-per-module and database-per-module comes down to five key areas.

Cross-module transactions. With schemas, both modules share a database, so you can wrap operations across modules in a single transaction. Treat that as an escape hatch, not a feature - every shared transaction couples the modules a little more. With separate databases, cross-module transactions are impossible by construction. You'll need patterns like the outbox pattern or sagas to maintain consistency across module boundaries. This is a significant complexity jump.

Deployment complexity. Schema-per-module means one database to provision, monitor, and back up. Database-per-module multiplies that by the number of modules. If you have five modules, you now have five databases to manage. In production, this means more connection pools, more monitoring dashboards, and more backup schedules.

Performance isolation. Schemas share the same database resources - CPU, memory, I/O. A poorly optimized query in one module can degrade performance for every other module. Separate databases give you true resource isolation. You can allocate more resources to your busiest module without touching the others.

Developer experience. Schema-per-module is simpler for local development. One PostgreSQL instance, one connection string, and you're running. Database-per-module means each developer needs multiple database instances, which usually means a Docker Compose file with several containers. Not a dealbreaker, but it adds friction.

Migration path to microservices. If you plan to eventually extract modules into microservices, database-per-module puts you closer to that goal. Each module already owns its data store. With schema-per-module, extracting a module means migrating its schema into a new database and updating all module communication to handle network boundaries.

Head-to-Head Summary

Here's the whole comparison condensed:

• Isolation level: schemas give logical isolation in one database; databases give physical isolation.
• Cross-module transactions: possible (but discouraged) with schemas; impossible with separate databases, which forces saga/outbox patterns.
• Deployment overhead: one database to manage vs one per module.
• Performance isolation: shared CPU, memory, and I/O with schemas; independent resources with databases.
• Local dev setup: one connection string vs a Docker Compose file with several database containers.
• Migration to microservices: schemas require a data extraction step first; databases are already separated.
• Backup and restore: all-or-nothing with one database; per-module with separate databases.
• Connection pooling: a single pool vs one pool per module (watch total connection counts on the server).

Enforcing the Boundary Either Way

Whichever strategy you pick, isolation only holds if nothing bypasses it. Use a separate database user per module (with permissions limited to its own schema or database) so a cross-module query fails loudly instead of working silently. I cover more enforcement techniques in how to keep your data boundaries intact.

My Recommendation

Start with schema-per-module. It gives you meaningful data isolation with minimal infrastructure overhead. You get separate namespaces, independent migration histories, and a clear boundary that prevents accidental cross-module queries through EF Core.

Then graduate to database-per-module when you hit one of these triggers:

• A module needs independent scaling due to different load patterns
• You need to restore one module's data without affecting others
• A noisy-neighbor problem is degrading performance across modules
• You're actively planning to extract a module into a service

The transition from schemas to databases is straightforward. You create the new database, migrate the schema's tables into it, and update the connection string. No changes to your DbContext classes or application code beyond configuration.

Picking the "best" strategy upfront is less important than picking one that enforces boundaries at all. A modular monolith with schema isolation beats a monolith where every module reaches into every other module's tables.

Thanks for reading, and stay awesome!

The Problem With Cross-Module Transactions

In a modular monolith, each module owns its data. When a business process spans multiple modules - like placing an order that requires inventory reservation, payment processing, and shipping - you can't wrap everything in a single database transaction.

If your modules use separate databases or separate schemas, there's no way to do a distributed ACID transaction without introducing tight coupling.

To be precise: with schema-per-module in one physical database, a cross-module transaction is technically possible. But using it means one module's transaction now holds locks on another module's tables, and your modules can never be separated without rewriting the process. Treat module boundaries as transaction boundaries, and the saga pattern follows naturally.

The saga pattern solves this by breaking a long-running process into a sequence of local transactions, each within a single module, coordinated through events or a centralized orchestrator.

Choreography vs Orchestration

There are two approaches to implementing sagas.

Choreography - Each module listens for events and decides what to do next. There's no central coordinator. Module A publishes an event, Module B reacts, publishes its own event, and Module C reacts to that.

Orchestration - A central saga orchestrator tells each module what to do and when. It maintains the state of the process and sends commands to each participant.

I prefer orchestration for most use cases because the process flow is explicit and visible in one place. With choreography, the business logic is scattered across event handlers in different modules, making it hard to understand and debug. I've written a deeper comparison in Orchestration vs Choreography.

Defining a Saga State Machine

A saga is essentially a state machine. Each step transitions the saga to a new state, and failures trigger compensating actions.

public class OrderSaga
{
    public Guid Id { get; private set; }
    public Guid OrderId { get; private set; }
    public decimal TotalAmount { get; private set; }
    public OrderSagaState State { get; private set; }
    public DateTime StartedAtUtc { get; private set; }
    public DateTime? CompletedAtUtc { get; private set; }
    public string? FailureReason { get; private set; }

    public static OrderSaga Start(Guid orderId, decimal totalAmount)
    {
        return new OrderSaga
        {
            Id = Guid.NewGuid(),
            OrderId = orderId,
            TotalAmount = totalAmount,
            State = OrderSagaState.Started,
            StartedAtUtc = DateTime.UtcNow
        };
    }

    public void TransitionTo(OrderSagaState newState)
    {
        State = newState;
    }

    public void Fail(string reason)
    {
        FailureReason = reason;
        State = OrderSagaState.Failed;
    }

    public void Complete()
    {
        State = OrderSagaState.Completed;
        CompletedAtUtc = DateTime.UtcNow;
    }
}

public enum OrderSagaState
{
    Started,
    InventoryReserved,
    PaymentProcessed,
    ShipmentScheduled,
    Completed,
    InventoryCompensated,
    Failed
}

Building the Saga Orchestrator

The orchestrator processes events and drives the saga forward. Each event handler checks the current state and issues the next command.

The saga is triggered by the same OrderPlacedIntegrationEvent contract used for event-driven communication, and every later step publishes its own thin event. IIntegrationEvent is the marker from the shared kernel: an EventId plus an OccurredOnUtc timestamp.

// Ordering.Contracts
public sealed record OrderPlacedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IIntegrationEvent;

public sealed record OrderLine(Guid ProductId, int Quantity);

// Inventory.Contracts
public sealed record StockReservedEvent(
    Guid EventId, DateTime OccurredOnUtc, Guid OrderId) : IIntegrationEvent;

public sealed record StockReservationFailedEvent(
    Guid EventId, DateTime OccurredOnUtc,
    Guid OrderId, string Reason) : IIntegrationEvent;

// Payment.Contracts
public sealed record PaymentProcessedEvent(
    Guid EventId, DateTime OccurredOnUtc, Guid OrderId) : IIntegrationEvent;

public sealed record PaymentFailedEvent(
    Guid EventId, DateTime OccurredOnUtc,
    Guid OrderId, string Reason) : IIntegrationEvent;

// Shipping.Contracts
public sealed record ShipmentScheduledEvent(
    Guid EventId, DateTime OccurredOnUtc, Guid OrderId) : IIntegrationEvent;

The orchestrator reacts to each of them:

public class OrderSagaOrchestrator
{
    private readonly IOrderingModule _ordering;
    private readonly IInventoryModule _inventory;
    private readonly IPaymentModule _payment;
    private readonly IShippingModule _shipping;
    private readonly ISagaRepository _sagaRepository;

    public OrderSagaOrchestrator(
        IOrderingModule ordering,
        IInventoryModule inventory,
        IPaymentModule payment,
        IShippingModule shipping,
        ISagaRepository sagaRepository)
    {
        _ordering = ordering;
        _inventory = inventory;
        _payment = payment;
        _shipping = shipping;
        _sagaRepository = sagaRepository;
    }

    public async Task HandleAsync(OrderPlacedIntegrationEvent @event)
    {
        var saga = OrderSaga.Start(@event.OrderId, @event.TotalAmount);
        await _sagaRepository.SaveAsync(saga);

        var lines = await _ordering.GetOrderLinesAsync(@event.OrderId);
        await _inventory.ReserveStockAsync(@event.OrderId, lines);
    }

    public async Task HandleAsync(StockReservedEvent @event)
    {
        var saga = await _sagaRepository.GetByOrderIdAsync(@event.OrderId);
        saga.TransitionTo(OrderSagaState.InventoryReserved);
        await _sagaRepository.SaveAsync(saga);

        await _payment.ProcessPaymentAsync(saga.OrderId, saga.TotalAmount);
    }

    public async Task HandleAsync(PaymentProcessedEvent @event)
    {
        var saga = await _sagaRepository.GetByOrderIdAsync(@event.OrderId);
        saga.TransitionTo(OrderSagaState.PaymentProcessed);
        await _sagaRepository.SaveAsync(saga);

        await _shipping.ScheduleShipmentAsync(saga.OrderId);
    }

    public async Task HandleAsync(ShipmentScheduledEvent @event)
    {
        var saga = await _sagaRepository.GetByOrderIdAsync(@event.OrderId);
        saga.TransitionTo(OrderSagaState.ShipmentScheduled);
        saga.Complete();

        await _sagaRepository.SaveAsync(saga);
    }
}

Two details in this class carry more weight than they look.

The saga keeps TotalAmount in its own state, captured when the process started. The Inventory module has no idea what the order costs, so StockReservedEvent can't be the source of that number; without it, the payment step has nothing correct to charge.

And each handler persists the state transition before issuing the next command. Crash between the two and you get a saga parked in a known state that a timeout can pick up later, instead of a payment charge the saga doesn't remember requesting.

Each module exposes a public API - an interface - that the orchestrator calls. The modules don't know about the saga. They simply execute commands and publish events.

public interface IOrderingModule
{
    Task<IReadOnlyList<OrderLine>> GetOrderLinesAsync(Guid orderId);
    Task CancelOrderAsync(Guid orderId, string reason);
}

public interface IInventoryModule
{
    Task ReserveStockAsync(Guid orderId, IReadOnlyList<OrderLine> lines);
    Task ReleaseStockAsync(Guid orderId);
}

public interface IPaymentModule
{
    Task ProcessPaymentAsync(Guid orderId, decimal amount);
}

public interface IShippingModule
{
    Task ScheduleShipmentAsync(Guid orderId);
}

Implementing Compensating Actions

When a step fails, you need to undo previous steps. These are compensating actions - the reverse of the original operation.

public async Task HandleAsync(PaymentFailedEvent @event)
{
    var saga = await _sagaRepository.GetByOrderIdAsync(@event.OrderId);

    // Compensate the inventory reservation
    await _inventory.ReleaseStockAsync(@event.OrderId);
    saga.TransitionTo(OrderSagaState.InventoryCompensated);

    saga.Fail(@event.Reason);
    await _sagaRepository.SaveAsync(saga);

    await _ordering.CancelOrderAsync(@event.OrderId, @event.Reason);
}

public async Task HandleAsync(StockReservationFailedEvent @event)
{
    var saga = await _sagaRepository.GetByOrderIdAsync(@event.OrderId);

    saga.Fail(@event.Reason);
    await _sagaRepository.SaveAsync(saga);

    await _ordering.CancelOrderAsync(@event.OrderId, @event.Reason);
}

Compensation must be idempotent. If the compensating action fails and gets retried, it should produce the same result. Use the outbox pattern to guarantee event delivery even during failures.

Note that compensation is not a rollback. The payment happened; the refund is a new business operation with its own audit trail. Some actions can't be perfectly compensated (you can't unsend an email), so design the step order to put hard-to-compensate actions last.

Wiring Events to the Orchestrator

Use your module communication infrastructure to route integration events to the orchestrator. I'm using the IIntegrationEventHandler<T> abstraction from the shared kernel:

public interface IIntegrationEventHandler<in TEvent>
    where TEvent : IIntegrationEvent
{
    Task HandleAsync(TEvent @event, CancellationToken ct = default);
}

A small router implements it for every saga event and delegates to the orchestrator:

public sealed class OrderSagaEventRouter :
    IIntegrationEventHandler<OrderPlacedIntegrationEvent>,
    IIntegrationEventHandler<StockReservedEvent>,
    IIntegrationEventHandler<StockReservationFailedEvent>,
    IIntegrationEventHandler<PaymentProcessedEvent>,
    IIntegrationEventHandler<PaymentFailedEvent>,
    IIntegrationEventHandler<ShipmentScheduledEvent>
{
    private readonly OrderSagaOrchestrator _orchestrator;

    public OrderSagaEventRouter(OrderSagaOrchestrator orchestrator)
    {
        _orchestrator = orchestrator;
    }

    public Task HandleAsync(
        OrderPlacedIntegrationEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);

    public Task HandleAsync(
        StockReservedEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);

    public Task HandleAsync(
        StockReservationFailedEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);

    public Task HandleAsync(
        PaymentProcessedEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);

    public Task HandleAsync(
        PaymentFailedEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);

    public Task HandleAsync(
        ShipmentScheduledEvent @event, CancellationToken ct = default) =>
        _orchestrator.HandleAsync(@event);
}

Register the router once per event type it handles:

public static class OrderSagaModule
{
    public static IServiceCollection AddOrderSaga(
        this IServiceCollection services)
    {
        services.AddScoped<OrderSagaOrchestrator>();
        services.AddScoped<ISagaRepository, SagaRepository>();

        services.AddScoped<
            IIntegrationEventHandler<OrderPlacedIntegrationEvent>,
            OrderSagaEventRouter>();
        services.AddScoped<
            IIntegrationEventHandler<StockReservedEvent>,
            OrderSagaEventRouter>();
        services.AddScoped<
            IIntegrationEventHandler<StockReservationFailedEvent>,
            OrderSagaEventRouter>();
        services.AddScoped<
            IIntegrationEventHandler<PaymentProcessedEvent>,
            OrderSagaEventRouter>();
        services.AddScoped<
            IIntegrationEventHandler<PaymentFailedEvent>,
            OrderSagaEventRouter>();
        services.AddScoped<
            IIntegrationEventHandler<ShipmentScheduledEvent>,
            OrderSagaEventRouter>();

        return services;
    }
}

Miss a registration and that event is silently ignored, which is exactly how sagas get stuck halfway. An architecture test that asserts every saga event has a registered handler is cheap insurance.

Persisting Saga State

The saga state must be persisted so it survives application restarts. A simple table works:

public class SagaDbContext(DbContextOptions<SagaDbContext> options)
    : DbContext(options)
{
    public DbSet<OrderSaga> OrderSagas => Set<OrderSaga>();
}

public interface ISagaRepository
{
    Task<OrderSaga> GetByOrderIdAsync(Guid orderId);
    Task SaveAsync(OrderSaga saga);
}

public class SagaRepository : ISagaRepository
{
    private readonly SagaDbContext _dbContext;

    public SagaRepository(SagaDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<OrderSaga> GetByOrderIdAsync(Guid orderId)
    {
        return await _dbContext.OrderSagas
            .FirstOrDefaultAsync(s => s.OrderId == orderId)
            ?? throw new InvalidOperationException(
                $"Saga not found for order {orderId}.");
    }

    public async Task SaveAsync(OrderSaga saga)
    {
        var entry = _dbContext.Entry(saga);
        if (entry.State == EntityState.Detached)
        {
            _dbContext.OrderSagas.Add(saga);
        }

        await _dbContext.SaveChangesAsync();
    }
}

One production concern the simple repository hides: concurrency. If two events for the same saga arrive close together, both handlers load the same row and the last write wins. Add a concurrency token (xmin in PostgreSQL, rowversion in SQL Server) to the saga entity and retry on DbUpdateConcurrencyException.

When to Use Sagas in a Modular Monolith

Not every cross-module operation needs a saga. Use sagas when:

• The process spans three or more modules
• Steps can fail independently and need compensation
• You need visibility into the process state for debugging or monitoring
• The process is long-running (seconds to days)

For simple two-module interactions, direct module communication with error handling is often sufficient.

If you'd rather not hand-roll the state machine, MassTransit's saga support gives you persistence, concurrency handling, and timeouts out of the box, and it works with an in-memory transport inside a monolith. For sagas across separate services, see the saga pattern in .NET guide.

Takeaway

1. Sagas coordinate long-running business processes that span multiple modules without distributed transactions.
2. Orchestration keeps the process flow explicit in a single class, making it easier to understand and debug.
3. Each saga step is a local transaction within one module, maintaining data isolation.
4. Compensating actions undo previous steps when a later step fails - they must be idempotent.
5. Persist saga state so the process survives application restarts and can be monitored.
6. Use the outbox pattern alongside sagas for reliable event delivery.

Thanks for reading, and stay awesome!

The Dual-Write Problem

Picture this. A customer places an order. Your service saves the order to the database, then publishes an OrderPlaced event so the shipping module can start fulfillment.

Simple enough. Until it isn't.

The database write succeeds. The message broker call fails. Now you have an order sitting in the database, but the shipping module never hears about it. The customer waits. Nobody ships anything. You have a ghost order.

This is the dual-write problem. Any time your application writes to two separate systems - a database and a message broker - without a shared transaction, you have a consistency gap. And there are three ways it can bite you:

1. DB succeeds, broker fails. Data is persisted, but downstream systems never get the event. Orders go unfulfilled. Notifications never send. State drifts silently.
2. Broker succeeds, DB fails. Other services react to an event for data that was never saved. The shipping module tries to fulfill an order that doesn't exist.
3. Distributed transaction bottleneck. You wrap both writes in a two-phase commit. It works - until the broker goes slow, and suddenly every write in your system is blocked.

This is not a theoretical concern. It shows up in production under load, during network blips, and especially during deployments. The insidious part is that it doesn't fail loudly. It fails silently, producing inconsistent state that you only notice hours later when a customer complains.

Why Other Solutions Fall Short

The first instinct is usually to add a retry.

If publishing to the broker fails, just try again. But retries don't solve the fundamental problem. Between the DB commit and the successful publish, your process might crash. The message is lost. You'd need to scan the database for "unpublished" records - and now you're reinventing the Outbox pattern anyway.

The second instinct is distributed transactions. Two-phase commit (2PC) can coordinate the database and the broker so both commit or both roll back. In theory, it sounds perfect. In practice, it has serious drawbacks:

• Most message brokers don't support 2PC at all (RabbitMQ, Kafka).
• It adds significant latency to every write.
• A coordinator failure can leave participants in a blocked state.
• It creates tight coupling between your database and your messaging infrastructure.

There's a third approach you'll sometimes see: publish first, save second. The reasoning goes, "if the DB save fails, at least we can compensate." But this is strictly worse. You've now published an event for data that doesn't exist. Every downstream consumer processes garbage. Compensation logic adds enormous complexity and rarely covers every edge case.

None of these approaches solve the core issue. You're trying to make two independent systems behave atomically, and that's fighting physics.

How the Outbox Pattern Works

The key insight behind the Outbox pattern is deceptively simple: stop writing to two systems.

Instead of saving your business data to the database and then publishing an event to the broker, you save both the business data and the event to the same database, in the same transaction.

That's it. That's the whole trick.

You add an outbox table to your database. When you save an order, you also insert a row into the outbox table describing the event you want to publish. Both writes happen in a single database transaction.

A separate background process - the outbox processor - polls that table, picks up unprocessed messages, publishes them to the message broker, and marks them as processed.

The flow looks like this:

The order insert and the outbox insert commit together. The database guarantees that. Either both rows are committed or neither is. The dual-write problem vanishes because there is no dual write anymore - there's only one write target.

The publishing step is decoupled and asynchronous. It introduces a small delay, but it introduces something far more valuable: reliability.

The Guarantee

Why does this actually work? Because a single database transaction is atomic by definition. Your relational database has decades of battle-tested ACID guarantees. By placing the outbox message inside the same transaction as the business data, you're leveraging guarantees that already exist rather than trying to invent new ones across system boundaries.

If the transaction commits, both the order and the outbox message are persisted. The processor will eventually pick it up and publish. If the transaction rolls back, neither exists. No ghost orders. No phantom events.

There is a trade-off, though.

The outbox processor might publish a message and then crash before marking it as processed. On the next run, it publishes the same message again. This means the Outbox pattern provides at-least-once delivery, not exactly-once. Your consumers must be idempotent - they need to handle receiving the same event twice without producing duplicate side effects.

This is a well-understood trade-off, and idempotency is far easier to implement than distributed transaction coordination. The idempotent consumer pattern shows how to handle duplicate messages cleanly.

A Minimal Example

In .NET with EF Core, the Outbox pattern requires two things: a place to store outbox messages and a mechanism to capture domain events before they leave the transaction.

The outbox entity is straightforward:

public sealed class OutboxMessage
{
    public Guid Id { get; set; }
    public string Type { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
    public DateTime OccurredOnUtc { get; set; }
    public DateTime? ProcessedOnUtc { get; set; }
}

An EF Core interceptor captures domain events and converts them into outbox rows before the transaction commits. AggregateRoot here is the base class whose DomainEvents collection entities raise events into; the shared kernel article shows the full base type.

public sealed class InsertOutboxMessagesInterceptor : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            InsertOutboxMessages(eventData.Context);
        }

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private static void InsertOutboxMessages(DbContext context)
    {
        var outboxMessages = context.ChangeTracker
            .Entries<AggregateRoot>()
            .SelectMany(entry =>
            {
                var events = entry.Entity.DomainEvents.ToList();
                entry.Entity.ClearDomainEvents();
                return events;
            })
            .Select(domainEvent => new OutboxMessage
            {
                Id = Guid.NewGuid(),
                Type = domainEvent.GetType().FullName!,
                Content = JsonSerializer.Serialize(domainEvent, domainEvent.GetType()),
                OccurredOnUtc = DateTime.UtcNow
            })
            .ToList();

        context.Set<OutboxMessage>().AddRange(outboxMessages);
    }
}

When SaveChangesAsync is called, this interceptor collects every domain event from modified aggregates, serializes them into JSON, and adds them to the same DbContext. They all commit together. No second system involved.

One detail worth calling out: the Type column stores the full type name. The processor has to resolve the CLR type to deserialize the JSON later, and a bare class name won't round-trip across assemblies.

Wire the interceptor into the module's DbContext registration:

services.AddSingleton<InsertOutboxMessagesInterceptor>();

services.AddDbContext<OrderingDbContext>((sp, options) =>
    options
        .UseNpgsql(config.GetConnectionString("Database"))
        .AddInterceptors(
            sp.GetRequiredService<InsertOutboxMessagesInterceptor>()));

The background processor that publishes these messages is a separate concern. The critical part - the part that solves the dual-write problem - is entirely in the code above.

For the full end-to-end implementation, including the background worker, see implementing the Outbox pattern. And if you ever need serious throughput, I've written about scaling the Outbox to 2 billion messages per day.

When You Need It (and When You Don't)

The Outbox pattern is the right choice when losing an event has business consequences.

Reach for it when:

• You need reliable event publishing after database writes
• Modules in a modular monolith need to communicate through events
• You're publishing events to external brokers in a microservices architecture
• Consistency between your data and your events is non-negotiable

Skip it when:

• The events are purely informational - analytics pings, debug logs, metrics. If losing a few is acceptable, the added complexity isn't worth it.
• Fire-and-forget notifications where the occasional miss is tolerable.
• Your database supports Change Data Capture (CDC) and you'd rather capture changes at the log level. CDC solves a similar problem from a different angle and avoids the outbox table entirely.

The pattern adds a table, a background processor, and the idempotency requirement on consumers. That's real complexity. But for any system where "the event must go out if the data was saved," there's no simpler reliable solution.

One Write Instead of Two

The dual-write problem is one of those issues that's easy to overlook and painful to debug after the fact. It doesn't throw exceptions. It produces subtle data inconsistencies that erode trust in your system over time.

The Outbox pattern solves it by reducing two writes to one. Your database transaction becomes the single source of truth for both business data and events. Everything else - the publishing, the delivery, the processing - flows from that one atomic commit.

It's a small architectural decision with outsized impact on system reliability.

Thanks for reading, and stay awesome!

Why Boundaries Matter

Draw module boundaries wrong, and you'll spend your time fighting the architecture instead of building features. Modules that are too fine-grained create an explosion of inter-module communication. Modules that are too coarse become monoliths within a monolith.

A bounded context from Domain-Driven Design defines a clear boundary where a particular domain model applies. It's the best tool we have for deciding what goes in each module of a Modular Monolith.

Context Maps

Start by mapping the subdomains of your business:

Each box is a bounded context, and each becomes a module.

Rules for Drawing Boundaries

Rule 1: Each Module Owns Its Language

In the Ordering module, "Product" means an item in the order with a quantity and price. In the Catalog module, "Product" means an item with descriptions, images, and categories. Same word, different meaning.

// Ordering Module
public class OrderProduct
{
    public Guid ProductId { get; set; }
    public string Name { get; set; }
    public int Quantity { get; set; }
    public decimal Price { get; set; }
}

// Catalog Module
public class CatalogProduct
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public List<string> Images { get; set; }
    public Guid CategoryId { get; set; }
}

Each module has its own model of the same real-world concept. This is ubiquitous language in action.

Duplicating the Product concept feels wrong at first. It isn't. The Ordering module's OrderProduct is a snapshot of name and price at the time of ordering - you want it frozen even if the catalog changes later. What looks like duplication is actually two different concepts that happen to share a name.

Rule 2: Minimize Cross-Module Communication

If two concepts constantly need each other's data, they probably belong in the same module:

Bad - too chatty between modules
  OrdersModule.PlaceOrder → InventoryModule.CheckStock
  OrdersModule.PlaceOrder → PricingModule.CalculatePrice
  OrdersModule.PlaceOrder → CustomerModule.GetCustomer
  OrdersModule.PlaceOrder → TaxModule.CalculateTax

Better - Pricing is part of Ordering
  OrdersModule.PlaceOrder → InventoryModule.CheckStock
  (Pricing, tax, and customer validation happen within OrdersModule)

If every order operation calls the pricing module, merge pricing into ordering.

Rule 3: Each Module Owns Its Data

No shared databases between modules. Each module has its own tables (or schema):

// Ordering Module
public class OrderingDbContext : DbContext
{
    public DbSet<Order> Orders { get; set; }
    public DbSet<LineItem> LineItems { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("ordering");
    }
}

// Catalog Module
public class CatalogDbContext : DbContext
{
    public DbSet<Product> Products { get; set; }
    public DbSet<Category> Categories { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("catalog");
    }
}

See Modular Monolith Data Isolation for implementation details.

Rule 4: Communicate Through Contracts

Modules don't reference each other's internals. They communicate through integration events or public APIs:

// Shared contract
public sealed record OrderPlacedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IIntegrationEvent;

// Ordering Module publishes
await _eventBus.PublishAsync(
    new OrderPlacedIntegrationEvent(
        Guid.NewGuid(),
        DateTime.UtcNow,
        order.Id,
        order.CustomerId,
        order.TotalAmount));

// Shipping Module subscribes
public sealed class OrderPlacedHandler(ShippingDbContext db)
    : IIntegrationEventHandler<OrderPlacedIntegrationEvent>
{
    public async Task HandleAsync(
        OrderPlacedIntegrationEvent @event,
        CancellationToken cancellationToken = default)
    {
        var shipment = Shipment.CreateFor(@event.OrderId);

        db.Shipments.Add(shipment);
        await db.SaveChangesAsync(cancellationToken);
    }
}

The IIntegrationEvent and IIntegrationEventHandler<TEvent> abstractions live in the shared kernel, so every module speaks the same contract language.

Common Mistakes

Mistake 1: Entity-Based Modules

Bad - modules based on entities
Modules/
  OrderModule/
  CustomerModule/
  ProductModule/
  PaymentModule/
  InvoiceModule/

This creates fine-grained modules that constantly communicate. "Place an order" touches 5 modules.

Mistake 2: One Giant Module

Bad - everything in one module
Modules/
  ECommerceModule/  ← 200 entities, 150 handlers

If a module has more than 15-20 entities, it's probably doing too much.

Mistake 3: Technical Modules

Bad - modules based on technical concerns
Modules/
  ApiModule/
  BusinessLogicModule/
  DatabaseModule/
  MessagingModule/

This is just layers with extra steps. Modules should be business-oriented.

Practical Process

Step 1: List Business Capabilities

• Place an order
• Manage product catalog
• Handle payments
• Ship orders
• Manage customer accounts
• Generate invoices
• Handle refunds

Step 2: Group by Cohesion

Which capabilities change together?

Ordering: Place order, Cancel order, Order status
Catalog: Product management, Categories, Search
Payments: Process payment, Refunds, Payment methods
Shipping: Create shipment, Track delivery, Returns
Identity: User accounts, Authentication, Roles

Step 3: Validate With the "Change Test"

Ask: "If I change feature X, which module is affected?"

• "Change the order discount logic" → Ordering only
• "Add a new product attribute" → Catalog only
• "Change how shipping cost is calculated" → Shipping only

If a change touches multiple modules, your boundaries might be wrong.

Boundaries Are Not Forever

You will get some boundaries wrong. That's expected - you know the least about your domain at the start of the project.

The good news: fixing a boundary inside a monolith is a refactoring, not a migration. Merging two chatty modules means moving files and combining two DbContexts. Splitting an overgrown module is harder, but still a single-codebase exercise. I walk through a real example in refactoring overgrown bounded contexts.

Compare that with microservices, where a wrong boundary is baked into network contracts, separate databases, and independent deployment pipelines. This is the strongest argument for validating boundaries in a modular monolith before extracting anything to a microservice.

Module Structure

src/
  Modules/
    Ordering/
      Ordering.Application/    ← Use cases, handlers
      Ordering.Domain/         ← Entities, value objects
      Ordering.Infrastructure/ ← EF Core, external services
      Ordering.Contracts/      ← Public API, integration events
    Catalog/
      Catalog.Application/
      Catalog.Domain/
      Catalog.Infrastructure/
      Catalog.Contracts/

The Contracts project is the only one other modules can reference.

Getting the Boundaries Right

Drawing module boundaries with bounded contexts:

1. Map your business capabilities - not entities, not technical layers
2. Each module owns its language - same word, different meaning across modules
3. Minimize cross-module communication - chatty modules should merge
4. Each module owns its data - separate schemas, no shared tables
5. Communicate through contracts - events and public APIs only
6. Validate with the change test - a change should affect one module

Get boundaries right, and the rest of the Modular Monolith falls into place.

Thanks for reading, and stay awesome!

Why Event-Driven?

In a Modular Monolith, modules must stay decoupled. Direct method calls between modules create tight coupling - exactly what you're trying to avoid.

Event-driven communication solves this: one module publishes an event, and other modules react independently. The publisher doesn't know (or care) who's listening.

Domain Events vs Integration Events

There are two types of events in a Modular Monolith:

• Domain events stay within a module and are handled in the same transaction. Example: OrderPlaced, consumed by another handler inside the Ordering module.
• Integration events cross module boundaries and are processed in separate transactions. Example: OrderPlacedIntegrationEvent, consumed by the Shipping and Notification modules.

Domain events are internal to a module. Integration events cross module boundaries. A common flow: a domain event handler inside the module maps the domain event to an integration event and publishes it. That way, module internals (entity IDs, domain types) never leak into the shared contract.

Setting Up Integration Events

Define a shared contract that modules can reference:

// Shared contracts assembly
public interface IIntegrationEvent : INotification
{
    Guid EventId { get; }
    DateTime OccurredOnUtc { get; }
}

public sealed record OrderPlacedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IIntegrationEvent;

public sealed record PaymentCompletedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    decimal Amount) : IIntegrationEvent;

These live in a contracts project that both modules can reference - no dependency on internal module code.

One deliberate choice to call out: this IIntegrationEvent marker extends MediatR's INotification, because I'm about to use MediatR as the in-process event bus. MediatR throws if you publish an object that doesn't implement INotification, so this is not optional. The cost is a reference to the small MediatR.Contracts package from the contracts project. The shared kernel article shows the stricter, dependency-free variant of the same contract, with its own IIntegrationEventHandler<T> abstraction instead of MediatR's handler interface.

In-Process Event Bus

For a Modular Monolith running in a single process, you can use MediatR notifications as an event bus. You can also build a lightweight message bus with .NET Channels if you want true fire-and-forget semantics. The abstraction is what matters:

public interface IEventBus
{
    Task PublishAsync<T>(T integrationEvent, CancellationToken ct = default)
        where T : IIntegrationEvent;
}

public class InProcessEventBus : IEventBus
{
    private readonly IPublisher _publisher;

    public InProcessEventBus(IPublisher publisher)
    {
        _publisher = publisher;
    }

    public async Task PublishAsync<T>(
        T integrationEvent, CancellationToken ct) where T : IIntegrationEvent
    {
        await _publisher.Publish(integrationEvent, ct);
    }
}

Register it:

services.AddScoped<IEventBus, InProcessEventBus>();

Publishing Events

The Ordering module publishes an event after placing an order:

// Ordering module
public sealed class PlaceOrderHandler
    : IRequestHandler<PlaceOrderCommand, Result<Guid>>
{
    private readonly OrderingDbContext _db;
    private readonly IEventBus _eventBus;

    public PlaceOrderHandler(
        OrderingDbContext db, IEventBus eventBus)
    {
        _db = db;
        _eventBus = eventBus;
    }

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);

        _db.Orders.Add(order);
        await _db.SaveChangesAsync(ct);

        // Publish integration event
        await _eventBus.PublishAsync(
            new OrderPlacedIntegrationEvent(
                Guid.NewGuid(),
                DateTime.UtcNow,
                order.Id,
                order.CustomerId,
                order.TotalAmount),
            ct);

        return Result.Success(order.Id);
    }
}

Consuming Events

Other modules subscribe to events independently:

// Shipping module
public sealed class OrderPlacedHandler
    : INotificationHandler<OrderPlacedIntegrationEvent>
{
    private readonly ShippingDbContext _db;

    public OrderPlacedHandler(ShippingDbContext db) => _db = db;

    public async Task Handle(
        OrderPlacedIntegrationEvent notification, CancellationToken ct)
    {
        var shipment = Shipment.CreateFor(
            notification.OrderId,
            notification.CustomerId);

        _db.Shipments.Add(shipment);
        await _db.SaveChangesAsync(ct);
    }
}

// Notification module
public sealed class SendOrderConfirmationHandler
    : INotificationHandler<OrderPlacedIntegrationEvent>
{
    private readonly IEmailService _emailService;

    public SendOrderConfirmationHandler(IEmailService emailService) =>
        _emailService = emailService;

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

The Ordering module doesn't know about Shipping or Notifications. Each module independently decides how to react.

One gotcha you should know: MediatR's Publish awaits every handler synchronously, in the same request scope. If the Shipping handler takes two seconds, the user placing the order waits those two seconds. If the Notification handler throws, the exception propagates back to the publisher. "Event-driven" here means decoupled in code, not decoupled at runtime.

That's exactly the problem the outbox solves.

The Outbox Pattern for Reliability

What if the event consumer fails? With in-process events, you risk inconsistency - the order is saved but the shipment isn't created.

The Outbox Pattern solves this. The outbox message is a plain entity in the Ordering module's schema, with a few extra fields for retry bookkeeping that we'll use later:

public sealed class OutboxMessage
{
    public Guid Id { get; set; }
    public string Type { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
    public DateTime OccurredOnUtc { get; set; }
    public DateTime? ProcessedOnUtc { get; set; }
    public int RetryCount { get; set; }
    public string? Error { get; set; }
    public DateTime? FailedOnUtc { get; set; }
}

The handler saves the order and the outbox message in the same transaction:

public sealed class PlaceOrderHandler
    : IRequestHandler<PlaceOrderCommand, Result<Guid>>
{
    private readonly OrderingDbContext _db;

    public PlaceOrderHandler(OrderingDbContext db) => _db = db;

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);

        var orderPlaced = new OrderPlacedIntegrationEvent(
            Guid.NewGuid(), DateTime.UtcNow,
            order.Id, order.CustomerId, order.TotalAmount);

        // Save order AND outbox message in the same transaction
        _db.Orders.Add(order);
        _db.OutboxMessages.Add(new OutboxMessage
        {
            Id = Guid.NewGuid(),
            Type = orderPlaced.GetType().FullName!,
            Content = JsonSerializer.Serialize(orderPlaced),
            OccurredOnUtc = orderPlaced.OccurredOnUtc
        });

        await _db.SaveChangesAsync(ct);

        return Result.Success(order.Id);
    }
}

Note that Type stores the full type name. The processor needs it to resolve the CLR type when deserializing, and a bare class name won't resolve across assemblies.

A background job processes outbox messages and publishes them:

public class OutboxProcessor : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<OutboxProcessor> _logger;

    public OutboxProcessor(
        IServiceScopeFactory scopeFactory,
        ILogger<OutboxProcessor> logger)
    {
        _scopeFactory = scopeFactory;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider
                .GetRequiredService<OrderingDbContext>();
            var eventBus = scope.ServiceProvider
                .GetRequiredService<IEventBus>();

            var messages = await db.OutboxMessages
                .Where(m => m.ProcessedOnUtc == null)
                .OrderBy(m => m.OccurredOnUtc)
                .Take(20)
                .ToListAsync(ct);

            foreach (var message in messages)
            {
                var @event = DeserializeEvent(
                    message.Type, message.Content);

                await eventBus.PublishAsync(@event, ct);

                message.ProcessedOnUtc = DateTime.UtcNow;
            }

            await db.SaveChangesAsync(ct);
            await Task.Delay(TimeSpan.FromSeconds(5), ct);
        }
    }

    private static IIntegrationEvent DeserializeEvent(
        string type, string content)
    {
        var eventType =
            typeof(OrderPlacedIntegrationEvent).Assembly.GetType(type)
            ?? throw new InvalidOperationException(
                $"Unknown event type: {type}");

        return (IIntegrationEvent)JsonSerializer
            .Deserialize(content, eventType)!;
    }
}

Register it as a hosted service:

services.AddHostedService<OutboxProcessor>();

Two details in this class do a lot of work.

First, the processor is a singleton (every BackgroundService is), while the DbContext and event bus are scoped. Constructor-injecting them would throw at startup with scope validation enabled, which is why the processor creates a scope per iteration through IServiceScopeFactory. This is the same rule I covered in DI lifetimes.

Second, DeserializeEvent resolves the type from the contracts assembly. Type.GetType with a bare type name only searches the calling assembly and the core library, so it would return null here and fail at runtime.

Event Ordering

With a single outbox processor reading messages ordered by OccurredOnUtc, events are published in the order they were saved. That's one of the underrated benefits of the in-process setup: you get ordering for free, without partitions or sequence numbers.

Ordering only becomes a real problem when you scale out to multiple processors or move to a message broker. At that point you need partition keys or per-aggregate sequencing - I cover the options in message ordering in distributed systems.

Error Handling

When a consumer fails:

foreach (var message in messages)
{
    try
    {
        var @event = DeserializeEvent(message.Type, message.Content);
        await eventBus.PublishAsync(@event, ct);
        message.ProcessedOnUtc = DateTime.UtcNow;
    }
    catch (Exception ex)
    {
        message.RetryCount++;
        message.Error = ex.Message;

        if (message.RetryCount >= 3)
        {
            message.ProcessedOnUtc = DateTime.UtcNow;
            message.FailedOnUtc = DateTime.UtcNow;
            _logger.LogError(ex,
                "Outbox message {Id} failed after {Retries} retries",
                message.Id, message.RetryCount);
        }
    }
}

Failed messages after max retries go to a dead letter state for manual investigation.

There's a flip side to retries: a consumer can receive the same event twice. If the processor publishes a message and crashes before marking it processed, the next run publishes it again. Consumers must be idempotent - the idempotent consumer pattern covers how to handle duplicates safely. This is exactly why every integration event carries an EventId: it's the natural deduplication key.

Module Boundaries

Events enforce boundaries:

Modules never reference each other's internals. They communicate exclusively through events defined in shared contracts.

Takeaway

Event-driven communication in a Modular Monolith:

1. Integration events cross module boundaries, domain events stay internal
2. IEventBus abstracts the publishing mechanism (in-process or message broker)
3. Outbox Pattern guarantees events are published even if the consumer fails
4. Shared contracts define events without coupling module internals
5. Background processor publishes outbox messages with retry logic

Start with in-process events. Add the Outbox Pattern when you need reliability. When you eventually extract to microservices, swap the in-process bus for RabbitMQ or Azure Service Bus.

Thanks for reading, and stay awesome!

What We're Building

A Modular Monolith with three modules: Catalog, Ordering, and Shipping. Each module has its own domain, data store, and public API. They communicate through integration events and module interfaces.

If you're not sure this architecture is the right fit, start with What Is a Modular Monolith? and come back. This article is the hands-on part: by the end, you'll have a working skeleton you can grow into a production system.

Step 1: Solution Structure

src/
  Api/                          ← Host application (single deployment)
  Common/
    Common.Application/         ← Shared abstractions
    Common.Infrastructure/      ← Shared infrastructure
  Modules/
    Catalog/
      Catalog.Application/
      Catalog.Domain/
      Catalog.Infrastructure/
      Catalog.Contracts/
    Ordering/
      Ordering.Application/
      Ordering.Domain/
      Ordering.Infrastructure/
      Ordering.Contracts/
    Shipping/
      Shipping.Application/
      Shipping.Domain/
      Shipping.Infrastructure/
      Shipping.Contracts/

Create the solution:

dotnet new sln -n ModularMonolith

# Host
dotnet new webapi -n Api -o src/Api

# Common
dotnet new classlib -n Common.Application -o src/Common/Common.Application
dotnet new classlib -n Common.Infrastructure -o src/Common/Common.Infrastructure

# Catalog module
dotnet new classlib -n Catalog.Application -o src/Modules/Catalog/Catalog.Application
dotnet new classlib -n Catalog.Domain -o src/Modules/Catalog/Catalog.Domain
dotnet new classlib -n Catalog.Infrastructure -o src/Modules/Catalog/Catalog.Infrastructure
dotnet new classlib -n Catalog.Contracts -o src/Modules/Catalog/Catalog.Contracts

Repeat for Ordering and Shipping.

Step 2: Project References

Each module follows Clean Architecture internally:

<!-- Catalog.Application.csproj -->
<ItemGroup>
    <ProjectReference Include="..\Catalog.Domain\Catalog.Domain.csproj" />
    <ProjectReference Include="..\..\..\Common\Common.Application\Common.Application.csproj" />
</ItemGroup>

<!-- Catalog.Infrastructure.csproj -->
<ItemGroup>
    <ProjectReference Include="..\Catalog.Application\Catalog.Application.csproj" />
</ItemGroup>

Cross-module references go through Contracts only:

<!-- Ordering.Application.csproj -->
<ItemGroup>
    <ProjectReference Include="..\Ordering.Domain\Ordering.Domain.csproj" />
    <ProjectReference Include="..\..\Catalog\Catalog.Contracts\Catalog.Contracts.csproj" />
</ItemGroup>

The host references all Infrastructure projects:

<!-- Api.csproj -->
<ItemGroup>
    <ProjectReference Include="..\Modules\Catalog\Catalog.Infrastructure\Catalog.Infrastructure.csproj" />
    <ProjectReference Include="..\Modules\Ordering\Ordering.Infrastructure\Ordering.Infrastructure.csproj" />
    <ProjectReference Include="..\Modules\Shipping\Shipping.Infrastructure\Shipping.Infrastructure.csproj" />
</ItemGroup>

The Contracts project contains only what a module is willing to expose: the module's public interface, integration event records, and simple DTOs. No entities, no DbContext, no handlers. If it compiles without referencing anything else in the module, it belongs in Contracts.

Step 3: Database per Module

Each module gets its own schema using separate DbContexts:

// Catalog.Infrastructure/CatalogDbContext.cs
public class CatalogDbContext(DbContextOptions<CatalogDbContext> options)
    : DbContext(options)
{
    public DbSet<Product> Products { get; set; }
    public DbSet<Category> Categories { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("catalog");
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(CatalogDbContext).Assembly);
    }
}

// Ordering.Infrastructure/OrderingDbContext.cs
public class OrderingDbContext(DbContextOptions<OrderingDbContext> options)
    : DbContext(options)
{
    public DbSet<Order> Orders { get; set; }
    public DbSet<LineItem> LineItems { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.HasDefaultSchema("ordering");
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(OrderingDbContext).Assembly);
    }
}

All schemas live in the same database. Each module only accesses its own schema.

Each DbContext also gets its own migrations history table, so you can evolve modules independently:

dotnet ef migrations add InitialCreate \
  --project src/Modules/Catalog/Catalog.Infrastructure \
  --startup-project src/Api \
  --context CatalogDbContext

dotnet ef migrations add InitialCreate \
  --project src/Modules/Ordering/Ordering.Infrastructure \
  --startup-project src/Api \
  --context OrderingDbContext

Because the host references every Infrastructure project, you always pass --context to tell EF Core which module you're working with.

Step 4: Module Registration

Each module has a registration extension method:

// Catalog.Infrastructure/CatalogModuleRegistration.cs
public static class CatalogModuleRegistration
{
    public static IServiceCollection AddCatalogModule(
        this IServiceCollection services, IConfiguration config)
    {
        services.AddDbContext<CatalogDbContext>(options =>
            options.UseNpgsql(
                config.GetConnectionString("Database"),
                o => o.MigrationsHistoryTable(
                    "__EFMigrationsHistory", "catalog")));

        services.AddScoped<ICatalogModule, CatalogModule>();

        services.AddMediatR(cfg =>
            cfg.RegisterServicesFromAssembly(
                typeof(GetProductsQuery).Assembly)); // Catalog.Application

        return services;
    }
}

Careful with the MediatR assembly: the handlers live in Catalog.Application, not in the Infrastructure project where this registration class sits. Scanning the wrong assembly is a classic mistake, and the symptom is a runtime "no handler registered" error on the first request.

Wire everything in the host:

// Api/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCatalogModule(builder.Configuration);
builder.Services.AddOrderingModule(builder.Configuration);
builder.Services.AddShippingModule(builder.Configuration);

var app = builder.Build();

app.MapCatalogEndpoints();
app.MapOrderingEndpoints();
app.MapShippingEndpoints();

app.Run();

Step 5: Module Endpoints

Each module registers its own endpoints:

// Catalog.Infrastructure/CatalogEndpoints.cs
public static class CatalogEndpoints
{
    public static void MapCatalogEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/catalog")
            .WithTags("Catalog");

        group.MapGet("/products", async (
            ISender sender, CancellationToken ct) =>
        {
            var result = await sender.Send(
                new GetProductsQuery(), ct);
            return Results.Ok(result);
        });

        group.MapGet("/products/{id:guid}", async (
            Guid id, ISender sender, CancellationToken ct) =>
        {
            var result = await sender.Send(
                new GetProductByIdQuery(id), ct);
            return result is null
                ? Results.NotFound()
                : Results.Ok(result);
        });

        group.MapPost("/products", async (
            CreateProductRequest request,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(
                new CreateProductCommand(
                    request.Name, request.Price), ct);
            return Results.Created(
                $"/api/catalog/products/{result}", result);
        });
    }
}

One gotcha: this class lives in a class library, so Catalog.Infrastructure.csproj needs <FrameworkReference Include="Microsoft.AspNetCore.App" /> to see WebApplication and Results.

Step 6: Event Bus

Create a simple in-process event bus for integration events:

// Common.Application/IIntegrationEvent.cs
public interface IIntegrationEvent : INotification
{
    Guid EventId { get; }
    DateTime OccurredOnUtc { get; }
}

// Common.Application/IEventBus.cs
public interface IEventBus
{
    Task PublishAsync<T>(T @event, CancellationToken ct = default)
        where T : IIntegrationEvent;
}

// Common.Infrastructure/InProcessEventBus.cs
public class InProcessEventBus : IEventBus
{
    private readonly IPublisher _publisher;

    public InProcessEventBus(IPublisher publisher) =>
        _publisher = publisher;

    public async Task PublishAsync<T>(
        T @event, CancellationToken ct) where T : IIntegrationEvent
    {
        await _publisher.Publish(@event, ct);
    }
}

The IIntegrationEvent marker extends MediatR's INotification. That's what lets consumer modules subscribe with plain notification handlers; MediatR refuses to publish objects that don't implement INotification. If you'd rather keep your contracts free of MediatR entirely, the shared kernel article shows a dependency-free marker with its own IIntegrationEventHandler<T> abstraction.

Register the event bus:

services.AddScoped<IEventBus, InProcessEventBus>();

One caveat: MediatR's Publish runs every handler in the same process and scope, synchronously. A slow or failing consumer affects the publisher. That's fine for a first version, but for anything critical you'll want the Outbox pattern so events are persisted with the business data and published by a background worker.

Step 7: Cross-Module Communication

The ordering module uses the catalog module's public interface. The contract lives in Catalog.Contracts, so it's the only thing other modules ever see:

// Catalog.Contracts/ICatalogModule.cs
public interface ICatalogModule
{
    Task<IReadOnlyList<ProductResponse>> GetProductsAsync(
        IReadOnlyCollection<Guid> productIds,
        CancellationToken ct = default);
}

public sealed record ProductResponse(Guid Id, string Name, decimal Price);

The implementation stays internal to the Catalog module (this is the CatalogModule class we registered in Step 4):

// Catalog.Infrastructure/CatalogModule.cs
internal sealed class CatalogModule : ICatalogModule
{
    private readonly CatalogDbContext _db;

    public CatalogModule(CatalogDbContext db) => _db = db;

    public async Task<IReadOnlyList<ProductResponse>> GetProductsAsync(
        IReadOnlyCollection<Guid> productIds,
        CancellationToken ct = default)
    {
        return await _db.Products
            .Where(p => productIds.Contains(p.Id))
            .Select(p => new ProductResponse(p.Id, p.Name, p.Price))
            .ToListAsync(ct);
    }
}

The integration event that Ordering publishes lives in Ordering.Contracts:

// Ordering.Contracts/OrderPlacedIntegrationEvent.cs
public sealed record OrderPlacedIntegrationEvent(
    Guid EventId,
    DateTime OccurredOnUtc,
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IIntegrationEvent;

Ordering.Contracts references Common.Application to see the IIntegrationEvent marker; that's the one shared dependency contracts projects are allowed.

Now the ordering module can place an order:

// Ordering.Application/PlaceOrderHandler.cs
public sealed class PlaceOrderHandler
    : IRequestHandler<PlaceOrderCommand, Result<Guid>>
{
    private readonly ICatalogModule _catalog;
    private readonly OrderingDbContext _db;
    private readonly IEventBus _eventBus;

    public PlaceOrderHandler(
        ICatalogModule catalog,
        OrderingDbContext db,
        IEventBus eventBus)
    {
        _catalog = catalog;
        _db = db;
        _eventBus = eventBus;
    }

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        // Get product info from Catalog module
        var products = await _catalog.GetProductsAsync(
            command.Items.Select(i => i.ProductId).ToList(), ct);

        if (products.Count != command.Items.Count)
        {
            return Result.Failure<Guid>(new Error(
                "Ordering.ProductsNotFound",
                "Some products were not found."));
        }

        // Create order
        var order = Order.Create(command.CustomerId);
        foreach (var item in command.Items)
        {
            var product = products.First(p => p.Id == item.ProductId);
            order.AddLineItem(item.ProductId, item.Quantity, product.Price);
        }

        _db.Orders.Add(order);
        await _db.SaveChangesAsync(ct);

        // Publish integration event
        await _eventBus.PublishAsync(
            new OrderPlacedIntegrationEvent(
                Guid.NewGuid(), DateTime.UtcNow,
                order.Id, order.CustomerId, order.TotalAmount), ct);

        return Result.Success(order.Id);
    }
}

One simplification to be upfront about: I'm injecting OrderingDbContext straight into the handler to keep the example short, but with the Step 2 project references the Application project can't actually see the Infrastructure project. In a real module, either hide persistence behind an abstraction defined in Ordering.Application, or merge Application and Infrastructure into a single project per module (a perfectly valid simplification that many teams choose).

Step 8: Enforce Module Boundaries

Use architecture tests to prevent modules from referencing each other's internals:

[Fact]
public void OrderingModule_ShouldNotReference_CatalogInternals()
{
    var result = Types
        .InAssembly(typeof(OrderingDbContext).Assembly)
        .Should()
        .NotHaveDependencyOn("Catalog.Domain")
        .And()
        .NotHaveDependencyOn("Catalog.Application")
        .And()
        .NotHaveDependencyOn("Catalog.Infrastructure")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

See Architecture Testing for more patterns.

Project references already prevent most violations at compile time (a module can't call what it can't see). The architecture tests catch the sneakier failures: someone adding a project reference "just this once", or reflection-based access that the compiler can't see.

Common Pitfalls

A few things that bite teams on their first Modular Monolith:

• A bloated Common project. Common.Application should hold abstractions (IEventBus, base types, the result pattern), not business logic. If two modules need the same business rule, that's a boundary problem, not a code-sharing problem.
• Shared entities. The Ordering module must not reference Catalog.Domain.Product. It gets a ProductResponse DTO through the contract, or it stores its own copy of the data it needs (product name and price at the time of ordering).
• Cross-schema queries. One DbContext per module means EF Core won't let you join ordering.orders to catalog.products. Someone will try to do it with raw SQL. Don't. That query is a hidden coupling that will break the module boundary silently.
• Skipping Contracts because "it's all one process anyway". The Contracts project feels like ceremony until you extract a module. Then it becomes the API surface of your new service, for free.

When NOT to Use This Structure

For a small CRUD application with one team and one bounded context, four projects per module is overkill. A single project with feature folders will serve you better.

The Modular Monolith earns its structure when you have multiple distinct business capabilities, a team in the roughly 2-15 developer range, or a real chance you'll need to extract a module later.

If you want to see the complete approach applied to a production-grade system, my Modular Monolith Architecture course walks through every one of these steps in depth.

Takeaway

Building a Modular Monolith step by step:

1. Solution structure - each module has Domain, Application, Infrastructure, and Contracts
2. Contracts project - the only cross-module dependency allowed
3. Database per module - separate schemas, separate DbContexts
4. Module registration - each module wires its own DI and endpoints
5. Event bus - integration events for decoupled cross-module communication
6. Architecture tests - enforce module boundaries at build time

Start with a Modular Monolith. Extract to microservices only when you need to scale independently.

Thanks for reading, and stay awesome!

Clean Architecture Is Not Always the Answer

Teams apply Clean Architecture to every project, regardless of complexity. A five-endpoint CRUD API with four separate projects, domain events, a CQRS pipeline, and architecture tests.

That's over-engineering.

Clean Architecture solves specific problems. When those problems don't exist, the architecture adds cost without benefit.

When Clean Architecture Shines

Complex Business Logic

If your domain has real business rules - not just CRUD operations - Clean Architecture protects that logic from infrastructure concerns.

Signals you need it:

• Business rules that span multiple entities
• Domain invariants that must always hold
• Complex calculations or state machines
• Rules that change independently from infrastructure

// This is domain complexity worth protecting
public class LoanApplication : AggregateRoot
{
    public ApplicationStatus Status { get; private set; }
    public decimal Amount { get; private set; }

    public Result Approve(CreditScore score, DebtToIncomeRatio ratio)
    {
        if (Status != ApplicationStatus.UnderReview)
            return Result.Failure(LoanErrors.NotUnderReview);

        if (score.Value < 650)
            return Result.Failure(LoanErrors.CreditScoreTooLow);

        if (ratio.Value > 0.43m)
            return Result.Failure(LoanErrors.DebtRatioTooHigh);

        Status = ApplicationStatus.Approved;
        RaiseDomainEvent(new LoanApprovedDomainEvent(Id, Amount));

        return Result.Success();
    }
}

Long-Lived Projects

Projects expected to last years benefit from clean boundaries. Requirements change, frameworks evolve, team members rotate. Clean Architecture makes the codebase resilient to these changes.

If the project has a 6-month lifespan and will be replaced, the investment doesn't pay off.

Multiple Teams

When multiple teams work on the same codebase, clear boundaries prevent them from stepping on each other. The Domain layer is the stable core everyone agrees on.

High Testability Requirements

If comprehensive testing is a hard requirement (regulated industries, financial systems, healthcare), Clean Architecture makes the domain layer trivially testable - no mocks for databases or HTTP needed.

I've written more about why Clean Architecture is great for complex projects if you recognize your project in these signals.

When to Skip Clean Architecture

Simple CRUD Applications

If your application is mostly reading and writing data with minimal business logic:

// This doesn't need Clean Architecture
app.MapPost("/api/todos", async (TodoRequest request, AppDbContext db) =>
{
    var todo = new Todo { Title = request.Title, IsComplete = false };
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/api/todos/{todo.Id}", todo);
});

For CRUD, a single project with Minimal APIs and EF Core is faster to build, easier to understand, and perfectly maintainable.

Prototypes and MVPs

Speed matters more than architecture when you're validating an idea. Build the simplest thing that works. Refactor into Clean Architecture later if the project survives.

Small Microservices

A microservice with a narrow responsibility (send emails, resize images, generate PDFs) doesn't need four projects and a domain model. Keep it simple.

Internal Tools

Admin dashboards, migration scripts, and one-off data tools don't justify the ceremony. Ship fast, iterate, replace.

The Decision Framework

Ask these questions.

Questions where "yes" points to Clean Architecture:

• Does the domain have complex business rules?
• Will the project live for 2+ years?
• Do multiple teams contribute to the same codebase?
• Is testability a hard requirement (regulated industry, financial, healthcare)?

Questions where "yes" points to a simpler structure:

• Is it mostly CRUD?
• Is it a prototype or MVP?
• Is it a small, focused microservice?
• Is it an internal tool you'd rather replace than maintain?

If you answer "yes" to most of the first group, Clean Architecture is a good fit. If you answer "yes" to most of the second group, keep it simple. Mixed answers usually mean: start simple, and let the migration path below carry you.

Alternatives to Clean Architecture

Vertical Slice Architecture

Vertical Slice Architecture organizes code by feature instead of by layer. Each feature contains everything it needs - from request to response.

Best for: Medium-complexity applications where features are independent and don't share much domain logic. I compare the two approaches head-to-head in Vertical Slice Architecture vs Clean Architecture.

Simple Layered Architecture

The classic three-layer approach: Presentation → Business → Data. Less ceremony than Clean Architecture, still provides some separation.

Best for: Applications with moderate complexity that don't need the full rigor of Clean Architecture.

Single Project

Everything in one project, organized by feature folders.

Best for: Small applications, prototypes, microservices, and internal tools.

The Migration Path

You don't have to start with Clean Architecture. Start simple and evolve:

1. Start: Single project with feature folders
2. Grow: Extract a Domain project when business logic appears
3. Mature: Add Application and Infrastructure projects when needed
4. Scale: Add architecture tests to enforce boundaries

This is cheaper than starting with four empty projects and hoping you'll need them.

Common Objections

"But what if we need Clean Architecture later?" You'll know. When business logic starts leaking into controllers or database code infects your domain, it's time. Refactoring from a well-organized simple project to Clean Architecture is straightforward.

"Clean Architecture is industry standard." It's one approach among many. Hexagonal Architecture, Vertical Slices, and even well-structured monoliths are all valid. Choose based on your specific needs.

"My team expects Clean Architecture." Make the decision based on the project, not on habits. If the team knows Clean Architecture well and the project benefits from it, great. If it's adding overhead, question it.

The Bottom Line

Clean Architecture is a tool, not a dogma. Use it when your domain is complex, the project is long-lived, and testability matters. Skip it when simplicity serves you better.

The best architecture is the one that makes your team productive and your software maintainable - whatever that looks like for your specific project.

Thanks for reading, and stay awesome!

All three put the boundary in the wrong place, because they let a technical concern decide a business question. What must succeed or fail together is defined by the use case. So the transaction starts where the use case lives: the application layer.

The Principle: Atomicity Is a Use Case Property

Take a classic use case: transferring inventory between warehouses. Deduct from one location, add to another, record the movement. Partial success is corruption, so those writes are atomic because the business says so, not because EF Core has a transaction API.

That reasoning gives each layer its role:

• Domain: defines aggregates, and an aggregate is itself a consistency boundary. Changes within one aggregate must always be atomic. The domain implies what must be consistent, but never touches persistence.
• Application: the use case knows which aggregates it modifies together, so it owns the transaction boundary.
• Infrastructure: implements the mechanics with EF Core, and the details of working with transactions stay here.

Repositories are the notably wrong place. A repository sees one aggregate type at a time, and it cannot know whether the current operation is standalone or part of a larger unit. Controllers are equally wrong for the mirrored reason: they know about HTTP, not about business atomicity.

With the principle set, there are three ways to implement it. I will rank them as we go.

Option 1: One SaveChanges Per Use Case (the Default)

The fact that makes most explicit transactions unnecessary: EF Core already wraps every SaveChanges call in a database transaction. All tracked changes flushed by that one call commit or roll back together.

So the simplest correct pattern is: a use case mutates any number of tracked entities, and calls SaveChanges exactly once at the end.

public sealed record TransferInventoryCommand(
    Guid SourceLocationId,
    Guid DestinationLocationId,
    string Sku,
    int Quantity) : IRequest;

public sealed class TransferInventoryCommandHandler(
    IInventoryRepository inventoryRepository,
    IUnitOfWork unitOfWork)
    : IRequestHandler<TransferInventoryCommand>
{
    public async Task Handle(TransferInventoryCommand command, CancellationToken ct)
    {
        InventoryItem source = await inventoryRepository
            .GetAsync(command.SourceLocationId, command.Sku, ct)
            ?? throw new SourceInventoryNotFoundException(command.Sku);

        InventoryItem destination = await inventoryRepository
            .GetAsync(command.DestinationLocationId, command.Sku, ct)
            ?? throw new DestinationInventoryNotFoundException(command.Sku);

        source.Remove(command.Quantity);
        destination.Add(command.Quantity);

        await unitOfWork.SaveChangesAsync(ct);
    }
}

IUnitOfWork is a small application-layer interface, implemented by the DbContext in infrastructure:

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken ct = default);
}

// Infrastructure
public sealed class AppDbContext : DbContext, IUnitOfWork
{
    // DbSets and configuration
}

The DbContext was always a unit of work; the interface just lets the application layer own the abstraction, keeping the dependency arrow pointing inward.

This is my ranking's number one, and it should cover 90 percent of your use cases. It has a discipline attached: repositories never call SaveChanges. The moment a repository saves inside itself, the use case loses the ability to compose multiple changes into one atomic commit.

Domain events dispatched before SaveChanges (the standard interceptor approach) ride in the same transaction, so side effects like outbox messages commit atomically with the state change. That combination solves the dual-write problem without any explicit transaction code.

Option 2: An Explicit Transaction Abstraction (When One SaveChanges Is Not Enough)

Some use cases genuinely need more than one flush:

• You need a generated ID from an insert before a second write can proceed.
• You mix EF Core changes with Dapper or raw SQL that must commit together.
• You call an infrastructure service that writes to the same database outside the DbContext.

Then the application layer needs an explicit boundary, still behind its own abstraction:

public interface ITransactionManager
{
    Task ExecuteInTransactionAsync(
        Func<CancellationToken, Task> action,
        CancellationToken ct = default);
}

Infrastructure implements it with EF Core, including the execution strategy so it composes with connection resiliency:

public sealed class TransactionManager(AppDbContext dbContext) : ITransactionManager
{
    public async Task ExecuteInTransactionAsync(
        Func<CancellationToken, Task> action,
        CancellationToken ct = default)
    {
        IExecutionStrategy strategy = dbContext.Database.CreateExecutionStrategy();

        await strategy.ExecuteAsync(async token =>
        {
            await using IDbContextTransaction transaction =
                await dbContext.Database.BeginTransactionAsync(token);

            await action(token);

            await transaction.CommitAsync(token);
        }, ct);
    }
}

And the use case wraps only the part that must be atomic:

await transactionManager.ExecuteInTransactionAsync(async token =>
{
    await orderRepository.AddAsync(order, token);
    await unitOfWork.SaveChangesAsync(token);

    await auditWriter.WriteAsync(order.Id, token);
}, ct);

One catch: BeginTransactionAsync opens the transaction on the DbContext's connection, and it does not flow to other writers automatically. For the audit writer to actually participate, its Dapper or ADO.NET code must run on that same connection and transaction, which infrastructure can obtain from dbContext.Database.GetDbConnection() and dbContext.Database.CurrentTransaction.GetDbTransaction(). A writer on its own connection commits independently, and the atomicity you think you have is not there.

This is rank two: exactly as much transaction as the use case needs, no more. Use it for the minority of use cases that need it, and keep Option 1 everywhere else. Mixing the two in one codebase is normal.

Option 3: A Transaction Pipeline Behavior (Blanket Coverage)

The third approach wraps every command in a transaction via a MediatR pipeline behavior:

public interface ITransactionalCommand { }

public sealed class TransactionBehavior<TRequest, TResponse>(
    AppDbContext dbContext)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ITransactionalCommand
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        IExecutionStrategy strategy = dbContext.Database.CreateExecutionStrategy();

        return await strategy.ExecuteAsync(async token =>
        {
            await using IDbContextTransaction transaction =
                await dbContext.Database.BeginTransactionAsync(token);

            TResponse response = await next();

            await transaction.CommitAsync(token);

            return response;
        }, ct);
    }
}

The behavior depends on AppDbContext directly, so it lives in infrastructure; have it use ITransactionManager instead if you want it in the application layer.

I rank this third, and I use it rarely. The upsides are real: handlers stay free of transaction code, and no one can forget the boundary. But the costs are structural:

• Most handlers do not need it, because one SaveChanges already gave them atomicity. The blanket transaction just holds a connection and locks for longer than necessary.
• It invites multi-SaveChanges handlers to proliferate, because "the behavior will catch it". Implicit safety breeds sloppy boundaries.
• Handlers that call external services now do so inside an open database transaction, stretching lock duration across network calls.

If you adopt it, constrain it with a marker interface (like ITransactionalCommand above) so only opt-in commands pay the cost, and never wrap queries.

What About TransactionScope and Request-Level Middleware?

Two approaches I recommend against as defaults.

TransactionScope with ambient flow looks convenient, but it is easy to hold wrong. The scope does not flow across await unless you create it with TransactionScopeAsyncFlowOption.Enabled, and forgetting that means work after the first await silently runs outside the transaction. A second connection can escalate it to a distributed transaction, and the boundary hides in ambient state where nobody can see it. Explicit boundaries are easier to reason about and easier to test.

A transaction-per-request middleware puts the boundary at the HTTP layer, which is the controller mistake at scale: every read-only GET pays for transaction overhead, and the boundary no longer matches any business definition of atomicity. The use case is the boundary; the request is just transport.

I walk through this decision, including how the outbox extends atomicity to messaging, in Pragmatic Clean Architecture.

The Ranking

Transactions answer a business question (what must happen together), so the boundary belongs to the layer that models business operations: the application layer.

Ranked:

1. One SaveChanges per use case. EF Core's implicit transaction covers it. This is the default, and repositories must not save behind the use case's back.
2. An explicit ITransactionManager for the few use cases that need multiple flushes or mixed writers, wrapping only what must be atomic.
3. A pipeline behavior when you want blanket enforcement, constrained by a marker interface and kept away from queries.

If you find BeginTransaction in a controller or a repository today, move the boundary to the handler. The code gets shorter, and atomicity finally matches what the business actually meant.

Use Cases Are the Application Layer

In Clean Architecture, the Application layer contains use cases - the actions your system can perform. Each use case represents a single thing the user can do.

But as your project grows from 5 use cases to 50 to 200, organization becomes critical.

Strategy 1: Group by Feature (Recommended)

Organize use cases by business feature or aggregate:

Application/
  Orders/
    PlaceOrder/
      PlaceOrderCommand.cs
      PlaceOrderCommandHandler.cs
      PlaceOrderValidator.cs
    CancelOrder/
      CancelOrderCommand.cs
      CancelOrderCommandHandler.cs
    GetOrderById/
      GetOrderByIdQuery.cs
      GetOrderByIdQueryHandler.cs
      OrderResponse.cs
    GetOrders/
      GetOrdersQuery.cs
      GetOrdersQueryHandler.cs
      OrderSummaryResponse.cs
  Customers/
    RegisterCustomer/
      RegisterCustomerCommand.cs
      RegisterCustomerCommandHandler.cs
    GetCustomerProfile/
      GetCustomerProfileQuery.cs
      GetCustomerProfileQueryHandler.cs

Each use case gets its own folder. Everything related to placing an order - the command, handler, validator, DTOs - lives in one place.

Benefits:

• Find any use case instantly
• Related code is co-located
• Fewer merge conflicts (teams work on different features)
• Mirrors feature folders in Vertical Slice Architecture

This is Screaming Architecture in practice: the folder names shout Orders and Customers, not Handlers and DTOs.

Strategy 2: Group by CQRS

When using CQRS, separate commands from queries:

Application/
  Commands/
    Orders/
      PlaceOrder/
        PlaceOrderCommand.cs
        PlaceOrderCommandHandler.cs
      CancelOrder/
        CancelOrderCommand.cs
        CancelOrderCommandHandler.cs
  Queries/
    Orders/
      GetOrderById/
        GetOrderByIdQuery.cs
        GetOrderByIdQueryHandler.cs
      GetOrders/
        GetOrdersQuery.cs
        GetOrdersQueryHandler.cs

This makes it clear which operations modify state and which are read-only.

The downside shows up as the project grows: everything about Orders is now split across two top-level trees. To understand the Orders feature, you jump between Commands/Orders and Queries/Orders constantly. I'd only pick this layout if your read and write sides are owned by different teams or deployed separately. The Command/Query suffix already tells you which side you're on.

Strategy 3: Group by Technical Type (Avoid This)

For completeness, here's the layout you should not use:

Application/
  Commands/
    PlaceOrderCommand.cs
    CancelOrderCommand.cs
    RegisterCustomerCommand.cs
  Handlers/
    PlaceOrderCommandHandler.cs
    CancelOrderCommandHandler.cs
    RegisterCustomerCommandHandler.cs
  Validators/
    PlaceOrderValidator.cs
  Dtos/
    OrderResponse.cs
    CustomerResponse.cs

It looks tidy at 10 use cases. At 100, adding one feature means touching four distant folders, and Handlers/ is a 100-file wall where nothing is related to its neighbors.

Folders should group things that change together. A command and its handler change together. Two unrelated handlers don't.

One Use Case Per Folder

Each use case should have:

• A request (command or query)
• A handler
• Optionally: a validator, DTOs, and mapping

// PlaceOrderCommand.cs
public sealed record PlaceOrderCommand(
    Guid CustomerId,
    List<OrderItemRequest> Items) : ICommand<Guid>;

// PlaceOrderCommandHandler.cs
public sealed class PlaceOrderCommandHandler
    : ICommandHandler<PlaceOrderCommand, Guid>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;

    public PlaceOrderCommandHandler(
        IOrderRepository orderRepository,
        IUnitOfWork unitOfWork)
    {
        _orderRepository = orderRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var order = Order.Create(command.CustomerId, command.Items);

        _orderRepository.Add(order);
        await _unitOfWork.SaveChangesAsync(ct);

        return order.Id;
    }
}

// PlaceOrderValidator.cs
public sealed class PlaceOrderValidator
    : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(x => x.ProductId).NotEmpty();
            item.RuleFor(x => x.Quantity).GreaterThan(0);
        });
    }
}

Keep handlers small. If a handler grows beyond 30-40 lines, the business logic probably belongs in a domain service or the domain entity itself.

Single-File Use Cases

Some teams take co-location one step further and put the whole use case in one file with a static wrapper class:

// PlaceOrder.cs
public static class PlaceOrder
{
    public sealed record Command(
        Guid CustomerId,
        List<OrderItemRequest> Items) : ICommand<Guid>;

    public sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.CustomerId).NotEmpty();
            RuleFor(x => x.Items).NotEmpty();
        }
    }

    internal sealed class Handler : ICommandHandler<Command, Guid>
    {
        // ...
    }
}

You reference it as PlaceOrder.Command, which reads nicely at call sites. The tradeoff is longer files and slightly unusual navigation. I use separate files by default and reach for this style in smaller projects or vertical slice codebases. Pick one convention per project and stick with it.

Naming Conventions

Use verb-noun naming that describes what the use case does:

• PlaceOrderCommand, not OrderCommand - the verb says what happens
• CancelOrderCommand, not UpdateOrderStatusCommand - name the business operation, not the database effect
• GetOrderByIdQuery, not OrderQuery - be specific about what's fetched
• RegisterCustomerCommand, not CreateCustomerCommand - match how the business talks

PlaceOrder is domain language. CreateOrder is CRUD language. Use the Ubiquitous Language from your domain.

Shared DTOs and Contracts

When multiple use cases share the same response:

Application/
  Orders/
    PlaceOrder/...
    CancelOrder/...
    GetOrderById/...
    Shared/
      OrderResponse.cs
      OrderSummaryResponse.cs
      OrderItemResponse.cs

Or at the feature root level:

Application/
  Orders/
    OrderResponse.cs          ← shared by multiple queries
    PlaceOrder/...
    GetOrderById/...

Keep shared DTOs minimal. If two queries need slightly different data, create separate response types rather than one bloated class.

Interfaces and Abstractions

Define repository and service interfaces close to the features that use them:

Application/
  Orders/
    IOrderRepository.cs
    PlaceOrder/...
    CancelOrder/...
  Customers/
    ICustomerRepository.cs
    RegisterCustomer/...

Or in a centralized Abstractions folder if they're used across features:

Application/
  Abstractions/
    IUnitOfWork.cs
    ICurrentUserService.cs
    IDateTimeProvider.cs
  Orders/
    IOrderRepository.cs
    PlaceOrder/...

Behaviors (Cross-Cutting Concerns)

Cross-cutting concerns like validation, logging, and caching are pipeline behaviors that wrap use case handlers:

Application/
  Behaviors/
    ValidationBehavior.cs
    LoggingBehavior.cs
    CachingBehavior.cs
  Orders/
    PlaceOrder/...

These apply to all use cases automatically - no need to duplicate logic in each handler.

Enforcing the Conventions

Conventions decay without enforcement. A few architecture tests keep the structure honest:

[Fact]
public void CommandHandlers_Should_Have_CommandHandler_Suffix()
{
    var result = Types
        .InAssembly(ApplicationAssembly)
        .That()
        .ImplementInterface(typeof(ICommandHandler<,>))
        .Should()
        .HaveNameEndingWith("CommandHandler")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

[Fact]
public void Handlers_Should_Be_Sealed()
{
    var result = Types
        .InAssembly(ApplicationAssembly)
        .That()
        .ImplementInterface(typeof(ICommandHandler<,>))
        .Should()
        .BeSealed()
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

ApplicationAssembly is a shared static field (typeof(PlaceOrderCommand).Assembly) so every test scans the same project. These tests also assume the separate-file convention. If you use the single-file style with nested Handler classes, adjust the naming rule to match.

Cheap to write, and they catch drift in code review before it becomes precedent.

What Goes Wrong

Fat handlers. A handler with 100+ lines is doing too much. Extract business logic to domain entities or domain services. The handler should only orchestrate.

Shared commands. One command used for both creating and updating. Create separate PlaceOrderCommand and UpdateOrderCommand - they have different validation and different business rules.

Anemic use cases. A use case that just calls repository.Add(entity) with no business logic. This is fine for simple CRUD, but if there are invariants to enforce, they belong in the domain.

A Structure That Scales

Organize use cases by feature, one per folder, with clear verb-noun names:

1. Group by feature or aggregate
2. One use case per folder (command/query + handler + validator)
3. Use domain language for naming
4. Keep handlers thin - orchestration only
5. Share DTOs sparingly

The structure should make it obvious what your application does just by looking at the folder names.

Thanks for reading, and stay awesome!

Why Pipeline Behaviors

Every Clean Architecture project eventually runs into the same problem. You need logging in every handler. Validation before every command. Caching for expensive queries. And you don't want to copy-paste that logic into dozens of classes.

MediatR's IPipelineBehavior<TRequest, TResponse> solves this by wrapping your handlers with reusable middleware. Think of it like ASP.NET Core middleware, but for your CQRS pipeline. Each behavior gets a chance to run code before and after the handler, or short-circuit the pipeline entirely.

I'll walk you through four behaviors I use in almost every project.

One thing before we start: MediatR is now a commercial product for larger companies. Everything in this article still applies, and the same pattern works with hand-rolled handler interfaces and Scrutor decorators if you'd rather not take the dependency. I show that decorator-based approach in balancing cross-cutting concerns in Clean Architecture.

How IPipelineBehavior Works

A pipeline behavior implements IPipelineBehavior<TRequest, TResponse>. It receives the request, a next delegate that calls the next behavior (or the handler itself), and a cancellation token.

public class MyBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        // Run code BEFORE the handler.

        var response = await next();

        // Run code AFTER the handler.

        return response;
    }
}

The next delegate is the key. Calling it passes control down the pipeline. You can inspect the request before calling next, inspect the response after, or skip next entirely to short-circuit.

Logging Behavior

The first behavior I add to any project is logging with elapsed time. It gives you visibility into every request flowing through the system without a single log statement in your handlers.

public class LoggingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(
        ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    {
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var requestName = typeof(TRequest).Name;

        _logger.LogInformation("Handling {Request}", requestName);

        var stopwatch = Stopwatch.StartNew();

        var response = await next();

        stopwatch.Stop();

        _logger.LogInformation(
            "Handled {Request} in {ElapsedMs}ms",
            requestName,
            stopwatch.ElapsedMilliseconds);

        return response;
    }
}

Every command and query gets timed automatically. If something runs slow, you'll see it in your logs immediately.

Validation Behavior

Validation is a perfect candidate for a pipeline behavior. You run all FluentValidation validators for the incoming request, and if anything fails, you short-circuit the pipeline before the handler ever executes.

public class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(
        IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        if (!_validators.Any())
        {
            return await next();
        }

        var context = new ValidationContext<TRequest>(request);

        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(result => result.Errors)
            .Where(failure => failure is not null)
            .ToArray();

        if (failures.Length != 0)
        {
            throw new ValidationException(failures);
        }

        return await next();
    }
}

Notice the behavior never calls next() when validation fails. The handler stays clean - it only deals with business logic, never input validation. You can pair this with the Result pattern if you prefer returning errors over throwing exceptions.

Caching Behavior

For query caching, I use a marker interface called ICacheable. Only queries that implement it get cached. Everything else passes straight through.

public interface ICacheable
{
    string CacheKey { get; }
    TimeSpan CacheDuration { get; }
}

public class CachingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>, ICacheable
{
    private readonly IDistributedCache _cache;
    private readonly ILogger<CachingBehavior<TRequest, TResponse>> _logger;

    public CachingBehavior(
        IDistributedCache cache,
        ILogger<CachingBehavior<TRequest, TResponse>> logger)
    {
        _cache = cache;
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var cached = await _cache.GetStringAsync(
            request.CacheKey, cancellationToken);

        if (cached is not null)
        {
            _logger.LogInformation(
                "Cache hit for {CacheKey}", request.CacheKey);

            return JsonSerializer.Deserialize<TResponse>(cached)!;
        }

        var response = await next();

        await _cache.SetStringAsync(
            request.CacheKey,
            JsonSerializer.Serialize(response),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = request.CacheDuration
            },
            cancellationToken);

        return response;
    }
}

Apply it to a query by implementing ICacheable:

public record GetProductByIdQuery(Guid ProductId)
    : IRequest<ProductResponse>, ICacheable
{
    public string CacheKey => $"product:{ProductId}";
    public TimeSpan CacheDuration => TimeSpan.FromMinutes(5);
}

The handler has no idea caching exists. It just returns data, and the behavior handles the rest.

Transaction Behavior

Commands that modify data often need to run inside a database transaction. Instead of wrapping every handler in a BeginTransaction/CommitAsync block, you can use a behavior with a marker interface.

public interface ITransactional;

public class TransactionBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>, ITransactional
{
    private readonly ApplicationDbContext _dbContext;
    private readonly ILogger<TransactionBehavior<TRequest, TResponse>> _logger;

    public TransactionBehavior(
        ApplicationDbContext dbContext,
        ILogger<TransactionBehavior<TRequest, TResponse>> logger)
    {
        _dbContext = dbContext;
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        await using var transaction = await _dbContext.Database
            .BeginTransactionAsync(cancellationToken);

        try
        {
            var response = await next();

            await _dbContext.SaveChangesAsync(cancellationToken);
            await transaction.CommitAsync(cancellationToken);

            _logger.LogInformation(
                "Transaction committed for {Request}",
                typeof(TRequest).Name);

            return response;
        }
        catch
        {
            await transaction.RollbackAsync(cancellationToken);
            throw;
        }
    }
}

Mark any command that needs a transaction:

public record PlaceOrderCommand(Guid CustomerId, List<OrderItem> Items)
    : IRequest<Guid>, ITransactional;

If the handler throws, the transaction rolls back automatically. No try-catch clutter in your business logic.

Registering Behaviors

MediatR's AddOpenBehavior method handles registration. You call it inside AddMediatR, and MediatR figures out the generic type arguments at runtime.

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(PlaceOrderCommand).Assembly);

    cfg.AddOpenBehavior(typeof(LoggingBehavior<,>));
    cfg.AddOpenBehavior(typeof(ValidationBehavior<,>));
    cfg.AddOpenBehavior(typeof(CachingBehavior<,>));
    cfg.AddOpenBehavior(typeof(TransactionBehavior<,>));
});

Don't forget to register your FluentValidation validators too:

builder.Services.AddValidatorsFromAssembly(
    typeof(PlaceOrderCommand).Assembly);

Execution Order

The order you call AddOpenBehavior determines the execution order. Behaviors execute from the outside in, like layers of an onion.

With the registration above, a request flows like this:

1. LoggingBehavior - starts the stopwatch, logs the request name
2. ValidationBehavior - runs validators, short-circuits if invalid
3. CachingBehavior - returns cached data if available (for cacheable queries)
4. TransactionBehavior - begins a transaction (for transactional commands)
5. Handler - runs the actual business logic

The response then flows back up through each behavior in reverse order. This means the logging behavior captures the total time including validation, caching, and transaction overhead.

Think carefully about ordering. Logging should always be outermost so it captures everything. Validation should run before caching - there's no point caching an invalid request.

Takeaway

Pipeline behaviors keep your handlers focused on business logic. Logging, validation, caching, and transactions all live in their own classes, registered once, and applied automatically across every request that matches the constraints.

The pattern scales well. Even with eight or nine behaviors in the pipeline, handlers stay just as clean as they were with zero. If you're building a Clean Architecture application with MediatR, pipeline behaviors are the single best tool for managing cross-cutting concerns.

Thanks for reading, and stay awesome!

Why Mapping Between Layers Exists

In Clean Architecture, each layer has its own models:

• Domain layer - Entities and Value Objects (business rules)
• Application layer - Commands, Queries, DTOs (use case contracts)
• Infrastructure layer - Persistence models, configuration entities
• Presentation layer - API request/response models

These models look similar but serve different purposes. You need mapping to convert between them.

An HTTP request arrives as a PlaceOrderRequest. You map it to a PlaceOrderCommand. The handler creates an Order entity. You return an OrderResponse to the client.

That's three mappings in one request flow.

When Is Mapping Worth It?

Map when:

• The API contract differs from the internal model (different field names, flattened structures)
• You want to hide internal implementation details from API consumers
• Domain entities expose behaviors you don't want serialized
• You need to return computed or aggregated data that doesn't exist on the entity

Don't map when:

• The source and target are structurally identical
• Adding a mapping layer provides zero value beyond "architecture says so"

Pragmatism matters. A 1:1 mapping between PlaceOrderRequest and PlaceOrderCommand with identical fields is ceremony, not architecture.

Approach 1: Manual Mapping

The simplest option. Extension methods or static factory methods:

public static class OrderMappings
{
    public static PlaceOrderCommand ToCommand(this PlaceOrderRequest request)
    {
        return new PlaceOrderCommand(
            request.CustomerId,
            request.Items.Select(i => new OrderItemDto(
                i.ProductId,
                i.Quantity)).ToList());
    }

    public static OrderResponse ToResponse(this Order order)
    {
        return new OrderResponse(
            order.Id,
            order.Customer.Name,
            order.TotalAmount.Amount,
            order.Status.Name,
            order.CreatedAt);
    }
}

Usage:

app.MapPost("/api/orders", async (
    PlaceOrderRequest request,
    ICommandHandler<PlaceOrderCommand, Guid> handler,
    CancellationToken cancellationToken) =>
{
    var command = request.ToCommand();
    var result = await handler.Handle(command, cancellationToken);
    return result.IsSuccess
        ? Results.Created($"/api/orders/{result.Value}", result.Value)
        : result.ToProblemDetails();
});

Pros: Simple, explicit, easy to debug, no magic. Cons: Repetitive for large models, manual maintenance when models change.

Approach 2: Projection in Queries (CQRS)

For read operations, skip mapping entirely. Project directly from the database into your response model:

public class GetOrderByIdQueryHandler : IQueryHandler<GetOrderByIdQuery, OrderResponse>
{
    private readonly IApplicationDbContext _dbContext;

    public GetOrderByIdQueryHandler(IApplicationDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<Result<OrderResponse>> Handle(
        GetOrderByIdQuery query,
        CancellationToken cancellationToken)
    {
        var order = await _dbContext.Orders
            .Where(o => o.Id == query.OrderId)
            .Select(o => new OrderResponse(
                o.Id,
                o.Customer.Name,
                o.TotalAmount.Amount,
                o.Status.Name,
                o.CreatedAt))
            .FirstOrDefaultAsync(cancellationToken);

        if (order is null)
        {
            return Result.Failure<OrderResponse>(OrderErrors.NotFound(query.OrderId));
        }

        return order;
    }
}

This is the CQRS pattern in action. No domain entity loaded, no mapping needed. EF Core generates an efficient SQL query that returns only the columns you need.

The handler depends on an IApplicationDbContext abstraction rather than the concrete DbContext, so the Application layer never references Infrastructure directly.

This is my preferred approach for queries. It's fast, clean, and eliminating the mapping layer eliminates a whole category of bugs.

Approach 3: Constructor Mapping on DTOs

Let the DTO/response model accept the entity in its constructor:

public sealed record OrderResponse
{
    public OrderResponse(Order order)
    {
        Id = order.Id;
        CustomerName = order.Customer.Name;
        TotalAmount = order.TotalAmount.Amount;
        Status = order.Status.Name;
        CreatedAt = order.CreatedAt;
    }

    public Guid Id { get; init; }
    public string CustomerName { get; init; }
    public decimal TotalAmount { get; init; }
    public string Status { get; init; }
    public DateTime CreatedAt { get; init; }
}

Pros: Self-contained, mapping logic lives near the data. Cons: Creates a dependency from the response model to the domain entity. If your response models are in the Presentation layer, this couples Presentation to Domain - which some teams want to avoid.

Approach 4: AutoMapper

AutoMapper handles mapping by convention:

public class OrderProfile : Profile
{
    public OrderProfile()
    {
        CreateMap<Order, OrderResponse>()
            .ForMember(dest => dest.CustomerName, opt => opt.MapFrom(src => src.Customer.Name))
            .ForMember(dest => dest.TotalAmount, opt => opt.MapFrom(src => src.TotalAmount.Amount))
            .ForMember(dest => dest.Status, opt => opt.MapFrom(src => src.Status.Name));
    }
}

var response = _mapper.Map<OrderResponse>(order);

Pros: Reduces boilerplate for large models, convention-based for simple mappings. Cons: Magic behavior, runtime errors instead of compile-time errors, hard to debug, performance overhead, easy to misconfigure.

I generally avoid AutoMapper. The magic it provides isn't worth the debugging cost. When a mapping breaks, you're reading AutoMapper source code instead of a simple ToResponse() method.

There's also a licensing angle now: AutoMapper went commercial alongside MediatR. If you were on the fence, that's one more reason to prefer boring, dependency-free mapping code.

Approach 5: Mapster

Mapster is a faster alternative to AutoMapper with code generation support:

var response = order.Adapt<OrderResponse>();

Or with code generation for compile-time safety:

[AdaptFrom(typeof(Order))]
public sealed record OrderResponse(
    Guid Id,
    string CustomerName,
    decimal TotalAmount,
    string Status,
    DateTime CreatedAt);

Pros: Better performance than AutoMapper, code generation option. Cons: Still involves magic, still another dependency.

My Recommendation

1. Use projections for queries - don't load entities just to map them to DTOs
2. Use manual mapping for commands - extension methods are simple and explicit
3. Skip mapping when models are identical - don't create a PlaceOrderCommand that's identical to PlaceOrderRequest
4. Avoid AutoMapper - the convenience doesn't justify the debugging cost

Here's the practical flow:

How Many Models Do You Actually Need?

Not every layer needs its own model. A pragmatic approach:

On the write side (commands):

• Presentation: a request model
• Application: a command (which can reuse the request type when the shapes match)
• Domain: the entity

On the read side (queries):

• Application: a response DTO
• Infrastructure: nothing - the EF Core projection produces the DTO directly
• Domain: not involved; no entity is loaded

For simple CRUD, the request model might be the command. The response DTO might be the projection result. Two models instead of five.

Going too far in the other direction - a fresh DTO and mapper at every boundary - is what I call mapping mania in my Clean Architecture anti-patterns article.

Takeaway

Mapping between layers is a means, not an end. Map when it provides value - contract independence, data transformation, security (hiding internal fields). Skip it when it's just ceremony.

Projections eliminate the most common mapping. Manual extension methods handle the rest. You rarely need a mapping framework.

Thanks for reading, and stay awesome!

The Logging Dilemma

You want observability - structured logging, trace IDs, request timings. But you also want clean domain logic without ILogger scattered everywhere.

In Clean Architecture, logging has clear boundaries.

Where to Log (And Where Not To)

• Domain: don't log. Raise domain events instead, and log in their handlers.
• Application: log minimally, through a LoggingBehavior pipeline behavior rather than inside handlers.
• Infrastructure: log freely. Inject ILogger directly and record every external interaction.
• Presentation: log via middleware - HTTP request/response logging and the global exception handler.

The Domain layer should never reference ILogger. Domain entities don't need to know about logging infrastructure.

Pipeline Behavior: Log Every Use Case

A single MediatR pipeline behavior can log every command and query automatically:

public class LoggingBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(
        ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    {
        _logger = logger;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var requestName = typeof(TRequest).Name;

        _logger.LogInformation(
            "Handling {RequestName} {@Request}",
            requestName,
            request);

        var stopwatch = Stopwatch.StartNew();
        var response = await next();
        stopwatch.Stop();

        if (stopwatch.ElapsedMilliseconds > 500)
        {
            _logger.LogWarning(
                "Long-running request: {RequestName} took {ElapsedMs}ms",
                requestName,
                stopwatch.ElapsedMilliseconds);
        }

        if (response is Result { IsFailure: true } result)
        {
            _logger.LogError(
                "Handled {RequestName} with error {ErrorCode} in {ElapsedMs}ms",
                requestName,
                result.Error.Code,
                stopwatch.ElapsedMilliseconds);
        }
        else
        {
            _logger.LogInformation(
                "Handled {RequestName} in {ElapsedMs}ms",
                requestName,
                stopwatch.ElapsedMilliseconds);
        }

        return response;
    }
}

Register it in the Application layer's DI:

services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(assembly);
    config.AddOpenBehavior(typeof(LoggingBehavior<,>));
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
});

Now every command and query is logged (entry, exit, duration, and failed results) without touching a single handler. Note that the behavior doesn't catch exceptions. Those propagate to the global exception handler, so each failure gets logged exactly once.

Structured Properties

Enrich your logs with contextual properties using structured logging:

_logger.LogInformation(
    "Handling {RequestName} with {UserId} {@Request}",
    requestName,
    currentUser.UserId,
    request);

Structured properties make logs searchable. You can find all requests from a specific user or all executions of PlaceOrderCommand.

Be careful with {@Request}. This destructures the entire request object. If a command contains sensitive data (passwords, tokens), you'll log it.

Note that [JsonIgnore] won't help here - Serilog uses its own destructuring, not System.Text.Json. Use the Destructurama.Attributed package to mask properties:

public sealed record LoginCommand(
    string Email,
    [property: NotLogged] string Password) : ICommand<TokenResponse>;

Or configure a destructuring policy in your Serilog setup. The safest default: log the request name, not the request body, and opt in to logging specific properties. I cover this and other pitfalls in 5 Serilog best practices.

Infrastructure Layer Logging

The Infrastructure layer is where you log external interactions:

public class EmailService : IEmailService
{
    private readonly ILogger<EmailService> _logger;
    private readonly SmtpClient _client;

    public EmailService(ILogger<EmailService> logger, SmtpClient client)
    {
        _logger = logger;
        _client = client;
    }

    public async Task SendAsync(
        string to, string subject, string body, CancellationToken ct)
    {
        _logger.LogInformation(
            "Sending email to {Recipient} with subject {Subject}",
            to,
            subject);

        try
        {
            await _client.SendMailAsync(
                new MailMessage("noreply@app.com", to, subject, body), ct);

            _logger.LogInformation(
                "Email sent to {Recipient}", to);
        }
        catch (SmtpException ex)
        {
            _logger.LogError(ex,
                "Failed to send email to {Recipient}: {Error}",
                to,
                ex.Message);
            throw;
        }
    }
}

Log before and after external calls. Log failures with full exception details. This is your debugging lifeline when third-party services fail.

Request/Response Logging Middleware

Log HTTP requests at the API layer with middleware:

public class RequestLoggingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestLoggingMiddleware> _logger;

    public RequestLoggingMiddleware(
        RequestDelegate next,
        ILogger<RequestLoggingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var stopwatch = Stopwatch.StartNew();

        try
        {
            await _next(context);
        }
        finally
        {
            stopwatch.Stop();

            _logger.LogInformation(
                "HTTP {Method} {Path} responded {StatusCode} in {ElapsedMs}ms",
                context.Request.Method,
                context.Request.Path,
                context.Response.StatusCode,
                stopwatch.ElapsedMilliseconds);
        }
    }
}

Or use Serilog's built-in request logging:

app.UseSerilogRequestLogging(options =>
{
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("UserId",
            httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier));
    };
});

Domain Events Instead of Logging

Instead of injecting ILogger into domain entities, raise domain events:

public class Order : AggregateRoot
{
    public OrderStatus Status { get; private set; }
    public string? CancellationReason { get; private set; }

    public void Cancel(string reason)
    {
        if (Status == OrderStatus.Shipped)
            throw new DomainException("Cannot cancel a shipped order.");

        Status = OrderStatus.Cancelled;
        CancellationReason = reason;

        // Don't log here - raise an event
        RaiseDomainEvent(new OrderCancelledDomainEvent(Id, reason));
    }
}

Handle the event in the Application or Infrastructure layer where logging is appropriate:

public class OrderCancelledEventHandler
    : INotificationHandler<OrderCancelledDomainEvent>
{
    private readonly ILogger<OrderCancelledEventHandler> _logger;

    public OrderCancelledEventHandler(
        ILogger<OrderCancelledEventHandler> logger)
    {
        _logger = logger;
    }

    public Task Handle(
        OrderCancelledDomainEvent notification, CancellationToken ct)
    {
        _logger.LogInformation(
            "Order {OrderId} cancelled. Reason: {Reason}",
            notification.OrderId,
            notification.Reason);

        return Task.CompletedTask;
    }
}

The domain stays clean. The logging happens in the right layer.

Error Logging

Log exceptions in the global error handler:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken ct)
    {
        _logger.LogError(
            exception,
            "Unhandled exception: {Message}",
            exception.Message);

        httpContext.Response.StatusCode = 500;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = 500,
            Title = "Internal Server Error"
        }, ct);

        return true;
    }
}

Log the full exception with stack trace. Return a generic message to the client.

Log Levels

Use the right level for the right situation:

• Trace - detailed diagnostic info (never in production)
• Debug - development-time debugging
• Information - normal operations, use case execution
• Warning - slow requests, degraded performance
• Error - unhandled exceptions, failed operations
• Critical - application startup failures, data corruption

Logging Rules by Layer

Logging in Clean Architecture follows the dependency rule:

1. Domain layer - No logging. Raise domain events instead.
2. Application layer - Pipeline behaviors for automatic use case logging.
3. Infrastructure layer - Direct ILogger injection for external integrations.
4. Presentation layer - Middleware for HTTP request/response logging.
5. Global error handler - Catches and logs all unhandled exceptions.

Use structured logging everywhere. Enrich with correlation IDs and user context. Let the architecture guide where logging belongs.

Thanks for reading, and stay awesome!

What Is the Infrastructure Layer?

The Infrastructure layer is the outermost layer in Clean Architecture. It provides implementations for the abstractions defined in the Domain and Application layers.

Everything that talks to the outside world lives here:

• Database access - EF Core DbContext, Dapper queries, repository implementations
• External API clients - payment gateways, email services, third-party APIs
• Message brokers - RabbitMQ, Azure Service Bus, Kafka
• File storage - local disk, Azure Blob Storage, S3
• Caching - Redis, in-memory cache
• Authentication providers - Identity, OAuth, JWT token services

The Infrastructure layer depends on the Domain and Application layers. It implements their interfaces. The inner layers never reference Infrastructure directly.

Implementing Repository Interfaces

The Domain layer defines repository interfaces (some teams keep them in the Application layer instead; either placement works). Infrastructure provides the implementation:

// Domain layer - the interface
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
    void Add(Order order);
}

// Infrastructure layer - the implementation
public sealed class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _dbContext;

    public OrderRepository(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<Order?> GetByIdAsync(
        Guid id,
        CancellationToken cancellationToken = default)
    {
        return await _dbContext.Orders
            .Include(o => o.LineItems)
            .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);
    }

    public void Add(Order order)
    {
        _dbContext.Orders.Add(order);
    }
}

The repository pattern keeps EF Core confined to the Infrastructure layer. Your domain logic never sees a DbContext.

The DbContext

Your DbContext lives in Infrastructure and handles all EF Core configuration:

public sealed class AppDbContext : DbContext, IUnitOfWork
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Customer> Customers => Set<Customer>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(
            typeof(AppDbContext).Assembly);
    }
}

Entity configurations use IEntityTypeConfiguration<T>:

public sealed class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.HasKey(o => o.Id);

        builder.Property(o => o.Status)
            .HasConversion(
                status => status.Name,
                name => OrderStatus.FromName(name));

        builder.HasMany(o => o.LineItems)
            .WithOne()
            .HasForeignKey(li => li.OrderId)
            .OnDelete(DeleteBehavior.Cascade);

        builder.ComplexProperty(o => o.TotalAmount, money =>
        {
            money.Property(m => m.Amount).HasColumnName("total_amount");
            money.Property(m => m.Currency).HasColumnName("total_currency");
        });
    }
}

OrderStatus is a smart enum from the Domain layer, a class rather than a plain enum, so we tell EF Core explicitly how to convert it: store the Name, rehydrate with the FromName lookup on the Enumeration<TEnum> base class.

Implementing External Service Interfaces

The Application layer defines interfaces for external services. Infrastructure implements them:

// Application layer
public interface IEmailService
{
    Task SendOrderConfirmationAsync(
        string recipientEmail,
        Guid orderId,
        CancellationToken cancellationToken = default);
}

// Infrastructure layer
public sealed class EmailSettings
{
    public string BaseUrl { get; init; } = string.Empty;
    public string OrderConfirmationTemplateId { get; init; } = string.Empty;
}

public sealed class EmailService : IEmailService
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly EmailSettings _settings;

    public EmailService(
        IHttpClientFactory httpClientFactory,
        IOptions<EmailSettings> settings)
    {
        _httpClientFactory = httpClientFactory;
        _settings = settings.Value;
    }

    public async Task SendOrderConfirmationAsync(
        string recipientEmail,
        Guid orderId,
        CancellationToken cancellationToken = default)
    {
        var client = _httpClientFactory.CreateClient("EmailApi");

        var request = new SendEmailRequest
        {
            To = recipientEmail,
            Subject = "Order Confirmed",
            TemplateId = _settings.OrderConfirmationTemplateId,
            Data = new { OrderId = orderId }
        };

        await client.PostAsJsonAsync("/v1/emails", request, cancellationToken);
    }
}

Implementing Caching

Application layer defines the caching abstraction:

// Application layer
public interface ICacheService
{
    Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default);
    Task SetAsync<T>(string key, T value, TimeSpan? expiration = null, CancellationToken cancellationToken = default);
    Task RemoveAsync(string key, CancellationToken cancellationToken = default);
}

// Infrastructure layer
public sealed class RedisCacheService : ICacheService
{
    private readonly IDistributedCache _cache;

    public RedisCacheService(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task<T?> GetAsync<T>(
        string key,
        CancellationToken cancellationToken = default)
    {
        var bytes = await _cache.GetAsync(key, cancellationToken);

        return bytes is null
            ? default
            : JsonSerializer.Deserialize<T>(bytes);
    }

    public async Task SetAsync<T>(
        string key,
        T value,
        TimeSpan? expiration = null,
        CancellationToken cancellationToken = default)
    {
        var bytes = JsonSerializer.SerializeToUtf8Bytes(value);

        var options = new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = expiration ?? TimeSpan.FromMinutes(5)
        };

        await _cache.SetAsync(key, bytes, options, cancellationToken);
    }

    public async Task RemoveAsync(
        string key,
        CancellationToken cancellationToken = default)
    {
        await _cache.RemoveAsync(key, cancellationToken);
    }
}

DI Registration Module

Keep your Infrastructure DI registrations organized in a single method:

public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddDbContext<AppDbContext>(options =>
            options.UseNpgsql(configuration.GetConnectionString("Database")));

        services.AddScoped<IUnitOfWork>(sp =>
            sp.GetRequiredService<AppDbContext>());

        services.AddScoped<IOrderRepository, OrderRepository>();
        services.AddScoped<ICustomerRepository, CustomerRepository>();

        services.Configure<EmailSettings>(configuration.GetSection("Email"));

        services.AddHttpClient("EmailApi", client =>
            client.BaseAddress = new Uri(configuration["Email:BaseUrl"]!));

        services.AddScoped<IEmailService, EmailService>();
        services.AddScoped<ICacheService, RedisCacheService>();

        services.AddStackExchangeRedisCache(options =>
            options.Configuration = configuration.GetConnectionString("Redis"));

        return services;
    }
}

Then in Program.cs:

builder.Services.AddInfrastructure(builder.Configuration);

This keeps the Presentation layer from knowing about Infrastructure internals.

Folder Structure

Infrastructure/
  Data/
    AppDbContext.cs
    Configurations/
      OrderConfiguration.cs
      CustomerConfiguration.cs
    Repositories/
      OrderRepository.cs
      CustomerRepository.cs
    Interceptors/
      PublishDomainEventsInterceptor.cs
  Services/
    EmailService.cs
    PaymentService.cs
  Caching/
    RedisCacheService.cs
  Messaging/
    EventBus.cs
    Consumers/
      OrderCompletedConsumer.cs
  DependencyInjection.cs

Common Mistakes

1. Leaking Infrastructure into the Domain. If your entity has [Column] or [Table] attributes, you've coupled the Domain to EF Core. Use IEntityTypeConfiguration<T> instead.

2. Not using IEntityTypeConfiguration<T>. Putting all configuration in OnModelCreating becomes unmanageable. One config class per entity.

3. Referencing Infrastructure from Application. The Application layer should only use interfaces. If you see using Infrastructure; in an Application class, something is wrong.

4. Missing the Unit of Work. Don't call SaveChanges in every repository method. Use a dedicated Unit of Work that commits after the use case completes.

5. Fat Infrastructure classes. If your email service also handles templates, formatting, and retry logic, split it. Keep each implementation focused.

Takeaway

The Infrastructure layer is where all external concerns live. It implements the interfaces defined by inner layers and keeps framework dependencies from leaking inward.

Structure it by concern (Data, Services, Caching, Messaging), register everything cleanly, and test it with integration tests that verify actual external interactions.

Thanks for reading, and stay awesome!

The Problem

Exceptions fly around your application - validation errors, not-found scenarios, business rule violations, infrastructure failures. Without a clear strategy, exception handling becomes inconsistent:

• Some handlers throw exceptions, others return nulls
• The API layer catches NullReferenceException and guesses what went wrong
• Business errors are mixed with infrastructure failures
• Error responses are inconsistent across endpoints

A Layered Exception Strategy

Each layer in Clean Architecture handles errors differently:

• Domain: throw domain exceptions for invariant violations
• Application: return Result<T> for expected business errors
• Infrastructure: let infrastructure exceptions propagate
• Presentation: map results and exceptions to HTTP responses

Domain Layer: Guard Invariants

The Domain layer throws exceptions when invariants are violated - things that should never happen if the system is working correctly:

public class Order
{
    private Order(Guid customerId, List<LineItem> lineItems)
    {
        if (customerId == Guid.Empty)
            throw new DomainException("Customer ID cannot be empty.");

        if (lineItems.Count == 0)
            throw new DomainException("Order must have at least one line item.");

        Id = Guid.NewGuid();
        CustomerId = customerId;
        LineItems = lineItems;
        Status = OrderStatus.Draft;
    }

    public Guid Id { get; private set; }
    public Guid CustomerId { get; private set; }
    public List<LineItem> LineItems { get; private set; }
    public OrderStatus Status { get; private set; }
    public string? CancellationReason { get; private set; }

    public static Order Create(Guid customerId, List<LineItem> lineItems) =>
        new(customerId, lineItems);

    public void Cancel(string reason)
    {
        if (Status == OrderStatus.Shipped)
            throw new DomainException("Cannot cancel a shipped order.");

        Status = OrderStatus.Cancelled;
        CancellationReason = reason;
    }
}

Domain exceptions signal bugs or invalid state transitions. They're not for expected scenarios like "customer not found."

public class DomainException : Exception
{
    public DomainException(string message) : base(message) { }
}

Application Layer: Result Pattern

The Application layer uses the Result pattern for expected business failures:

public sealed class PlaceOrderCommandHandler
    : ICommandHandler<PlaceOrderCommand, Guid>
{
    private readonly IOrderRepository _orderRepository;
    private readonly ICustomerRepository _customerRepository;
    private readonly IUnitOfWork _unitOfWork;

    public PlaceOrderCommandHandler(
        IOrderRepository orderRepository,
        ICustomerRepository customerRepository,
        IUnitOfWork unitOfWork)
    {
        _orderRepository = orderRepository;
        _customerRepository = customerRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command, CancellationToken ct)
    {
        var customer = await _customerRepository.GetByIdAsync(
            command.CustomerId, ct);

        if (customer is null)
        {
            return Result.Failure<Guid>(
                CustomerErrors.NotFound(command.CustomerId));
        }

        if (!customer.IsActive)
        {
            return Result.Failure<Guid>(
                CustomerErrors.Inactive(command.CustomerId));
        }

        var order = Order.Create(command.CustomerId, command.Items);

        _orderRepository.Add(order);
        await _unitOfWork.SaveChangesAsync(ct);

        return order.Id;
    }
}

Define typed errors:

public static class CustomerErrors
{
    public static Error NotFound(Guid id) => new(
        "Customer.NotFound",
        $"Customer with ID '{id}' was not found.",
        ErrorType.NotFound);

    public static Error Inactive(Guid id) => new(
        "Customer.Inactive",
        $"Customer with ID '{id}' is inactive.",
        ErrorType.Conflict);
}

public record Error(string Code, string Description, ErrorType Type);

public enum ErrorType
{
    Validation,
    NotFound,
    Conflict,
    Forbidden,
    Failure
}

The handler never throws for expected scenarios. Customer not found is not exceptional - it's an expected outcome.

Validation: Before the Handler

Use a validation pipeline behavior to reject invalid requests before the handler runs:

public class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
    where TResponse : Result
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var failures = _validators
            .Select(v => v.Validate(request))
            .SelectMany(result => result.Errors)
            .Where(f => f is not null)
            .ToList();

        if (failures.Count != 0)
        {
            return CreateValidationResult<TResponse>(failures);
        }

        return await next();
    }
}

Validation errors are returned as Result.Failure with ErrorType.Validation - not thrown as exceptions.

The CreateValidationResult helper needs a small amount of reflection to construct either Result or Result<T> depending on the request type. I walk through the complete implementation in CQRS validation with MediatR pipeline and FluentValidation.

Presentation Layer: Map to HTTP

The API layer maps Result<T> to HTTP responses:

app.MapPost("/api/orders", async (
    PlaceOrderRequest request,
    ISender sender,
    CancellationToken ct) =>
{
    var command = new PlaceOrderCommand(request.CustomerId, request.Items);
    var result = await sender.Send(command, ct);

    return result.IsSuccess
        ? Results.Created($"/api/orders/{result.Value}", result.Value)
        : result.ToProblemDetails();
});

public static IResult ToProblemDetails(this Result result)
{
    if (result.IsSuccess)
    {
        throw new InvalidOperationException(
            "Can't convert a success result to a problem response.");
    }

    return Results.Problem(
        statusCode: result.Error.Type switch
        {
            ErrorType.Validation => StatusCodes.Status400BadRequest,
            ErrorType.NotFound => StatusCodes.Status404NotFound,
            ErrorType.Conflict => StatusCodes.Status409Conflict,
            ErrorType.Forbidden => StatusCodes.Status403Forbidden,
            _ => StatusCodes.Status500InternalServerError
        },
        title: result.Error.Code,
        detail: result.Error.Description);
}

Global Exception Handler: Safety Net

For unexpected exceptions (bugs, infrastructure failures), use global error handling:

app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        var exception = context.Features
            .Get<IExceptionHandlerFeature>()?.Error;

        var (statusCode, title) = exception switch
        {
            DomainException => (400, "Domain Rule Violation"),
            _ => (500, "Internal Server Error")
        };

        context.Response.StatusCode = statusCode;
        context.Response.ContentType = "application/problem+json";

        await context.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Detail = statusCode == 500
                ? "An unexpected error occurred."
                : exception?.Message
        });
    });
});

Or with .NET 8's IExceptionHandler:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken ct)
    {
        _logger.LogError(exception, "Unhandled exception: {Message}", exception.Message);

        httpContext.Response.StatusCode = exception switch
        {
            DomainException => StatusCodes.Status400BadRequest,
            _ => StatusCodes.Status500InternalServerError
        };

        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = httpContext.Response.StatusCode,
            Title = "An error occurred",
            Detail = httpContext.Response.StatusCode == 500
                ? "An unexpected error occurred."
                : exception.Message
        }, ct);

        return true;
    }
}

Never expose internal exception details in production. Log the full exception, return a generic message to the client.

Either way, keep the response shape consistent with Problem Details so expected failures and unexpected errors look the same to API consumers.

The Decision Flow

When an error occurs, how do you decide what to do?

1. Invalid input → Validation behavior returns Result.Failure(ValidationError)
2. Entity not found → Handler returns Result.Failure(NotFoundError)
3. Business rule violation (expected) → Handler returns Result.Failure(ConflictError)
4. Domain invariant violated → Domain throws DomainException → global handler catches
5. Infrastructure failure → Exception propagates → global handler catches and logs

Rules of thumb:

• Expected failures → Result<T>
• Programming errors → Exceptions
• Infrastructure issues → Exceptions

Takeaway

A consistent exception handling strategy in Clean Architecture:

1. Domain layer throws exceptions for invariant violations
2. Application layer returns Result<T> for expected business errors
3. Validation happens before the handler via pipeline behaviors
4. The presentation layer maps results to HTTP responses
5. A global exception handler catches unexpected failures

Stop mixing exceptions and return values randomly. Pick a clear strategy and apply it consistently.

Thanks for reading, and stay awesome!

What Is the Domain Layer?

The Domain layer is the innermost layer in Clean Architecture. It sits at the center of the dependency graph, and nothing depends on anything outside of it.

This is where your business rules live. Not HTTP concerns. Not database details. Just the rules that make your business what it is.

The Domain layer contains:

• Entities - objects with identity and lifecycle
• Value Objects - immutable objects defined by their attributes
• Domain Events - notifications that something meaningful happened
• Enumerations - smart enums representing domain concepts
• Domain Services - business logic that doesn't belong to a single entity
• Repository Interfaces - abstractions for data access
• Custom Exceptions - domain-specific error types

Entities

Entities are objects defined by their identity, not their attributes. Two customers with the same name are still different customers.

public abstract class Entity : IEquatable<Entity>
{
    private readonly List<IDomainEvent> _domainEvents = new();

    protected Entity(Guid id)
    {
        Id = id;
    }

    public Guid Id { get; private init; }

    public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    public void ClearDomainEvents() => _domainEvents.Clear();

    protected void RaiseDomainEvent(IDomainEvent domainEvent) =>
        _domainEvents.Add(domainEvent);

    public bool Equals(Entity? other)
    {
        return other is not null && Id == other.Id;
    }

    public override bool Equals(object? obj)
    {
        return obj is Entity entity && Equals(entity);
    }

    public override int GetHashCode() => Id.GetHashCode();
}

The base class also collects domain events (we'll define IDomainEvent in a moment), so entities can record what happened and let an outer layer publish it after saving.

And a concrete entity:

public sealed class Customer : Entity
{
    private Customer(Guid id, string name, Email email) : base(id)
    {
        Name = name;
        Email = email;
    }

    public string Name { get; private set; }
    public Email Email { get; private set; }

    public static Customer Create(string name, Email email)
    {
        var customer = new Customer(Guid.NewGuid(), name, email);

        customer.RaiseDomainEvent(new CustomerCreatedDomainEvent(customer.Id));

        return customer;
    }

    public void UpdateName(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
        {
            throw new DomainException("Customer name cannot be empty.");
        }

        Name = name;
    }
}

Key principles:

• Private constructor - creation goes through a factory method that enforces invariants
• Private setters - state changes go through methods that validate the transition
• Domain events - the entity signals when something important happens

This is what makes the domain model the best place to enforce invariants: there's no way to construct or mutate the entity into an invalid state.

Value Objects

Value Objects represent concepts with no identity. Two Email("test@example.com") instances are equal.

public sealed class Email : ValueObject
{
    private Email(string value) => Value = value;

    public string Value { get; }

    public static Result<Email> Create(string email)
    {
        if (string.IsNullOrWhiteSpace(email) || !email.Contains('@'))
        {
            return Result.Failure<Email>(DomainErrors.Email.InvalidFormat);
        }

        return new Email(email.Trim().ToLowerInvariant());
    }

    protected override IEnumerable<object> GetAtomicValues()
    {
        yield return Value;
    }
}

Use Value Objects to replace primitives wherever a concept has business rules attached to it.

Domain Events

Domain events represent something that happened in the domain. They're raised by entities and handled by the Application layer.

public interface IDomainEvent
{
    Guid Id { get; }
    DateTime OccurredOnUtc { get; }
}

public sealed record CustomerCreatedDomainEvent(Guid CustomerId) : IDomainEvent
{
    public Guid Id { get; } = Guid.NewGuid();
    public DateTime OccurredOnUtc { get; } = DateTime.UtcNow;
}

Domain events live in the Domain layer because they describe domain facts. But the handlers live in the Application layer.

Smart Enumerations

Instead of plain enum types, use smart enums for domain concepts that carry behavior:

public abstract class OrderStatus : Enumeration<OrderStatus>
{
    public static readonly OrderStatus Draft = new DraftStatus();
    public static readonly OrderStatus Confirmed = new ConfirmedStatus();
    public static readonly OrderStatus Shipped = new ShippedStatus();
    public static readonly OrderStatus Delivered = new DeliveredStatus();
    public static readonly OrderStatus Cancelled = new CancelledStatus();

    private OrderStatus(int id, string name) : base(id, name) { }

    public abstract bool CanTransitionTo(OrderStatus next);

    private sealed class DraftStatus : OrderStatus
    {
        public DraftStatus() : base(1, "Draft") { }

        public override bool CanTransitionTo(OrderStatus next) =>
            next == Confirmed || next == Cancelled;
    }

    private sealed class ConfirmedStatus : OrderStatus
    {
        public ConfirmedStatus() : base(2, "Confirmed") { }

        public override bool CanTransitionTo(OrderStatus next) =>
            next == Shipped || next == Cancelled;
    }

    // ... other statuses
}

The state transition rules are embedded in the enum itself. No service needed to check if an order can be cancelled.

The Enumeration<TEnum> base class handles equality and provides static lookups like FromValue and FromName, which is what the Infrastructure layer uses to persist the enum as a string.

Repository Interfaces

Repository interfaces can live in the Domain layer, right next to the aggregates they load and save. That's the convention I'm showing here. Their implementations always go in Infrastructure.

public interface ICustomerRepository
{
    Task<Customer?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
    Task<Customer?> GetByEmailAsync(Email email, CancellationToken cancellationToken = default);
    void Add(Customer customer);
    void Update(Customer customer);
}

This follows the Dependency Rule: the Domain layer defines what it needs, and outer layers provide it.

Note: some developers place repository interfaces in the Application layer instead. Both approaches are valid - the key is that implementations go in Infrastructure either way.

Domain Services

When business logic doesn't naturally belong to a single entity, use a Domain Service:

public sealed class PricingService
{
    public Money CalculateTotal(
        IReadOnlyCollection<OrderLineItem> items,
        DiscountCode? discountCode)
    {
        var subtotal = items.Aggregate(
            Money.Zero(Currency.Usd),
            (sum, item) => sum + item.TotalPrice);

        if (discountCode is not null)
        {
            subtotal = discountCode.Apply(subtotal);
        }

        return subtotal;
    }
}

Domain Services are stateless. They operate on entities and value objects passed to them.

Domain Errors

Define domain-specific errors in the Domain layer:

public static class DomainErrors
{
    public static class Email
    {
        public static readonly Error InvalidFormat = new(
            "Email.InvalidFormat",
            "The email address is not in a valid format.");
    }

    public static class Customer
    {
        public static readonly Error NotFound = new(
            "Customer.NotFound",
            "The customer was not found.");

        public static readonly Error EmailNotUnique = new(
            "Customer.EmailNotUnique",
            "The email address is already in use.");
    }

    public static class Order
    {
        public static readonly Error AlreadyCancelled = new(
            "Order.AlreadyCancelled",
            "The order has already been cancelled.");
    }
}

These errors are used with the Result pattern for explicit error handling without exceptions.

Folder Structure

Domain/
  Customers/
    Customer.cs
    CustomerCreatedDomainEvent.cs
    ICustomerRepository.cs
  Orders/
    Order.cs
    OrderLineItem.cs
    OrderStatus.cs
    OrderCompletedDomainEvent.cs
    IOrderRepository.cs
  Shared/
    Entity.cs
    AggregateRoot.cs
    ValueObject.cs
    IDomainEvent.cs
    Result.cs
    Error.cs
    DomainException.cs

Organize by aggregate or concept, not by pattern type. Don't create folders like Entities/, ValueObjects/, Events/.

What Does NOT Belong in the Domain Layer

• DTOs - those belong in the Application layer
• Database concerns - no DbContext, no [Table] attributes, no migration code
• Logging - the domain doesn't know about ILogger
• External service calls - no HTTP, no message queue access
• Validation with FluentValidation - command/query validation belongs in Application

The Domain layer has zero external package references. It references only .NET base class libraries.

Enforcing the Rules

Use architecture tests to keep the Domain layer pure:

[Fact]
public void Domain_Should_Not_Have_Dependencies_On_Other_Layers()
{
    var result = Types
        .InAssembly(typeof(Customer).Assembly)
        .ShouldNot()
        .HaveDependencyOnAny("Application", "Infrastructure", "Presentation")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

Keep It Pure

The Domain layer is the most stable and valuable part of your Clean Architecture solution. It contains the business rules that make your application unique - everything else is infrastructure.

Keep it pure, keep it focused, and the rest of your architecture will thank you.

Thanks for reading, and stay awesome!

Two Types of Events, Two Different Jobs

Events are central to building loosely coupled systems. But not all events are created equal.

In a well-designed .NET application, you'll typically work with two kinds:

• Domain events - something happened within a bounded context
• Integration events - something happened that other systems need to know about

Confusing the two leads to tight coupling, inconsistent data, and architectural headaches.

Let's clear this up.

What Are Domain Events?

A domain event represents something meaningful that happened in your domain. It's raised by an aggregate and handled within the same bounded context.

public interface IDomainEvent : INotification;

public sealed record OrderPlacedDomainEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount) : IDomainEvent;

IDomainEvent extends MediatR's INotification, so we can dispatch events with IMediator and handle them with INotificationHandler<T>. That couples the domain to MediatR's contracts. If you want a fully pure domain, you can adapt events with a generic wrapper instead; I cover that tradeoff in the Clean Architecture solution template.

When an order is placed, the Order aggregate raises this event:

public class Order : AggregateRoot
{
    public static Order Create(Customer customer, List<LineItem> items)
    {
        var order = new Order(customer.Id, items);

        order.RaiseDomainEvent(new OrderPlacedDomainEvent(
            order.Id,
            order.CustomerId,
            order.TotalAmount));

        return order;
    }
}

Domain events are typically:

• In-process - they execute within the same application, same transaction
• Synchronous (usually) - handlers run before SaveChanges completes or right after
• Private - they stay inside the bounded context that raised them
• Consistent - they maintain strong consistency with the operation that triggered them

What Domain Event Handlers Do

Domain event handlers react to what happened and execute side effects within the same context:

public class OrderPlacedDomainEventHandler : INotificationHandler<OrderPlacedDomainEvent>
{
    private readonly IInventoryService _inventoryService;

    public OrderPlacedDomainEventHandler(IInventoryService inventoryService)
    {
        _inventoryService = inventoryService;
    }

    public async Task Handle(
        OrderPlacedDomainEvent notification,
        CancellationToken cancellationToken)
    {
        await _inventoryService.ReserveStockAsync(notification.OrderId);
    }
}

Common uses for domain event handlers:

• Updating related data within the same aggregate or module
• Enforcing business rules that span multiple entities
• Preparing data for projections or read models

For a full implementation guide, see my article on domain events in .NET.

What Are Integration Events?

An integration event represents something that happened that other bounded contexts or external systems need to react to.

public interface IIntegrationEvent;

public sealed record OrderPlacedIntegrationEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount,
    DateTime OccurredAt) : IIntegrationEvent;

Integration events are:

• Published to a message broker (RabbitMQ, Azure Service Bus, Amazon SQS)
• Asynchronous - consumers process them at their own pace
• Public - they cross bounded context boundaries
• Eventually consistent - there's a delay between publishing and consuming

Publishing Integration Events

You typically publish integration events after the domain transaction succeeds. This is where the Outbox pattern becomes critical - you need to guarantee that the event gets published even if the application crashes after saving.

public class PublishOrderPlacedIntegrationEventHandler
    : INotificationHandler<OrderPlacedDomainEvent>
{
    private readonly IOutboxWriter _outbox;

    public PublishOrderPlacedIntegrationEventHandler(IOutboxWriter outbox)
    {
        _outbox = outbox;
    }

    public async Task Handle(
        OrderPlacedDomainEvent notification,
        CancellationToken cancellationToken)
    {
        // Convert domain event to integration event
        var integrationEvent = new OrderPlacedIntegrationEvent(
            notification.OrderId,
            notification.CustomerId,
            notification.TotalAmount,
            DateTime.UtcNow);

        // Write to outbox (same transaction as domain changes)
        await _outbox.WriteAsync(integrationEvent, cancellationToken);
    }
}

MediatR runs every handler registered for a notification, so this handler executes alongside the inventory handler from earlier. One reacts inside the bounded context, the other hands the event off to the outside world.

A background process picks up outbox messages and publishes them to the message broker.

Key Differences

Here's how the two compare, aspect by aspect:

• Scope: domain events stay within a bounded context; integration events cross bounded context boundaries.
• Transport: domain events travel in-memory (MediatR or a custom dispatcher); integration events go through a message broker (RabbitMQ, Azure Service Bus, SQS).
• Consistency: domain events can participate in the same transaction; integration events are eventually consistent.
• Failure handling: domain event side effects roll back with the transaction; integration events need retries and idempotent consumers.
• Schema: a domain event is internal and can change freely; an integration event is a public contract that needs versioning.
• Timing: domain events are handled immediately; integration events are processed with a delay, at the consumer's pace.

The Flow: Domain Event → Integration Event

In a well-architected system, the flow looks like this:

1. An aggregate performs a business operation
2. The aggregate raises a domain event
3. A domain event handler processes the event within the same transaction
4. If other bounded contexts need to know, the handler writes an integration event to the outbox
5. A background worker publishes the integration event to the message broker
6. Consumers in other bounded contexts receive and process the event

This two-step approach gives you the best of both worlds:

• Strong consistency for domain-level side effects
• Reliable asynchronous delivery for cross-boundary communication

Publishing Domain Events With EF Core

A common pattern is to dispatch domain events when SaveChanges is called. You can use an EF Core interceptor for this:

public class PublishDomainEventsInterceptor : SaveChangesInterceptor
{
    private readonly IMediator _mediator;

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

    public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        var dbContext = eventData.Context;

        if (dbContext is null)
        {
            return result;
        }

        var aggregates = dbContext.ChangeTracker
            .Entries<AggregateRoot>()
            .Select(entry => entry.Entity)
            .Where(aggregate => aggregate.DomainEvents.Count > 0)
            .ToList();

        var domainEvents = aggregates
            .SelectMany(aggregate => aggregate.DomainEvents)
            .ToList();

        foreach (var aggregate in aggregates)
        {
            aggregate.ClearDomainEvents();
        }

        foreach (var domainEvent in domainEvents)
        {
            await _mediator.Publish(domainEvent, cancellationToken);
        }

        return result;
    }
}

One important subtlety: this interceptor uses SavingChangesAsync, which runs before the save completes. Handlers execute inside the same transaction, so anything they add through the change tracker (like an outbox message) commits atomically with the domain changes. That's exactly what the outbox handler above needs. If your handlers only have side effects independent of the transaction, you can dispatch from SavedChangesAsync after the commit instead. Just don't write to the outbox from there; dispatching after the commit reintroduces the exact dual-write problem the outbox is supposed to solve.

I wrote a dedicated guide on building a custom domain events dispatcher if you want the full implementation.

Integration Event Contracts

Since integration events cross boundaries, their schema is a public contract. Treat them like an API:

• Version them - don't break consumers when you change the event
• Keep them minimal - only include what consumers need
• Use primitive types - avoid domain-specific types that consumers would need to reference
• Document them - consumers need to know what to expect

// ✅ Good: minimal, self-contained, uses primitives
public sealed record OrderPlacedIntegrationEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount,
    DateTime OccurredAt);

// ❌ Bad: leaks domain details, forces consumers to reference your domain assembly
public sealed record OrderPlacedIntegrationEvent(
    Order Order,
    Customer Customer,
    List<LineItem> LineItems);

Consuming Integration Events

Consumers in other bounded contexts subscribe to integration events through the message broker. Two critical patterns apply:

1. Idempotent Consumer - handle the same message multiple times safely
2. Inbox pattern - deduplicate incoming messages before processing

Here's what that looks like in a MassTransit consumer:

public class OrderPlacedIntegrationEventConsumer
    : IConsumer<OrderPlacedIntegrationEvent>
{
    private readonly IInboxStore _inbox;
    private readonly IEmailService _emailService;

    public OrderPlacedIntegrationEventConsumer(
        IInboxStore inbox,
        IEmailService emailService)
    {
        _inbox = inbox;
        _emailService = emailService;
    }

    public async Task Consume(ConsumeContext<OrderPlacedIntegrationEvent> context)
    {
        if (await _inbox.HasBeenProcessedAsync(context.MessageId))
        {
            return; // Already processed - skip
        }

        var message = context.Message;

        // Handle the event
        await _emailService.SendOrderConfirmationAsync(
            message.CustomerId,
            message.OrderId);

        await _inbox.MarkAsProcessedAsync(context.MessageId);
    }
}

When to Use Domain Events

Use domain events when:

• Side effects must be consistent with the main operation
• The handler lives in the same bounded context
• You need immediate execution (same request lifecycle)
• Example: reserving inventory when an order is placed

When to Use Integration Events

Use integration events when:

• Another bounded context or service needs to react
• Eventual consistency is acceptable
• You need reliable delivery across process boundaries
• Example: sending an email confirmation from the Notification service

Common Mistakes

1. Publishing integration events synchronously. Integration events should go through a message broker, not through direct HTTP calls. Direct calls create temporal coupling and fragile systems.

2. Putting too much data in integration events. Only include what consumers need. If a consumer needs more details, it can query the originating service.

3. Using domain events across bounded contexts. Domain events are internal. If another context needs the information, create an integration event with a separate schema.

4. Skipping the Outbox pattern. Without the Outbox, you risk losing events if the app crashes between saving to the database and publishing to the broker.

The Golden Rule

Domain events keep your bounded context consistent. Integration events keep your system loosely coupled.

The golden rule: domain events stay inside, integration events go outside.

Use domain events for immediate side effects within the same transaction. Use integration events for asynchronous communication across boundaries. And always use the Outbox pattern to guarantee delivery.

Thanks for reading, and stay awesome!

What Is the Dependency Rule?

Robert C. Martin defines it simply:

Source code dependencies must only point inward.

In Clean Architecture, the application is organized in concentric circles:

1. Domain (innermost) - entities, value objects, domain events
2. Application - use cases, commands, queries, interfaces
3. Infrastructure (outermost) - database access, external services, frameworks

The Dependency Rule says: nothing in an inner circle can know anything about an outer circle.

• Domain doesn't reference Application
• Application doesn't reference Infrastructure
• Infrastructure references Application and Domain

Arrows always point inward. Never outward.

Why the Dependency Rule Matters

Without it, your domain logic gets polluted with infrastructure concerns:

// WRONG - Domain depends on Infrastructure
public class Order
{
    public void Confirm()
    {
        // Domain class knows about EF Core
        using var context = new AppDbContext();
        context.Orders.Update(this);
        context.SaveChanges();

        // Domain class knows about email service
        var emailService = new SendGridEmailService();
        emailService.Send(this.CustomerEmail, "Order confirmed!");
    }
}

This code can't be tested without a database and an email service. It can't be reused in a different context. And changing your email provider means changing your domain.

With the Dependency Rule:

// RIGHT - Domain knows nothing about infrastructure
public class Order
{
    public void Confirm()
    {
        // Pure business logic
        Status = OrderStatus.Confirmed;
        ConfirmedAt = DateTime.UtcNow;
        RaiseDomainEvent(new OrderConfirmedDomainEvent(Id));
    }
}

The domain is pure. How to persist the order and send the email is handled by outer layers.

How to Enforce It in .NET

Project References

Set up your project references to match the Dependency Rule:

<!-- Domain - references NOTHING -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

<!-- Application - references Domain only -->
<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <ProjectReference Include="..\Domain\Domain.csproj" />
  </ItemGroup>
</Project>

<!-- Infrastructure - references Application (and Domain transitively) -->
<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <ProjectReference Include="..\Application\Application.csproj" />
  </ItemGroup>
</Project>

<!-- API - references Infrastructure and Application -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <ItemGroup>
    <ProjectReference Include="..\Application\Application.csproj" />
    <ProjectReference Include="..\Infrastructure\Infrastructure.csproj" />
  </ItemGroup>
</Project>

The compiler enforces this. If Domain tries to reference an Infrastructure class, it won't compile.

Dependency Inversion

The Application layer defines interfaces. The Infrastructure layer implements them:

// Application layer - defines what it needs
public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct);
    void Add(Order order);
}

public interface IEmailService
{
    Task SendOrderConfirmationAsync(string email, Guid orderId, CancellationToken ct);
}

// Infrastructure layer - implements using specific technology
public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _dbContext;

    public OrderRepository(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
    {
        return await _dbContext.Orders
            .Include(o => o.LineItems)
            .FirstOrDefaultAsync(o => o.Id == id, ct);
    }

    public void Add(Order order) => _dbContext.Orders.Add(order);
}

The Application layer calls IOrderRepository. It doesn't know (or care) that Entity Framework Core is behind it.

This is the Dependency Inversion Principle at work - high-level modules (Application) don't depend on low-level modules (Infrastructure). Both depend on abstractions.

Flow of Control vs Source Dependencies

Here's the part that confuses most people when they first meet the Dependency Rule.

At runtime, control flows outward: the Application layer calls the database, sends emails, publishes messages. So how can dependencies point inward?

Because a source dependency is about what your code references at compile time, not who calls whom at runtime.

Walk through a single request:

1. The API controller (outer) calls a command handler (inner). Control flows inward, dependency points inward. No conflict.
2. The handler calls IOrderRepository.GetByIdAsync(...). Control is about to flow outward into EF Core, but the handler only references an interface it owns.
3. The DI container resolved IOrderRepository to OrderRepository from Infrastructure at startup. The call lands in the outer layer without the inner layer ever naming it.

The interface is the trick. It lets control flow outward while the compile-time arrow keeps pointing inward. When you see a diagram of Clean Architecture, the arrows show source dependencies, not call direction.

The Rule Applies to NuGet Packages Too

Project references are only half the story. A Domain project with zero project references but a Microsoft.EntityFrameworkCore package reference violates the Dependency Rule just the same.

My guidelines:

• Domain: no packages. Entities, value objects, and domain events are plain C#.
• Application: contracts-only packages at most (MediatR contracts, FluentValidation). No EF Core, no HTTP clients, no cloud SDKs.
• Infrastructure: this is where the package weight belongs - EF Core, message brokers, external SDKs.

The gray zone is logging. Microsoft.Extensions.Logging.Abstractions in the Application layer is a pragmatic exception most teams accept: it's an abstraction package with no implementation baggage.

Where Does the DI Container Fit?

Someone has to know about all the layers to wire them together. That's the composition root: the API project's Program.cs.

The outermost layer referencing everything isn't a violation. It's the design: the most volatile, framework-heavy project depends on everything, and nothing depends on it.

builder.Services
    .AddApplication()       // handlers, validators, behaviors
    .AddInfrastructure(builder.Configuration); // EF Core, email, auth

If you find yourself wanting to resolve services inside the Domain layer (service locator style), that's the Dependency Rule being violated at runtime even though the compiler is happy. Domain objects receive what they need as method parameters; they don't ask a container.

What Breaks the Dependency Rule

1. Framework Attributes in Domain

// WRONG - Domain depends on EF Core
public class Order
{
    [Key]
    public Guid Id { get; set; }

    [Required]
    [MaxLength(100)]
    public string CustomerName { get; set; }
}

Fix: Use EF Core's Fluent API configuration in the Infrastructure layer:

// Infrastructure layer
public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> builder)
    {
        builder.HasKey(o => o.Id);
        builder.Property(o => o.CustomerName).IsRequired().HasMaxLength(100);
    }
}

2. Using Concrete Services in Application

// WRONG - Application depends on Infrastructure
public class PlaceOrderCommandHandler
{
    private readonly AppDbContext _dbContext;  // Infrastructure class
}

Fix: Depend on abstractions defined in the Application layer:

// RIGHT - Application depends on its own interfaces
public class PlaceOrderCommandHandler
{
    private readonly IOrderRepository _repository;
    private readonly IUnitOfWork _unitOfWork;
}

3. Leaking Infrastructure Types

// WRONG - Application returns infrastructure types
public class GetOrderQueryHandler
{
    public async Task<DbSet<Order>> Handle(GetOrderQuery query)
    {
        return _dbContext.Orders;  // Leaking DbSet<T>
    }
}

Fix: Map to DTOs or domain objects:

public async Task<OrderResponse?> Handle(GetOrderQuery query)
{
    return await _dbContext.Orders
        .Where(o => o.Id == query.OrderId)
        .Select(o => new OrderResponse(
            o.Id,
            o.Customer.Name,
            o.TotalAmount.Amount,
            o.Status.Name,
            o.CreatedAt))
        .FirstOrDefaultAsync();
}

Architecture Tests

Enforce the Dependency Rule automatically with architecture tests:

[Fact]
public void Domain_Should_Not_Reference_Application()
{
    var result = Types
        .InAssembly(typeof(Order).Assembly)
        .ShouldNot()
        .HaveDependencyOn(typeof(PlaceOrderCommand).Assembly.GetName().Name)
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

[Fact]
public void Domain_Should_Not_Reference_Infrastructure()
{
    var result = Types
        .InAssembly(typeof(Order).Assembly)
        .ShouldNot()
        .HaveDependencyOn(typeof(AppDbContext).Assembly.GetName().Name)
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

[Fact]
public void Application_Should_Not_Reference_Infrastructure()
{
    var result = Types
        .InAssembly(typeof(PlaceOrderCommand).Assembly)
        .ShouldNot()
        .HaveDependencyOn(typeof(AppDbContext).Assembly.GetName().Name)
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

Run these in CI. If someone adds a wrong dependency, the build fails.

I wrote more about this approach in enforcing software architecture with architecture tests, including rules that go beyond layer references (naming conventions, sealed handlers, interface placement).

Violating the Dependency Rule is also the most common of the Clean Architecture anti-patterns I see in real codebases - usually starting with a single EF Core attribute on a domain entity.

Three Layers of Defense

The Dependency Rule is the foundation of Clean Architecture. It keeps your domain and application logic independent of frameworks, databases, and external services.

Enforce it through:

1. Project references - the compiler prevents invalid dependencies
2. Dependency Inversion - interfaces in Application, implementations in Infrastructure
3. Architecture tests - automated verification in CI

Get the Dependency Rule right, and everything else in Clean Architecture falls into place.

Thanks for reading, and stay awesome!

Three Names, One Goal

If you've been reading about software architecture, you've probably encountered three similar-looking approaches:

• Clean Architecture (Robert C. Martin, 2012)
• Onion Architecture (Jeffrey Palermo, 2008)
• Hexagonal Architecture / Ports and Adapters (Alistair Cockburn, 2005)

They all aim at the same thing: keep your business logic independent of frameworks, databases, and external concerns.

The core insight behind all three is the Dependency Rule - dependencies point inward. Infrastructure depends on your domain, never the other way around.

So what's actually different?

Hexagonal Architecture (Ports and Adapters)

Hexagonal Architecture was the first of the three, introduced by Alistair Cockburn in 2005.

The key concept is simple: your application has a core (the hexagon) surrounded by ports and adapters.

• Ports are interfaces that define how the application talks to the outside world (and vice versa)
• Adapters are implementations that connect those ports to real infrastructure

There are two types of ports:

• Driving ports (primary) - how the outside world talks to your application (e.g., an HTTP controller calling a use case)
• Driven ports (secondary) - how your application talks to external systems (e.g., a repository interface for database access)

The hexagon itself contains your business logic. It doesn't know about HTTP, databases, or message queues.

Strengths:

• The ports/adapters mental model is intuitive
• Makes testability explicit - you test by plugging in fake adapters
• Symmetric - treats all external concerns equally (UI, database, messaging)

In .NET terms: Your domain and application logic sit in one project. Interfaces (ports) define the boundaries. Infrastructure implementations (adapters) connect to real systems.

Onion Architecture

Jeffrey Palermo introduced Onion Architecture in 2008, building on the hexagonal idea with a more explicit layer structure.

The architecture is organized in concentric rings:

1. Domain Model (center) - entities, value objects, domain logic
2. Domain Services - business operations that span multiple entities
3. Application Services - use case orchestration, DTOs
4. Infrastructure (outer ring) - database, file system, external services

The rules are:

• Inner layers define interfaces
• Outer layers provide implementations
• Dependencies always point inward

Strengths:

• Clearer layer separation than hexagonal
• Explicit placement of domain services
• The "onion rings" visualization is easy to communicate

In .NET terms: You typically create separate projects for each ring - Domain, Application, Infrastructure, and Presentation.

Clean Architecture

Robert C. Martin formalized Clean Architecture in 2012, combining ideas from hexagonal and onion architectures.

The layers are:

1. Entities (Enterprise Business Rules) - core business objects
2. Use Cases (Application Business Rules) - application-specific logic
3. Interface Adapters - controllers, presenters, gateways
4. Frameworks & Drivers - web framework, database, external tools

Clean Architecture adds explicit concepts like:

• Use Cases as first-class citizens
• Input/Output boundaries between layers
• The Dependency Rule stated explicitly

Strengths:

• Most prescriptive of the three - clear guidance on where things go
• Use cases are front and center
• Strong community adoption in .NET (thanks to common templates and structured guides)

In .NET terms: The typical project structure is Domain, Application, Infrastructure, Presentation - which happens to match the Onion Architecture layout closely.

Side-by-Side Comparison

Here's how the three approaches stack up:

Hexagonal Architecture (2005)

• Core concept: ports and adapters around an application core
• Layer names: Application, Ports, Adapters
• Primary focus: treating all external systems symmetrically
• Testing approach: swap real adapters for fakes
• Prescriptiveness: low - it's a mental model more than a structure
• .NET adoption: moderate; the terminology shows up more than the literal structure

Onion Architecture (2008)

• Core concept: concentric rings with the domain model at the center
• Layer names: Domain Model, Domain Services, Application Services, Infrastructure
• Primary focus: layer discipline and interface ownership by inner rings
• Testing approach: mock the interfaces defined by inner layers
• Prescriptiveness: medium
• .NET adoption: moderate; historically popular in the .NET community where it originated

Clean Architecture (2012)

• Core concept: the Dependency Rule plus use cases as first-class citizens
• Layer names: Entities, Use Cases, Interface Adapters, Frameworks & Drivers
• Primary focus: isolating application-specific business rules
• Testing approach: test use cases independently of infrastructure
• Prescriptiveness: high - the most opinionated of the three
• .NET adoption: very high, with widely used templates and guides

What They Have in Common

All three share these core principles:

1. Business logic at the center - domain code has zero dependencies on infrastructure
2. Dependency inversion - outer layers depend on inner layers, never the reverse
3. Testability by design - you can test business logic without databases, HTTP, or external services
4. Framework independence - swapping a web framework or database shouldn't require rewriting business rules
5. Interfaces as boundaries - abstractions define how layers communicate

In practice, a .NET solution following any of these three architectures looks remarkably similar. The same four rings show up under different names, with dependencies always pointing inward:

The naming differs. The structure is nearly identical.

Which Should You Choose?

Honestly? It doesn't matter as much as you think.

All three solve the same problem. If you understand the core principles - dependency inversion, business logic at the center, infrastructure at the edges - you can build clean systems with any of them.

That said, here's a practical decision guide:

Choose Clean Architecture when:

• You want clear, prescriptive guidance
• Your team benefits from a well-known, widely documented approach
• You're building in .NET (the ecosystem has strong support with templates and courses)

Choose Hexagonal when:

• You want maximum flexibility in how you structure things
• You work in a polyglot environment where the ports/adapters terminology is common
• You're focused on adapter swappability (testing, multi-channel systems)

Choose Onion when:

• You want layer discipline without the prescriptiveness of Clean Architecture
• You prefer the rings mental model for communicating with your team

Or don't choose at all: If your project is simple, a Vertical Slice Architecture might be more practical. Not every project needs concentric rings. I've written a separate guide on when to use Clean Architecture if you're on the fence.

Common Mistakes

1. Treating the choice as binary. You can mix ideas. Use Clean Architecture's use case structure with Hexagonal's ports and adapters terminology. The principles are compatible.

2. Over-engineering small projects. A CRUD API with five endpoints doesn't need four projects. Start simple and add architecture when complexity demands it.

3. Arguing about names instead of principles. The Dependency Rule matters more than whether you call it a "port" or an "interface". Focus on the direction of dependencies, not the labels.

4. Forgetting that architecture is a means, not an end. The goal is maintainable, testable software. If your architecture makes the codebase harder to work with, you've missed the point.

Principles Over Labels

Clean Architecture, Onion Architecture, and Hexagonal Architecture are variations of the same idea: protect your business logic by making infrastructure depend on your domain, not the other way around.

They differ in naming, structure, and emphasis - but the principles are identical.

Pick the one your team understands best, and focus on applying the principles consistently.

Thanks for reading, and stay awesome!

Why a Solution Template?

Every time you start a new Clean Architecture project, you repeat the same steps - creating projects, adding references, configuring DI, setting up MediatR, adding FluentValidation. A solution template saves hours and ensures consistency.

Here's the complete setup I use for production projects.

The Solution Structure

src/
  MyApp.Domain/
  MyApp.Application/
  MyApp.Infrastructure/
  MyApp.Persistence/
  MyApp.Api/
tests/
  MyApp.Domain.UnitTests/
  MyApp.Application.UnitTests/
  MyApp.Infrastructure.IntegrationTests/
  MyApp.Api.FunctionalTests/
  MyApp.ArchitectureTests/

Five source projects. Four layers plus a separate Persistence project (you can merge Infrastructure and Persistence if you prefer - I only split them when the infrastructure surface grows).

Project References (The Dependency Rule)

The dependency rule is the non-negotiable constraint. Every project reference points inward, toward Domain:

Domain depends on nothing. Application depends only on Domain. Infrastructure and Persistence depend on Application. The API project wires everything together.

Domain Project

The Domain layer contains entities, value objects, domain events, and domain exceptions. No NuGet packages:

<!-- MyApp.Domain.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

Domain/
  Entities/
    Order.cs
    Customer.cs
    Product.cs
  ValueObjects/
    Money.cs
    Address.cs
    Email.cs
  Events/
    OrderPlacedDomainEvent.cs
    OrderCancelledDomainEvent.cs
  Exceptions/
    DomainException.cs
  Repositories/
    IOrderRepository.cs
    ICustomerRepository.cs
  Primitives/
    Entity.cs
    AggregateRoot.cs
    IDomainEvent.cs
    IUnitOfWork.cs
    Result.cs
    Error.cs

Base classes:

public abstract class Entity
{
    public Guid Id { get; protected init; }
}

public abstract class AggregateRoot : Entity
{
    private readonly List<IDomainEvent> _domainEvents = [];

    public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents;

    protected void RaiseDomainEvent(IDomainEvent domainEvent) =>
        _domainEvents.Add(domainEvent);

    public void ClearDomainEvents() => _domainEvents.Clear();
}

public interface IDomainEvent;

Notice that IDomainEvent is a plain marker interface. A lot of templates declare it as IDomainEvent : MediatR.INotification, which quietly gives your Domain project a MediatR dependency and contradicts the "no packages" rule.

You have two honest options:

1. Keep the domain pure (what I show above) and adapt domain events to MediatR notifications in the Application layer with a generic wrapper.
2. Accept the tradeoff and reference MediatR.Contracts from Domain. It's a contracts-only package, but it still couples your domain to a library. And with MediatR going commercial, coupling your innermost layer to it deserves a second thought.

Either is workable. Just make the choice deliberately instead of inheriting it from a template.

Application Project

The Application layer contains use cases, validation, CQRS abstractions, and behaviors.

<!-- MyApp.Application.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="FluentValidation.DependencyInjectionExtensions" />
    <PackageReference Include="MediatR" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\MyApp.Domain\MyApp.Domain.csproj" />
  </ItemGroup>
</Project>

Application/
  Abstractions/
    Messaging/
      ICommand.cs
      ICommandHandler.cs
      IQuery.cs
      IQueryHandler.cs
    ICurrentUserService.cs
    IDateTimeProvider.cs
    IEmailService.cs
  Behaviors/
    ValidationBehavior.cs
    LoggingBehavior.cs
  Orders/
    PlaceOrder/
      PlaceOrderCommand.cs
      PlaceOrderCommandHandler.cs
      PlaceOrderValidator.cs
    GetOrderById/
      GetOrderByIdQuery.cs
      GetOrderByIdQueryHandler.cs
      OrderResponse.cs
  DependencyInjection.cs

CQRS abstractions:

public interface ICommand : IRequest<Result>;
public interface ICommand<TResponse> : IRequest<Result<TResponse>>;

public interface ICommandHandler<TCommand>
    : IRequestHandler<TCommand, Result>
    where TCommand : ICommand;

public interface ICommandHandler<TCommand, TResponse>
    : IRequestHandler<TCommand, Result<TResponse>>
    where TCommand : ICommand<TResponse>;

public interface IQuery<TResponse> : IRequest<Result<TResponse>>;

public interface IQueryHandler<TQuery, TResponse>
    : IRequestHandler<TQuery, Result<TResponse>>
    where TQuery : IQuery<TResponse>;

These thin interfaces buy you two things: every handler returns a Result, and pipeline behaviors can target commands or queries specifically (validate commands, cache queries).

DI registration:

// Application/DependencyInjection.cs
public static class DependencyInjection
{
    public static IServiceCollection AddApplication(
        this IServiceCollection services)
    {
        var assembly = typeof(DependencyInjection).Assembly;

        services.AddMediatR(config =>
        {
            config.RegisterServicesFromAssembly(assembly);
            config.AddOpenBehavior(typeof(ValidationBehavior<,>));
            config.AddOpenBehavior(typeof(LoggingBehavior<,>));
        });

        services.AddValidatorsFromAssembly(assembly);

        return services;
    }
}

Persistence Project

Handles EF Core configuration:

<!-- MyApp.Persistence.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore" />
    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\MyApp.Application\MyApp.Application.csproj" />
  </ItemGroup>
</Project>

Persistence/
  ApplicationDbContext.cs
  Configurations/
    OrderConfiguration.cs
    CustomerConfiguration.cs
  Repositories/
    OrderRepository.cs
    CustomerRepository.cs
  DependencyInjection.cs

// Persistence/DependencyInjection.cs
public static class DependencyInjection
{
    public static IServiceCollection AddPersistence(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseNpgsql(
                configuration.GetConnectionString("Database")));

        services.AddScoped<IUnitOfWork>(sp =>
            sp.GetRequiredService<ApplicationDbContext>());

        services.AddScoped<IOrderRepository, OrderRepository>();
        services.AddScoped<ICustomerRepository, CustomerRepository>();

        return services;
    }
}

Infrastructure Project

The Infrastructure layer handles external concerns - email, caching, authentication, file storage:

Infrastructure/
  Authentication/
    CurrentUserService.cs
    JwtConfiguration.cs
  Email/
    EmailService.cs
  Caching/
    CacheService.cs
  Time/
    DateTimeProvider.cs
  DependencyInjection.cs

// Infrastructure/DependencyInjection.cs
public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddScoped<ICurrentUserService, CurrentUserService>();
        services.AddSingleton<IDateTimeProvider, DateTimeProvider>();
        services.AddTransient<IEmailService, EmailService>();

        services.AddJwtAuthentication(configuration);

        return services;
    }
}

API Project

The entry point. Wires everything together:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddApplication()
    .AddPersistence(builder.Configuration)
    .AddInfrastructure(builder.Configuration);

builder.Services.AddOpenApi();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseAuthentication();
app.UseAuthorization();

app.MapOrderEndpoints();
app.MapCustomerEndpoints();

app.Run();

A few deliberate choices here:

• AddOpenApi()/MapOpenApi() is the built-in OpenAPI support in .NET 9+; no Swashbuckle package needed.
• The exception handler is registered as a service (IExceptionHandler) and UseExceptionHandler() sits at the top of the pipeline, so it catches failures from everything after it.
• Each layer contributes exactly one AddX() extension method. Program.cs stays readable at a glance.

The Architecture Tests Project

The template isn't complete without tests that keep it honest. The MyApp.ArchitectureTests project enforces the dependency rule in CI:

[Fact]
public void Domain_Should_Not_Reference_Other_Projects()
{
    var result = Types
        .InAssembly(typeof(Entity).Assembly)
        .ShouldNot()
        .HaveDependencyOnAny("MyApp.Application", "MyApp.Infrastructure",
            "MyApp.Persistence", "MyApp.Api")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

Without this, the template's project references are just a suggestion. I shared my five go-to rules in 5 architecture tests you should add to your .NET projects.

Should You Use an Existing Template?

There are excellent public templates (Jason Taylor's Clean Architecture template and Ardalis' Clean Architecture solution are the best known). They're great for learning the patterns.

But I'd still encourage you to build your own, for two reasons:

1. Public templates encode someone else's defaults. Identity setup, mapping libraries, front-end scaffolding - you'll spend the first day deleting things.
2. The best template is a project you already shipped. Strip out the business logic, keep the skeleton, and you have a starting point that matches how your team actually works.

My own version of this setup is the foundation of Pragmatic Clean Architecture, where I walk through every one of these decisions in depth.

Creating the Template

To turn the solution into a dotnet new template, create a .template.config/template.json file in the solution root:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": ["Web", "Clean Architecture"],
  "identity": "CleanArchitecture.Template",
  "name": "Clean Architecture Solution",
  "shortName": "cleanarch",
  "sourceName": "MyApp",
  "tags": {
    "language": "C#",
    "type": "solution"
  }
}

The sourceName means every occurrence of "MyApp" in filenames and file content gets replaced with whatever name you pass via -n.

Then install the template and create new solutions from it:

dotnet new install ./path/to/template
dotnet new cleanarch -n MyApp

Takeaway

A Clean Architecture solution template for .NET needs:

1. Five projects - Domain, Application, Infrastructure, Persistence, Api
2. Strict dependency rule - references only flow inward
3. CQRS abstractions - ICommand, IQuery, handlers, pipeline behaviors
4. DI extension methods - one AddX() per project
5. Base primitives - Entity, AggregateRoot, IDomainEvent, Result
6. Architecture tests - the dependency rule enforced in CI, not just in a diagram

Set it up once and reuse it across every project.

Thanks for reading, and stay awesome!

Why Minimal APIs With Clean Architecture?

Minimal APIs give you a lightweight, low-ceremony way to define HTTP endpoints in ASP.NET Core.

Clean Architecture gives you a structured way to organize business logic independently from infrastructure.

Together, they create a Presentation layer that's thin, readable, and easy to maintain. Your Minimal API endpoints become simple adapters that translate HTTP requests into commands/queries and return HTTP responses.

The Architecture

An HTTP request flows through the Minimal API endpoint into an Application layer command or query, and the result flows back out as an HTTP response:

The Api project is a thin coordination layer. It has two jobs:

1. Map HTTP requests to Application layer commands and queries
2. Map Application layer results back to HTTP responses

Defining an Endpoint

Here's a Minimal API endpoint that calls a command handler:

app.MapPost("/api/orders", async (
    PlaceOrderRequest request,
    ICommandHandler<PlaceOrderCommand, Guid> handler,
    CancellationToken cancellationToken) =>
{
    var command = new PlaceOrderCommand(request.CustomerId, request.Items);

    var result = await handler.Handle(command, cancellationToken);

    return result.IsSuccess
        ? Results.Created($"/api/orders/{result.Value}", new { id = result.Value })
        : result.ToProblemDetails();
});

The endpoint:

1. Receives the HTTP request
2. Creates a command from the request body
3. Passes it to the handler (from the Application layer)
4. Returns an appropriate HTTP response

No business logic. No database calls. Just request/response translation.

One note on wiring: the endpoint resolves ICommandHandler<PlaceOrderCommand, Guid> straight from DI. That works when your handlers are registered against these interfaces (a single Scrutor assembly scan handles it). If you're using MediatR, inject ISender and call Send instead; the shape of the endpoint stays the same.

Organizing Endpoints

Minimal APIs can get messy if you dump everything into Program.cs. Organize them using static classes:

public static class OrderEndpoints
{
    public static void MapOrderEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders")
            .WithTags("Orders");

        group.MapPost("", PlaceOrder);
        group.MapGet("{orderId:guid}", GetOrderById);
        group.MapPut("{orderId:guid}/cancel", CancelOrder);
        group.MapGet("", GetOrders);
    }

    private static async Task<IResult> PlaceOrder(
        PlaceOrderRequest request,
        ICommandHandler<PlaceOrderCommand, Guid> handler,
        CancellationToken cancellationToken)
    {
        var command = new PlaceOrderCommand(request.CustomerId, request.Items);

        var result = await handler.Handle(command, cancellationToken);

        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", new { id = result.Value })
            : result.ToProblemDetails();
    }

    private static async Task<IResult> GetOrderById(
        Guid orderId,
        IQueryHandler<GetOrderByIdQuery, OrderResponse> handler,
        CancellationToken cancellationToken)
    {
        var query = new GetOrderByIdQuery(orderId);

        var result = await handler.Handle(query, cancellationToken);

        return result.IsSuccess
            ? Results.Ok(result.Value)
            : Results.NotFound();
    }

    private static async Task<IResult> CancelOrder(
        Guid orderId,
        ICommandHandler<CancelOrderCommand> handler,
        CancellationToken cancellationToken)
    {
        var command = new CancelOrderCommand(orderId);

        var result = await handler.Handle(command, cancellationToken);

        return result.IsSuccess
            ? Results.NoContent()
            : result.ToProblemDetails();
    }

    private static async Task<IResult> GetOrders(
        [AsParameters] GetOrdersRequest request,
        IQueryHandler<GetOrdersQuery, PagedList<OrderSummary>> handler,
        CancellationToken cancellationToken)
    {
        var query = new GetOrdersQuery(request.Page, request.PageSize);

        var result = await handler.Handle(query, cancellationToken);

        return result.IsSuccess
            ? Results.Ok(result.Value)
            : result.ToProblemDetails();
    }
}

Then register them in Program.cs:

app.MapOrderEndpoints();
app.MapCustomerEndpoints();
app.MapProductEndpoints();

Each feature gets its own endpoint file. This follows the Screaming Architecture principle.

I shared more variations of this approach in how to structure Minimal APIs. And if you want to skip the manual Map* calls in Program.cs, you can register Minimal API endpoints automatically with a bit of reflection.

Using Carter for Endpoint Organization

Carter provides a module system for organizing Minimal API endpoints:

public class OrderModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/orders").WithTags("Orders");

        group.MapPost("", PlaceOrder);
        group.MapGet("{orderId:guid}", GetOrderById);
    }

    private static async Task<IResult> PlaceOrder(
        PlaceOrderRequest request,
        ICommandHandler<PlaceOrderCommand, Guid> handler,
        CancellationToken cancellationToken)
    {
        var command = new PlaceOrderCommand(request.CustomerId, request.Items);
        var result = await handler.Handle(command, cancellationToken);

        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", new { id = result.Value })
            : result.ToProblemDetails();
    }

    private static async Task<IResult> GetOrderById(
        Guid orderId,
        IQueryHandler<GetOrderByIdQuery, OrderResponse> handler,
        CancellationToken cancellationToken)
    {
        var query = new GetOrderByIdQuery(orderId);
        var result = await handler.Handle(query, cancellationToken);

        return result.IsSuccess ? Results.Ok(result.Value) : Results.NotFound();
    }
}

Carter auto-discovers modules and registers them:

builder.Services.AddCarter();
// ...
app.MapCarter();

Adding Endpoint Filters

Endpoint Filters are the Minimal API equivalent of action filters. Use them for cross-cutting concerns:

public class ValidationFilter<TRequest> : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var request = context.Arguments.OfType<TRequest>().FirstOrDefault();

        if (request is null)
        {
            return Results.BadRequest("Invalid request.");
        }

        var validator = context.HttpContext
            .RequestServices
            .GetService<IValidator<TRequest>>();

        if (validator is not null)
        {
            var validationResult = await validator.ValidateAsync(request);
            if (!validationResult.IsValid)
            {
                return Results.ValidationProblem(validationResult.ToDictionary());
            }
        }

        return await next(context);
    }
}

Apply it to endpoints:

group.MapPost("", PlaceOrder)
    .AddEndpointFilter<ValidationFilter<PlaceOrderRequest>>();

Mapping Results to HTTP Responses

Create an extension method that maps your Result pattern to Problem Details responses:

public static class ResultExtensions
{
    public static IResult ToProblemDetails(this Result result)
    {
        if (result.IsSuccess)
        {
            throw new InvalidOperationException("Cannot convert a success result to problem details.");
        }

        return Results.Problem(
            statusCode: GetStatusCode(result.Error.Type),
            title: GetTitle(result.Error.Type),
            extensions: new Dictionary<string, object?>
            {
                { "errors", new[] { result.Error } }
            });
    }

    private static int GetStatusCode(ErrorType errorType) => errorType switch
    {
        ErrorType.Validation => StatusCodes.Status400BadRequest,
        ErrorType.NotFound => StatusCodes.Status404NotFound,
        ErrorType.Conflict => StatusCodes.Status409Conflict,
        ErrorType.Forbidden => StatusCodes.Status403Forbidden,
        _ => StatusCodes.Status500InternalServerError
    };

    private static string GetTitle(ErrorType errorType) => errorType switch
    {
        ErrorType.Validation => "Bad Request",
        ErrorType.NotFound => "Not Found",
        ErrorType.Conflict => "Conflict",
        ErrorType.Forbidden => "Forbidden",
        _ => "Server Error"
    };
}

This gives you consistent Problem Details responses across all endpoints.

Minimal APIs vs Controllers

How do the two approaches compare?

• Ceremony: Minimal APIs are just functions. Controllers need a class, a base type, and routing attributes.
• Performance: Minimal APIs are slightly faster because they skip parts of the MVC pipeline (model binding infrastructure, filters, view support).
• Testability: identical. In both cases you test the handler in the Application layer, not the HTTP adapter.
• Organization: extension methods or Carter modules for Minimal APIs; controller classes for MVC.
• OpenAPI: both work with the built-in OpenAPI document generation in .NET 9+. Minimal APIs describe metadata fluently (WithTags, Produces), controllers use attributes.
• Model binding: Minimal APIs bind from route, query, and body by convention with [AsParameters] for grouping. Controllers use [FromBody], [FromQuery], and friends.

In a Clean Architecture setup, both approaches are thin adapters. The real logic lives in the Application layer. The choice between Minimal APIs and controllers is mostly a style preference.

I prefer Minimal APIs for new projects because they're more concise and align well with the REPR pattern.

Takeaway

Minimal APIs and Clean Architecture complement each other. The API layer becomes a thin adapter: receive HTTP, create command/query, call handler, return HTTP response.

Organize endpoints by feature using extension methods or Carter modules. Use endpoint filters for cross-cutting concerns. Map results to Problem Details consistently.

Keep your endpoints thin, and let the Application layer do the real work.

Thanks for reading, and stay awesome!

Caching has a way of leaking everywhere, because it feels harmless at every individual call site. Clean Architecture gives you a precise answer for where it goes. The answer has two halves, and both matter.

The Split: Mechanism vs. Decision

Here is the principle that resolves every "where does this go" debate about caching:

• The mechanism is infrastructure. Redis clients, IMemoryCache, serialization, TTL bookkeeping, key formatting. All of it is a technical detail, replaceable without touching business behavior. It lives in the infrastructure layer.
• The decision is application-level. What is worth caching, how stale it may be, and when it must be invalidated are things only the use case knows. Product catalog: 5 minutes stale is fine. Account balance: absolutely not. That knowledge belongs to the application layer.

And one hard rule: the domain layer never knows caching exists. No entity, value object, or domain service should reference a cache, and no invariant may depend on cached state. Caching is a performance optimization, and the domain models business rules, not performance.

So the application layer expresses caching intent through an abstraction it owns, and infrastructure provides the implementation. The abstraction is small:

public interface ICacheService
{
    Task<T?> GetAsync<T>(string key, CancellationToken ct = default);

    Task SetAsync<T>(
        string key,
        T value,
        TimeSpan? expiration = null,
        CancellationToken ct = default);

    Task RemoveAsync(string key, CancellationToken ct = default);
}

The interface is defined in the application layer. Infrastructure implements it with Redis, HybridCache, or an in-memory store, and the dependency arrow points inward, exactly as the dependency rule requires.

With the split established, there are two clean places to apply it.

Approach 1: The Caching Decorator

The decorator pattern is the classic answer, and it is still the cleanest when you want caching to be invisible to consumers.

Say you have a repository interface in the application layer:

public interface IProductRepository
{
    Task<Product?> GetByIdAsync(Guid id, CancellationToken ct = default);

    Task UpdateAsync(Product product, CancellationToken ct = default);
}

The caching decorator wraps the real implementation:

public sealed class CachedProductRepository(
    IProductRepository inner,
    ICacheService cache) : IProductRepository
{
    private static readonly TimeSpan Expiration = TimeSpan.FromMinutes(5);

    public async Task<Product?> GetByIdAsync(Guid id, CancellationToken ct = default)
    {
        string key = $"products:{id}";

        Product? cached = await cache.GetAsync<Product>(key, ct);
        if (cached is not null)
        {
            return cached;
        }

        Product? product = await inner.GetByIdAsync(id, ct);

        if (product is not null)
        {
            await cache.SetAsync(key, product, Expiration, ct);
        }

        return product;
    }

    public async Task UpdateAsync(Product product, CancellationToken ct = default)
    {
        await inner.UpdateAsync(product, ct);

        await cache.RemoveAsync($"products:{product.Id}", ct);
    }
}

Notice UpdateAsync: the decorator is also the natural home for write-through invalidation, because it sees every mutation that goes through the interface.

Registration with Scrutor is one Decorate call:

builder.Services.AddScoped<IProductRepository, ProductRepository>();
builder.Services.Decorate<IProductRepository, CachedProductRepository>();

The strengths of this approach: use case handlers do not change at all, caching is centralized per aggregate, and removing it is a one-line rollback. The weakness: the TTL decision now lives in infrastructure, one step removed from the use cases that actually know the staleness requirements. For entity-by-id caching that is usually fine, because the policy is uniform.

One caveat: the decorator caches a domain entity, which costs nothing with an in-memory store but means serialization in a distributed cache. Encapsulated entities with private setters often do not round-trip through JSON without extra serializer configuration, so verify that before pointing this at Redis.

Approach 2: The Use Case Declares Its Caching

For query results (the read side of CQRS), I prefer the use case itself to declare its caching policy. The query says what it needs; a pipeline behavior does the work.

Define a marker interface in the application layer:

public interface ICachedQuery
{
    string CacheKey { get; }

    TimeSpan? Expiration { get; }
}

A query opts in by implementing it:

public sealed record GetProductCatalogQuery(int Page, int PageSize)
    : IRequest<ProductCatalogResponse>, ICachedQuery
{
    public string CacheKey => $"catalog:page-{Page}:size-{PageSize}";

    public TimeSpan? Expiration => TimeSpan.FromMinutes(5);
}

And a single pipeline behavior handles every cached query in the system:

public sealed class QueryCachingBehavior<TRequest, TResponse>(
    ICacheService cache,
    ILogger<QueryCachingBehavior<TRequest, TResponse>> logger)
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : ICachedQuery
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        TResponse? cached = await cache.GetAsync<TResponse>(request.CacheKey, ct);

        if (cached is not null)
        {
            logger.LogDebug("Cache hit: {CacheKey}", request.CacheKey);

            return cached;
        }

        TResponse response = await next();

        await cache.SetAsync(request.CacheKey, response, request.Expiration, ct);

        return response;
    }
}

Registered once:

builder.Services.AddMediatR(config =>
{
    config.RegisterServicesFromAssembly(typeof(ICachedQuery).Assembly);
    config.AddOpenBehavior(typeof(QueryCachingBehavior<,>));
});

This is my default for query caching, for one reason: the staleness contract sits on the query definition, right where the person changing the use case will see it. The decision is application-level, visibly, while the mechanism stays behind ICacheService in infrastructure. Exactly the split we wanted.

Invalidation Is Application Logic Too

The part most articles skip: who evicts?

Knowing that UpdateProductCommand invalidates products:{id} and every catalog:* page is pure use-case knowledge. So invalidation belongs in the application layer, and the cleanest trigger is the same event flow you already have.

If your aggregates raise domain events, a cache-eviction handler is a natural subscriber:

public sealed class ProductUpdatedCacheEvictionHandler(ICacheService cache)
    : INotificationHandler<ProductUpdatedDomainEvent>
{
    public async Task Handle(ProductUpdatedDomainEvent domainEvent, CancellationToken ct)
    {
        await cache.RemoveAsync($"products:{domainEvent.ProductId}", ct);
        await cache.RemoveByPrefixAsync("catalog:", ct);
    }
}

RemoveByPrefixAsync is an extra method you add to ICacheService for view-level eviction; the Redis implementation backs it with key scans or key tagging.

One handler owns the mapping from "product changed" to "these views are stale". When invalidation logic is scattered across command handlers, one forgotten eviction ships a stale-data bug; centralizing it per event keeps the mapping auditable. For the eviction techniques themselves (prefix removal, versioned keys, TTL fallbacks), see cache invalidation strategies.

Two guardrails to keep this honest:

• Always set a TTL, even with explicit invalidation. Expiration is your safety net when an eviction path is missed.
• On the query side, cache DTOs and read models, not entities. Responses and read models are stable, flat, and safe to serialize. Entity caching belongs in the repository decorator, centralized and paired with its invalidation, not scattered across handlers.

I cover this decision, including where caching fits among the other cross-cutting concerns, in Pragmatic Clean Architecture.

Choosing Between the Two

Practical guidance:

• Entity-by-id lookups behind a repository: decorator. Uniform policy, invisible to handlers, easy rollback.
• Query results and composed read models: pipeline behavior with ICachedQuery. Policy lives with the use case that owns the staleness requirement.
• Both in one codebase: completely fine, and common. They share the same ICacheService, so infrastructure stays singular.

Whichever you pick, run the flush test: if flushing the cache changes any business outcome (not latency, outcome), caching has leaked past infrastructure and needs to be pushed back out.

The Two-Part Answer

The mechanism (Redis, memory, serialization, TTLs) is infrastructure behind an application-owned ICacheService. The decision (what to cache, how stale, when to evict) is application knowledge, expressed either as a decorator policy per repository or as a declaration on the query itself.

The domain never finds out. And when someone asks "what happens if we flush Redis", the answer should be one sentence: everything gets slower for a minute, and nothing else changes.

Clean Architecture already has an answer for this, and it is simpler than people expect. A background job is just another entry point. It belongs in the same ring as your controllers, and it should be just as thin.

Jobs Are Entry Points, Not a New Layer

Think about what a controller does in Clean Architecture: it accepts input from the outside world (HTTP), translates it into a use case invocation, and returns the result. It contains no business rules.

A background job is the same thing with a different trigger. Instead of an HTTP request, the trigger is a schedule, a timer, or a queue message. Everything after the trigger should be identical: invoke a use case in the application layer.

That gives you the placement rule:

• The job class (the BackgroundService, the Quartz IJob, the Hangfire method) lives in infrastructure or presentation, wherever your other entry points live.
• The work itself is an application-layer use case: a command handler or an application service.
• The domain rules the work enforces stay in the domain layer.

The payoff is the same one controllers get. The use case is testable without any scheduler, reusable from other entry points (an admin endpoint can trigger the same cleanup), and wrapped by the same cross-cutting behaviors: validation, logging, transactions.

If the logic is in the job class, none of that is true. You cannot invoke it from anywhere else, and testing it means fighting the scheduling machinery, which is exactly the pain I described in testing background services.

The Mechanical Detail: Scoped Services in a Singleton

Before the examples, the one wiring detail that trips up everyone.

A BackgroundService is registered as a singleton and lives for the entire process. Your application services, your DbContext, and your MediatR handlers are scoped. Inject a scoped service into the singleton constructor and you get the infamous "Cannot consume scoped service from singleton" error, or worse, a single DbContext instance shared across the whole application lifetime.

The fix is always the same: inject IServiceScopeFactory and create a scope per execution. I covered the underlying rules in using scoped services from singletons, and you will see the pattern in both examples below.

Option 1: BackgroundService Triggering a Use Case

Start with the use case itself, in the application layer. It knows nothing about scheduling:

public sealed record ExpireStaleOrdersCommand : IRequest<int>;

public sealed class ExpireStaleOrdersCommandHandler(
    IOrderRepository orderRepository,
    IUnitOfWork unitOfWork,
    TimeProvider timeProvider)
    : IRequestHandler<ExpireStaleOrdersCommand, int>
{
    public async Task<int> Handle(
        ExpireStaleOrdersCommand command,
        CancellationToken ct)
    {
        DateTime cutoff = timeProvider.GetUtcNow().UtcDateTime.AddHours(-24);

        IReadOnlyList<Order> staleOrders =
            await orderRepository.GetPendingOlderThanAsync(cutoff, ct);

        foreach (Order order in staleOrders)
        {
            order.Expire();
        }

        await unitOfWork.SaveChangesAsync(ct);

        return staleOrders.Count;
    }
}

The Expire method is a domain behavior on the Order entity. The handler orchestrates; the entity enforces the rules.

Now the job, in infrastructure. It is a scheduling shell around the command:

public sealed class ExpireStaleOrdersJob(
    IServiceScopeFactory scopeFactory,
    ILogger<ExpireStaleOrdersJob> logger) : BackgroundService
{
    private static readonly TimeSpan Interval = TimeSpan.FromMinutes(15);

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(Interval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                using IServiceScope scope = scopeFactory.CreateScope();

                ISender sender = scope.ServiceProvider
                    .GetRequiredService<ISender>();

                int expired = await sender.Send(
                    new ExpireStaleOrdersCommand(), stoppingToken);

                logger.LogInformation("Expired {Count} stale orders", expired);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Order expiration run failed");
            }
        }
    }
}

Register it in Program.cs:

builder.Services.AddHostedService<ExpireStaleOrdersJob>();

Three details worth noticing:

• The scope is created per tick, so each run gets a fresh DbContext and properly scoped dependencies.
• The try/catch swallows failures per run instead of letting one exception kill the loop forever. An exception that escapes ExecuteAsync stops the job for good, and since .NET 6 the default BackgroundServiceExceptionBehavior takes the entire host down with it.
• Cancellation flows through, so shutdown is clean.

The shell never changes as business logic evolves. Every future change happens in the handler, where it is unit-testable.

Option 2: Quartz Job Triggering the Same Use Case

PeriodicTimer loops are fine for simple intervals. For cron schedules, persistence, and no-overlap guarantees, I reach for Quartz:

dotnet add package Quartz.Extensions.Hosting

The Quartz job is even thinner, because the Microsoft DI integration resolves every job from a fresh scope per execution:

[DisallowConcurrentExecution]
public sealed class ExpireStaleOrdersQuartzJob(ISender sender) : IJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        await sender.Send(
            new ExpireStaleOrdersCommand(),
            context.CancellationToken);
    }
}

And the wiring:

builder.Services.AddQuartz(options =>
{
    var jobKey = JobKey.Create(nameof(ExpireStaleOrdersQuartzJob));

    options.AddJob<ExpireStaleOrdersQuartzJob>(jobKey)
        .AddTrigger(trigger => trigger
            .ForJob(jobKey)
            .WithCronSchedule("0 0/15 * * * ?"));
});

builder.Services.AddQuartzHostedService(options =>
{
    options.WaitForJobsToComplete = true;
});

Because Quartz resolves the job from a scope, ISender injects directly. No IServiceScopeFactory ceremony. DisallowConcurrentExecution prevents overlapping runs when one execution outlasts its schedule, and in a clustered Quartz setup that guarantee holds across application instances, something the timer loop cannot offer.

The important part: the handler did not change. Swapping the scheduling technology (timer loop, Quartz, Hangfire, a queue consumer) touches only the outer shell. That is the dependency rule doing its job.

Where the Boundaries Earn Their Keep

This structure pays off in three specific ways.

Testing. The handler is a plain class with injected interfaces. Unit test it like any other use case, the way I showed in unit testing Clean Architecture use cases. Zero scheduler involvement, and TimeProvider makes the cutoff logic deterministic.

Reuse. A support engineer needs to force-run the cleanup? Add an admin endpoint that sends the same command. The job and the endpoint are two triggers for one use case.

Cross-cutting behaviors. If your pipeline has validation, logging, and transaction behaviors, jobs get them for free by going through ISender. Job-embedded logic bypasses all of it.

One boundary question comes up often: what about the outbox processor, the job that publishes pending integration events? That one is legitimately pure infrastructure. It moves messages, it invokes no business use case, so it can live entirely in the infrastructure layer without an application-layer command. The rule is not "every job sends a command"; it is "business logic never lives in the job". The outbox pattern processor has no business logic, so it is fine as-is.

I go deep on structuring entry points, use cases, and the dependency rule in Pragmatic Clean Architecture, including how jobs and messaging consumers fit the same shape.

Takeaway

Background jobs do not need a special place in Clean Architecture, because they are not special. They are entry points: a schedule instead of an HTTP request, a scoped execution instead of a request scope, and a use case invocation at the center either way.

Keep the job class thin enough that it never needs a test beyond "it sends the command". Create a scope per execution, catch per-run exceptions so the loop survives, and let Quartz handle cron and overlap when the schedule gets serious.

If your job class has business rules in it today, extract them into a command handler. The job will shrink to ten lines, and the logic will finally be testable.

The Question

Clean Architecture has strict rules about dependencies. So where do authentication and authorization fit?

• Authentication (who are you?) is an infrastructure concern
• Authorization (can you do this?) spans multiple layers

Let me show you how to implement both without violating layer boundaries.

Authentication: Infrastructure Layer

Authentication is how users prove their identity - JWT tokens, cookies, OAuth flows. This is entirely an Infrastructure layer concern.

Configure JWT authentication in the Presentation or Infrastructure layer:

// Infrastructure/Authentication/JwtConfiguration.cs
public static class JwtConfiguration
{
    public static IServiceCollection AddJwtAuthentication(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(options =>
            {
                options.TokenValidationParameters = new TokenValidationParameters
                {
                    ValidateIssuer = true,
                    ValidateAudience = true,
                    ValidateLifetime = true,
                    ValidateIssuerSigningKey = true,
                    ValidIssuer = configuration["Jwt:Issuer"],
                    ValidAudience = configuration["Jwt:Audience"],
                    IssuerSigningKey = new SymmetricSecurityKey(
                        Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]!))
                };
            });

        return services;
    }
}

The Application layer doesn't know how users are authenticated. It only knows who the current user is.

The Current User Abstraction

Define an interface in the Application layer:

// Application/Abstractions/ICurrentUserService.cs
public interface ICurrentUserService
{
    Guid UserId { get; }
    string Email { get; }
    IReadOnlyCollection<string> Roles { get; }
    IReadOnlyCollection<string> Permissions { get; }
    bool IsAuthenticated { get; }
}

Implement it in Infrastructure:

// Infrastructure/Authentication/CurrentUserService.cs
public class CurrentUserService : ICurrentUserService
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public CurrentUserService(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public Guid UserId => Guid.Parse(
        _httpContextAccessor.HttpContext?.User
            .FindFirstValue(ClaimTypes.NameIdentifier) ?? Guid.Empty.ToString());

    public string Email =>
        _httpContextAccessor.HttpContext?.User
            .FindFirstValue(ClaimTypes.Email) ?? string.Empty;

    public IReadOnlyCollection<string> Roles =>
        _httpContextAccessor.HttpContext?.User
            .FindAll(ClaimTypes.Role)
            .Select(c => c.Value)
            .ToList() ?? [];

    public IReadOnlyCollection<string> Permissions =>
        _httpContextAccessor.HttpContext?.User
            .FindAll("permission")
            .Select(c => c.Value)
            .ToList() ?? [];

    public bool IsAuthenticated =>
        _httpContextAccessor.HttpContext?.User.Identity?.IsAuthenticated ?? false;
}

Register it:

services.AddHttpContextAccessor();
services.AddScoped<ICurrentUserService, CurrentUserService>();

Now your handlers can access the current user without depending on ASP.NET Core:

public sealed class GetMyOrdersQueryHandler
    : IQueryHandler<GetMyOrdersQuery, List<OrderResponse>>
{
    private readonly ICurrentUserService _currentUser;
    private readonly IOrderRepository _orderRepository;

    public GetMyOrdersQueryHandler(
        ICurrentUserService currentUser,
        IOrderRepository orderRepository)
    {
        _currentUser = currentUser;
        _orderRepository = orderRepository;
    }

    public async Task<Result<List<OrderResponse>>> Handle(
        GetMyOrdersQuery query, CancellationToken ct)
    {
        var orders = await _orderRepository.GetByCustomerIdAsync(
            _currentUser.UserId, ct);

        return orders.Select(o => o.ToResponse()).ToList();
    }
}

I go deeper on this abstraction (and a few variations of it) in getting the current user in Clean Architecture.

One gotcha to watch for: if you populate roles or permissions from an external identity provider, the claims may not arrive under the claim types you expect. Claims transformation is the right place to normalize them before your CurrentUserService reads them.

Another JWT-specific gotcha: CurrentUserService reads ClaimTypes.NameIdentifier, which only exists because ASP.NET Core remaps the token's sub claim by default. If you disable that mapping with options.MapInboundClaims = false, read the sub claim directly instead. Otherwise UserId silently falls back to Guid.Empty.

Authorization: Application Layer

Authorization logic lives in the Application layer because it's a business rule: "Only managers can approve orders over $10,000."

Option 1: In the Handler

For simple authorization checks:

public sealed class ApproveOrderCommandHandler
    : ICommandHandler<ApproveOrderCommand>
{
    private readonly ICurrentUserService _currentUser;
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;

    public ApproveOrderCommandHandler(
        ICurrentUserService currentUser,
        IOrderRepository orderRepository,
        IUnitOfWork unitOfWork)
    {
        _currentUser = currentUser;
        _orderRepository = orderRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result> Handle(
        ApproveOrderCommand command, CancellationToken ct)
    {
        if (!_currentUser.Roles.Contains("Manager"))
        {
            return Result.Failure(AuthorizationErrors.InsufficientRole("Manager"));
        }

        var order = await _orderRepository.GetByIdAsync(command.OrderId, ct);

        if (order is null)
        {
            return Result.Failure(OrderErrors.NotFound(command.OrderId));
        }

        order.Approve(_currentUser.UserId);
        await _unitOfWork.SaveChangesAsync(ct);

        return Result.Success();
    }
}

Option 2: Authorization Pipeline Behavior

For declarative, reusable permission-based authorization, decorate the command with the required permission:

// Application/Authorization/AuthorizeAttribute.cs
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class AuthorizeAttribute : Attribute
{
    public string? Permission { get; set; }
    public string? Role { get; set; }
}

// Decorate the command
[Authorize(Permission = "orders:approve")]
public sealed record ApproveOrderCommand(Guid OrderId) : ICommand;

Then create a pipeline behavior that enforces it:

public class AuthorizationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ICurrentUserService _currentUser;

    public AuthorizationBehavior(ICurrentUserService currentUser)
    {
        _currentUser = currentUser;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        var authorizeAttributes = request
            .GetType()
            .GetCustomAttributes<AuthorizeAttribute>()
            .ToList();

        if (authorizeAttributes.Count == 0)
        {
            return await next();
        }

        foreach (var attribute in authorizeAttributes)
        {
            if (attribute.Permission is not null &&
                !_currentUser.Permissions.Contains(attribute.Permission))
            {
                throw new ForbiddenAccessException(attribute.Permission);
            }

            if (attribute.Role is not null &&
                !_currentUser.Roles.Contains(attribute.Role))
            {
                throw new ForbiddenAccessException(attribute.Role);
            }
        }

        return await next();
    }
}

The ForbiddenAccessException is a simple custom exception defined in the Application layer:

public sealed class ForbiddenAccessException : Exception
{
    public ForbiddenAccessException(string requirement)
        : base($"Access denied. Missing requirement: {requirement}")
    {
    }
}

Your global exception handler in the Presentation layer translates it to a 403 Forbidden response. If you prefer to avoid exceptions for flow control, you can constrain TResponse to your Result type and return a failure instead; the tradeoff is some reflection to construct Result<T> failures generically.

This approach separates what permissions are needed (attribute on the command) from how they're enforced (pipeline behavior).

Option 3: Resource-Based Authorization

When authorization depends on the resource itself:

public sealed class UpdateProjectCommandHandler
    : ICommandHandler<UpdateProjectCommand>
{
    private readonly ICurrentUserService _currentUser;
    private readonly IProjectRepository _projectRepository;
    private readonly IUnitOfWork _unitOfWork;

    public UpdateProjectCommandHandler(
        ICurrentUserService currentUser,
        IProjectRepository projectRepository,
        IUnitOfWork unitOfWork)
    {
        _currentUser = currentUser;
        _projectRepository = projectRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result> Handle(
        UpdateProjectCommand command, CancellationToken ct)
    {
        var project = await _projectRepository.GetByIdAsync(
            command.ProjectId, ct);

        if (project is null)
        {
            return Result.Failure(ProjectErrors.NotFound(command.ProjectId));
        }

        if (!project.IsOwner(_currentUser.UserId) &&
            !project.IsMember(_currentUser.UserId))
        {
            return Result.Failure(AuthorizationErrors.Forbidden());
        }

        project.Update(command.Name, command.Description);
        await _unitOfWork.SaveChangesAsync(ct);

        return Result.Success();
    }
}

The authorization rule (IsOwner or IsMember) is part of the domain model.

What About the [Authorize] Attribute?

You should still use ASP.NET Core's [Authorize] attribute (or RequireAuthorization() on Minimal API endpoints). Just be clear about its job.

Endpoint-level authorization is a coarse gate: is the caller authenticated, does the token carry the right scope? It protects the HTTP entry point, and only the HTTP entry point.

The permission checks in your Application layer are the real enforcement. They run no matter how the use case is invoked: HTTP endpoint, background job, message consumer, or a test. If your only authorization lives in controller attributes, every non-HTTP entry point bypasses it.

Use both, at different granularities:

• Presentation: [Authorize] for "must be authenticated" and scope checks
• Application: permission and role checks per use case
• Domain: ownership and membership rules on the aggregate

The Background Job Gotcha

Here's the failure mode that bites almost everyone eventually.

CurrentUserService reads from IHttpContextAccessor. In a background job or a message consumer, there is no HTTP context, so HttpContext is null and UserId silently becomes Guid.Empty. Your audit trail now says "nobody" approved the order.

Two ways to handle it:

1. Pass the user explicitly. When a use case is triggered from a message, include the acting user's ID in the message payload and flow it into the command. This is my default: it's explicit and survives serialization boundaries.
2. Swap the implementation. Register a different ICurrentUserService for worker processes (for example, one representing a system account). This works well for genuinely system-initiated operations like scheduled cleanups.

Whichever you pick, make IsAuthenticated meaningful in both contexts and fail loudly (not with Guid.Empty) when a use case requires a real user.

The Layer Boundaries

Here's the summary of where each concern lives:

• JWT validation, cookie handling: Infrastructure
• ICurrentUserService interface: Application
• CurrentUserService implementation: Infrastructure
• Permission checks: Application (pipeline behavior or handler)
• Resource-based ownership rules: Domain
• [Authorize] attribute and 401/403 responses: Presentation

Takeaway

Authentication is infrastructure. Authorization is a business rule.

1. Define ICurrentUserService in the Application layer
2. Implement it in Infrastructure using IHttpContextAccessor
3. Use pipeline behaviors for permission-based authorization
4. Put resource-based authorization in handlers or domain entities
5. Keep [Authorize] for coarse endpoint-level checks only
6. Never let your Application layer depend on ASP.NET Core directly

This keeps your business logic testable - mock ICurrentUserService in tests instead of wrestling with HTTP contexts.

Thanks for reading, and stay awesome!

What Is the Application Layer?

In Clean Architecture, the Application layer sits between the Domain layer (inner) and the Infrastructure layer (outer).

It has three main responsibilities:

1. Define use cases - each use case is a single application operation (place an order, cancel a subscription, get user details)
2. Orchestrate domain objects - it calls domain entities and services to execute business logic
3. Define abstractions - it declares interfaces that the Infrastructure layer implements (repositories, email services, payment gateways)

The Application layer knows about the Domain layer but knows nothing about databases, HTTP, or external services.

If the Domain layer answers "what are the business rules?", the Application layer answers "when do they run, and what happens around them?".

What Belongs in the Application Layer

Use cases (Command/Query handlers):

public class PlaceOrderCommandHandler : ICommandHandler<PlaceOrderCommand, Guid>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;

    public PlaceOrderCommandHandler(
        IOrderRepository orderRepository,
        IUnitOfWork unitOfWork)
    {
        _orderRepository = orderRepository;
        _unitOfWork = unitOfWork;
    }

    public async Task<Result<Guid>> Handle(
        PlaceOrderCommand command,
        CancellationToken cancellationToken)
    {
        var order = Order.Create(command.CustomerId, command.Items);

        _orderRepository.Add(order);

        await _unitOfWork.SaveChangesAsync(cancellationToken);

        return order.Id;
    }
}

DTOs and response models:

public sealed record OrderResponse(
    Guid Id,
    string CustomerName,
    decimal TotalAmount,
    string Status,
    DateTime CreatedAt);

Interface definitions (ports):

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
    void Add(Order order);
}

public interface IEmailService
{
    Task SendOrderConfirmationAsync(
        string recipientEmail,
        Guid orderId,
        CancellationToken cancellationToken = default);
}

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

Validators:

public class PlaceOrderCommandValidator : AbstractValidator<PlaceOrderCommand>
{
    public PlaceOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleFor(x => x.Items)
            .Must(items => items.All(i => i.Quantity > 0))
            .WithMessage("All items must have a positive quantity.");
    }
}

What Does NOT Belong

• Database access code - no DbContext, no SQL, no connection strings
• HTTP concerns - no controllers, no HttpContext, no request/response objects
• Framework dependencies - no EF Core, no MassTransit, no Serilog
• Third-party service implementations - only interfaces

The Application layer defines what the application does. Infrastructure defines how.

Keep Handlers Thin

The most common mistake I see in application layers is business logic leaking into handlers.

Here's what that looks like:

// Business logic in the handler - don't do this
public async Task<Result> Handle(CancelOrderCommand command, CancellationToken ct)
{
    var order = await _orderRepository.GetByIdAsync(command.OrderId, ct);

    if (order.Status == OrderStatus.Shipped ||
        order.Status == OrderStatus.Delivered)
    {
        return Result.Failure(OrderErrors.CannotCancel);
    }

    order.Status = OrderStatus.Cancelled;
    order.CancelledAt = DateTime.UtcNow;

    await _unitOfWork.SaveChangesAsync(ct);
    return Result.Success();
}

The rule "you can't cancel a shipped order" is a business rule. It belongs in the domain, where every other code path that cancels orders will also enforce it:

// Orchestration in the handler, rules in the domain
public async Task<Result> Handle(CancelOrderCommand command, CancellationToken ct)
{
    var order = await _orderRepository.GetByIdAsync(command.OrderId, ct);

    if (order is null)
    {
        return Result.Failure(OrderErrors.NotFound(command.OrderId));
    }

    var result = order.Cancel();

    if (result.IsFailure)
    {
        return result;
    }

    await _unitOfWork.SaveChangesAsync(ct);
    return Result.Success();
}

The handler loads the aggregate, calls one domain method, and saves. If your handlers read like a table of contents (load, act, save), you got it right. If they read like a business rules engine, your domain model is anemic.

Organizing Use Cases

I recommend organizing use cases by feature, not by type:

Application/
  Orders/
    PlaceOrder/
      PlaceOrderCommand.cs
      PlaceOrderCommandHandler.cs
      PlaceOrderCommandValidator.cs
    CancelOrder/
      CancelOrderCommand.cs
      CancelOrderCommandHandler.cs
    GetOrderById/
      GetOrderByIdQuery.cs
      GetOrderByIdQueryHandler.cs
      OrderResponse.cs
  Customers/
    RegisterCustomer/
      RegisterCustomerCommand.cs
      RegisterCustomerCommandHandler.cs

This follows the Screaming Architecture principle - the folder structure tells you what the application does, not what frameworks it uses.

I cover the alternatives (and when each one breaks down) in how to organize use cases in Clean Architecture, and there's a full worked example in building your first use case with Clean Architecture.

CQRS in the Application Layer

The CQRS pattern is a natural fit for the Application layer. Commands change state, queries return data.

Commands go through the full domain model:

// Command → Load aggregate → Execute domain logic → Save
var order = await _orderRepository.GetByIdAsync(command.OrderId, cancellationToken);
order.Cancel();
await _unitOfWork.SaveChangesAsync(cancellationToken);

Queries bypass the domain model entirely:

// Query → Project directly from database → Return DTO
return await _dbContext.Orders
    .Where(o => o.Id == query.OrderId)
    .Select(o => new OrderResponse(
        o.Id,
        o.Customer.Name,
        o.TotalAmount.Amount,
        o.Status.Name,
        o.CreatedAt))
    .FirstOrDefaultAsync(cancellationToken);

This separation lets you optimize reads independently from writes. Your write side uses the rich domain model; your read side projects directly into flat DTOs.

There's a pragmatic tension hiding in that query example: projecting "directly from the database" means the query handler needs some database access. You have three options, from purest to most pragmatic:

• A query-specific abstraction (e.g. IOrderReadService) implemented in Infrastructure. Purest, but you write an interface per query group.
• An IApplicationDbContext interface exposing DbSet<T> properties. Convenient, but it leaks EF Core types into the Application layer.
• Dapper with an IDbConnectionFactory. Fast and explicit SQL, at the cost of a second data access approach to maintain.

All three work in practice. For most teams, the IApplicationDbContext compromise is fine for queries, as long as commands still go through repositories and the domain model.

Where Do the Interfaces Live?

Teams argue about whether repository interfaces belong in the Domain layer or the Application layer. Both are defensible:

• Domain layer: the repository is conceptually part of the aggregate's contract ("an Order can be loaded and saved"). This is the classic DDD position.
• Application layer: the domain stays 100% persistence-free, and repositories are just another port the application needs, like IEmailService.

I lean toward the Application layer for everything except cases where a domain service genuinely needs the abstraction. What matters far more than the choice is consistency: pick one location and enforce it with architecture tests.

Cross-Cutting Concerns

The Application layer is the right place to define cross-cutting behaviors like validation, logging, and caching - typically implemented as decorators (here using Scrutor's Decorate) or pipeline behaviors:

// Each Decorate wraps the previous registration:
// Logging runs first, then Validation, then the handler
builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(ValidationCommandHandler<,>));
builder.Services.Decorate(typeof(ICommandHandler<,>), typeof(LoggingCommandHandler<,>));

This keeps your handlers focused on business logic while cross-cutting concerns are handled transparently. If you're using MediatR, pipeline behaviors give you the same result.

The Application Layer's Dependencies

The Application layer should only reference:

• The Domain layer (entities, value objects, domain events, domain services)
• Abstractions packages (FluentValidation contracts, MediatR contracts - but not their implementations)

It should NOT reference:

• Infrastructure packages (EF Core, Dapper, MassTransit)
• Presentation packages (ASP.NET Core)

You can enforce this with architecture tests:

[Fact]
public void Application_Should_Not_Reference_Infrastructure()
{
    var result = Types
        .InAssembly(typeof(PlaceOrderCommand).Assembly)
        .ShouldNot()
        .HaveDependencyOn("Infrastructure")
        .GetResult();

    result.IsSuccessful.Should().BeTrue();
}

Without a test like this, the boundary erodes one "temporary" using directive at a time.

Takeaway

The Application layer is where your system's use cases live. It:

• Defines use cases as commands and queries
• Orchestrates domain objects without knowing about infrastructure
• Declares interfaces that the outer layers implement
• Keeps business logic testable and framework-independent

Keep handlers thin, structure the layer by feature, use CQRS to separate reads from writes, and enforce the boundaries with architecture tests.

Thanks for reading, and stay awesome!

Almost no team has them enforced, which means they are not rules. They are wishes with a code-review lottery attached, and they lose that lottery on the busy weeks, which are the weeks that matter.

A fitness function is the fix, and it is less work than the rule was to agree on.

What a Fitness Function Actually Is

The term comes from evolutionary architecture: an automated check of a structural property of your system, run like any other test.

A unit test asserts behavior. Given this input, the method returns that output.

A fitness function asserts shape. Nothing in the application layer references the infrastructure layer. No two feature folders depend on each other in a loop. Only the persistence assembly knows that EF Core exists.

That distinction matters because shape is what erodes. Behavior breaks loudly and immediately. A single new using in the wrong file breaks nothing today, ships fine, and shows up two years later as the reason nobody can extract that module.

I have written before about enforcing architecture with tests, and the general case for shifting that feedback left holds regardless of tool. This article is about the heavier of the two .NET libraries, ArchUnitNET, a port of Java's ArchUnit, and what it can express that lighter tools cannot.

Setting It Up

Two packages: the core library and the adapter for your test framework.

dotnet add package TngTech.ArchUnitNET
dotnet add package TngTech.ArchUnitNET.xUnitV3

Loading the architecture is the expensive step, because ArchUnitNET parses the IL of every assembly you hand it. Do it once for the whole test run:

using ArchUnitNET.Domain;
using ArchUnitNET.Loader;

public static class ArchitectureFixture
{
    // Loaded once, shared by every rule. Parsing the assemblies is the slow part;
    // evaluating a rule against an already-built Architecture is in-memory work.
    public static readonly Architecture Architecture = new ArchLoader()
        .LoadAssemblies(
            typeof(Shop.Domain.AssemblyReference).Assembly,
            typeof(Shop.Application.AssemblyReference).Assembly,
            typeof(Shop.Infrastructure.AssemblyReference).Assembly,
            typeof(Shop.Api.AssemblyReference).Assembly)
        .Build();
}

The AssemblyReference marker is just an empty public class in each project's root, so the test project can name an assembly without hardcoding its string name.

Now the first rule:

using ArchUnitNET.Fluent;
using ArchUnitNET.xUnitV3;
using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class LayeringTests
{
    [Fact]
    public void Application_Should_Not_Depend_On_Infrastructure()
    {
        IArchRule rule = Types()
            .That().ResideInNamespace("Shop.Application", useRegularExpressions: false)
            .Should().NotDependOnAny(
                Types().That().ResideInNamespace("Shop.Infrastructure", useRegularExpressions: false));

        rule.Check(ArchitectureFixture.Architecture);
    }
}

Check comes from the test-framework adapter package. It throws when the rule fails, and the message names every offending type and the dependency that violated the rule, which is the entire reason to use a library instead of reflection by hand.

The Rules Worth Writing First

Four shapes cover most of what teams actually argue about in reviews.

Dependency direction. The rule above, once per boundary you care about. In Clean Architecture that is domain depending on nothing, application depending on domain only. In a modular monolith it is one rule per module pair, allowing the contracts namespace and forbidding everything else.

Library containment. Keep infrastructure concerns from leaking inward:

IArchRule domainIsPersistenceIgnorant = Types()
    .That().ResideInNamespace("Shop.Domain", useRegularExpressions: false)
    .Should().NotDependOnAny(
        Types().That().ResideInNamespace("Microsoft.EntityFrameworkCore", useRegularExpressions: false));

This one earns its keep faster than the layering rules, because an EF Core attribute on a domain entity looks harmless in a diff.

Conventions. The things you keep retyping in review comments:

IArchRule handlerConventions = Classes()
    .That().ImplementInterface("IRequestHandler")
    .Should().BeSealed()
    .AndShould().HaveNameEndingWith("Handler");

Cycle freedom. Covered next, because it is the one you should not try to write yourself.

I listed my own starting set in 5 architecture tests every .NET project should have.

Cycle Freedom Is the Rule You Cannot Hand-Roll

ArchUnitNET can slice a codebase by a namespace pattern and assert that the slices form no dependency cycles:

using static ArchUnitNET.Fluent.Slices.SliceRuleDefinition;

IArchRule noSliceCycles = Slices()
    .Matching("Shop.Features.(*)")
    .Should().BeFreeOfCycles();

Matching captures one slice per distinct value of (*), so Shop.Features.Orders, Shop.Features.Billing, and Shop.Features.Shipping each become a node, and the rule fails if the dependency graph between them contains a loop.

This is the rot that turns a vertical slice architecture into mud, and it is close to invisible in review. Orders reaches into Billing for a tax calculation. Months later Billing reaches into Orders for a customer lookup. Neither pull request looked wrong on its own, and now the two features cannot be understood, tested, or extracted separately.

Detecting that means building a dependency graph and running cycle detection over it. You can write that, but it is a genuine algorithm with genuine edge cases, and it is the main reason I reach for ArchUnitNET over lighter alternatives like NetArchTest, which has no equivalent.

When You Need the Verdict, Not the Exception

Check is right inside a test: it throws, the runner prints the message, done.

When the result feeds something other than a test runner (a report, a dashboard, a per-rule verdict on a build page), evaluate the rule and read the results yourself:

foreach (EvaluationResult result in noSliceCycles.Evaluate(ArchitectureFixture.Architecture))
{
    if (!result.Passed)
    {
        Console.WriteLine(result.Description); // names the object and why it failed
    }
}

Each EvaluationResult carries Passed, a Description, and the object that was evaluated, so you can group violations by rule, count them over time, or render them next to the code that caused them.

Three Ways a Fitness Function Lies to You

All three produce a green build for a codebase that is violating the rule. They are worth knowing before you start trusting the suite.

An empty rule set always passes. Classes().That().ImplementInterface("IRequestHandler") matching zero types means "every one of the zero handlers is sealed", which is true. Rename the interface, and the convention rule goes green forever without a single handler being checked. Guard the rules that matter:

[Fact]
public void Handler_Convention_Rule_Has_Something_To_Check()
{
    IEnumerable<Class> handlers = Classes()
        .That().ImplementInterface("IRequestHandler")
        .GetObjects(ArchitectureFixture.Architecture);

    Assert.NotEmpty(handlers);
}

Namespace strings do not get refactored. Rename Shop.Persistence to Shop.Infrastructure.Persistence and every rule written against the old string silently matches nothing. Prefer assembly-based selection where you can, and when you do use namespaces, keep them in one const per layer so a rename is one edit instead of a search.

A rule can encode an accident. Write the rules by reading the current code and you will faithfully enshrine whatever shortcut is in there today. Write them from the decision you actually made, watch them fail, then fix the code or consciously change the decision. A fitness function that has never failed has never told you anything.

Running Them in CI

They are ordinary tests, so there is nothing special to wire up:

- name: Architecture tests
  run: dotnet test --filter "FullyQualifiedName~ArchitectureTests"

No database, no HTTP, no containers. The whole suite is one assembly parse plus in-memory graph work, so it belongs in the fast job that runs on every pull request, next to your unit tests.

The change this makes to a team is smaller than it sounds and matters more than it sounds: an architecture violation stops being a review comment somebody has to write, notice, and win an argument about, and becomes a red build with the offending type name in it.

When Rules Outgrow Code

Rules in code are the right default. They live next to the tests, they refactor with the solution, and the full fluent vocabulary is available.

There is a point where that breaks down: when the same handful of rule shapes repeat across many targets, when people who do not build the solution need to author rules, or when the rules are content rather than configuration. Then it is worth declaring rules as data and mapping them onto the fluent API:

[
  { "id": "notifier-abstraction", "kind": "interface-must-exist",
    "interface": "INotifier" },
  { "id": "service-not-concrete", "kind": "type-must-not-reference",
    "type": "OrderService", "target": "SmtpNotifier" },
  { "id": "app-not-infra", "kind": "layer-must-not-depend-on",
    "from": "Shop.Application", "to": "Shop.Infrastructure" }
]

public static ArchitectureRule Create(RuleDefinition definition) => definition.Kind switch
{
    "interface-must-exist"     => ArchRules.InterfaceMustExist(definition.Id, definition.Interface!),
    "type-must-not-reference"  => ArchRules.TypeMustNotReference(definition.Id, definition.Type!, definition.Target!),
    "layer-must-not-depend-on" => ArchRules.LayerMustNotDependOn(definition.Id, definition.From!, definition.To!),
    _ => throw new InvalidOperationException($"Unknown rule kind '{definition.Kind}'.")
};

Because an ArchitectureRule is ultimately just an id, a description, and an IArchRule, anything the data format cannot express drops down to a raw fluent rule in code, like the slice-cycle check above. Data for the common shapes, the full vocabulary for the exotic ones.

That is not a trade most teams need to make. Do not build it until the rules have actually multiplied.

The Property That Makes This Safe

One implementation detail is worth knowing because it changes what you can point ArchUnitNET at: it never executes the assembly.

ArchLoader reads assemblies with Mono.Cecil, a static IL and metadata parser. The assembly is never Assembly.Loaded into the runtime, so no module initializer runs, no static constructor fires, and nothing the code wants to do at load time happens.

For most teams that is a pleasant footnote: your fitness functions cannot be slowed down or broken by application startup code.

It stops being a footnote when the code is not yours. Katabench, my coding platform, has an architecture track where you refactor a small codebase (extract an abstraction, invert a dependency, break a cycle) and the platform grades the result. Grading a refactoring means answering "is the structure right now?" mechanically, for code a stranger uploaded a second ago. The submission is compiled with Roslyn, handed to Cecil, and evaluated as a set of fitness functions, all without a single line of it running. Behavior gets judged separately, inside a sandbox, and both gates have to pass.

Static structure checking and behavioral testing being genuinely independent is not a grading trick. It is why the shape check costs milliseconds and can run on every save while the slow gate runs later.

Start With Three

You do not need a rule catalog to get value out of this.

1. Add one test project and load the architecture once in a static field.
2. Write the three rules you already state in onboarding: your most important dependency direction, the naming convention you keep repeating in reviews, and a slice-cycle rule over your feature namespaces.
3. Run them in the fast CI job.

Then let them fail. The first failure is the useful one, because it tells you the gap between the architecture you describe and the one you have.

Architecture that is not executable erodes at exactly the speed your team ships. If you want to see rules graded against a codebase in real time, the architecture track on Katabench does it every time you hit Run.

invoice:1187:pdf points at a slot. The slot keeps its name when the thing it describes changes, so correctness depends on someone remembering to evict, at every site that writes, forever. Miss one and the cache serves a wrong answer with complete confidence.

There is another way to name things, and it makes that entire class of bug impossible: name the entry after a hash of its inputs.

You depend on this several times a day already. Git addresses every blob, tree, and commit by a hash of its content. Docker rebuilds a layer only when the instruction or the files it copies change. NuGet, npm, and Cargo pin packages by content hash. None of those systems has invalidation logic, because none of them needs any.

The same trick works inside an ASP.NET Core application, and it is underused there.

Location Keys and Content Keys

Say you render invoice PDFs from a template plus some data. The obvious key names the thing:

string key = $"invoice-pdf:{invoiceId}";

Now list everything that can change the bytes this key points at:

• the invoice data (line items, totals, the customer address)
• the template body, which the design team edits
• the culture used to format currency and dates
• the renderer itself, the day you upgrade it or fix a layout bug

Four inputs, and the key mentions one of them. The other three are handled by hope, or by eviction code written at each of the places that can change them. The template edit is the one that bites: nothing in the invoice changed, so nothing in the invoice's write path fires, and every cached PDF keeps rendering with last quarter's letterhead.

The content-addressed key names the inputs instead:

string key = ContentKey.From(templateId, templateSource, dataJson, culture, RendererVersion);

Edit the template and templateSource changes, so the key changes, so the lookup misses, so the PDF is rendered again and stored under the new key. The old entry is not stale. It is unreachable, because nothing computes its key anymore.

There is no invalidation code in this design. There is nothing to forget.

Building a Key You Can Trust

The key builder is small, and two details in it are load-bearing:

using System.Security.Cryptography;
using System.Text;

public static class ContentKey
{
    public static string From(params string?[] parts)
    {
        using IncrementalHash hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);

        foreach (string? part in parts)
        {
            byte[] bytes = Encoding.UTF8.GetBytes(part ?? string.Empty);

            // Length-prefix every part so the boundary between parts is unambiguous.
            hash.AppendData(BitConverter.GetBytes(bytes.Length));
            hash.AppendData(bytes);
        }

        return Convert.ToHexStringLower(hash.GetHashAndReset());
    }
}

The length prefix is the detail people skip. Concatenate the parts with a separator instead, and ("a b", "c") and ("a", "b c") produce the same bytes, so two different inputs collide onto one entry. That is the exact failure this pattern exists to prevent, reintroduced in the first four lines.

The second detail is what you pass in. Build the key next to the thing that defines the computation, and make the list exhaustive:

public sealed record InvoiceRenderRequest(
    string TemplateId,
    string TemplateSource,
    string DataJson,
    string Culture);

public static class ContentKeys
{
    // Bump on any change to how the renderer turns inputs into bytes.
    private const string RendererVersion = "pdf-v3";

    public static string ForInvoice(InvoiceRenderRequest request) => ContentKey.From(
        request.TemplateId,
        request.TemplateSource,   // the template body, not just its name
        request.DataJson,
        request.Culture,
        RendererVersion);
}

RendererVersion is the part that feels wrong and is not. The code is an input. Ship a renderer that fixes a rounding bug, leave the version alone, and every existing entry keeps serving output produced by the bug you just fixed. Docker does the same thing when it puts the instruction text into the layer's cache key, not only the files the instruction copies.

Note also that TemplateSource is the template's content, not its ID. A key that references an input by name inherits exactly the staleness problem you are trying to leave behind.

Reading and Writing

Everything above is about the key. The store can be whatever you already use. With HybridCache it is one call:

public sealed class InvoiceRenderer(HybridCache cache, IPdfEngine engine)
{
    public async Task<byte[]> RenderAsync(
        InvoiceRenderRequest request,
        CancellationToken cancellationToken = default)
    {
        string key = ContentKeys.ForInvoice(request);

        return await cache.GetOrCreateAsync(
            key,
            (engine, request),
            static (state, token) => state.engine.RenderAsync(state.request, token),
            new HybridCacheEntryOptions
            {
                // The value can never be wrong, so expiration is a storage decision,
                // not a correctness one. Pick it from your memory and Redis budget.
                Expiration = TimeSpan.FromDays(30),
                LocalCacheExpiration = TimeSpan.FromMinutes(10)
            },
            cancellationToken: cancellationToken);
    }
}

The comment on Expiration is the whole payoff. In a location-keyed cache, TTL is a correctness knob: it bounds how long you serve wrong data, so it fights your hit rate directly. Here it bounds nothing but storage, so you set it from what you can afford to keep, and a longer TTL is strictly better.

Concurrency Stops Being a Correctness Problem

Two requests arrive for the same cold key at the same time. Both miss, both render, both store.

In a location-keyed cache this is a cache stampede, and the standard answer is to coalesce the concurrent factory calls so only one runs. HybridCache does that for you, and so does FusionCache.

With a content key, the coalescing is a performance feature and nothing more. Both callers derived the key from the same inputs, and the computation is deterministic, so whatever the loser of the write race stored is the same value the winner stored. The cost of losing the race is one duplicated computation. The correctness of the entry is never in question.

That difference shows up when you write the store yourself:

public void Store(string key, byte[] value)
{
    string path = Path.Combine(_directory, key);
    string tmp = $"{path}.{Guid.NewGuid():N}.tmp";

    // Write to a unique temp file first, then move it into place, so a crash
    // mid-write can never leave a truncated entry behind.
    File.WriteAllBytes(tmp, value);

    try
    {
        File.Move(tmp, path, overwrite: true);
    }
    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
    {
        // A concurrent writer got there first. It wrote the same value we did,
        // so there is nothing to reconcile and nothing to retry.
        try { File.Delete(tmp); } catch { /* best effort */ }
    }
}

A directory of files named by key is a perfectly good cache when the values are megabytes rather than kilobytes, and it survives restarts and redeploys for free. Put a ConcurrentDictionary in front of it and a hot entry costs a dictionary lookup instead of a disk read.

One honest caveat on determinism. Many renderers embed a creation timestamp, so two runs produce different bytes from the same inputs. That is fine here, because both outputs are equally valid answers. What is not fine is a computation that can produce a wrong answer for the same inputs, and that is the line where this pattern stops applying.

You Traded Invalidation for Garbage Collection

Content addressing never deletes anything, so every edit strands the previous entry. That is the cost, and it is real: the template team edits a header twenty times in an afternoon and you now hold twenty invoice renderings nobody will ever ask for again.

You have two ways to bound it, and they are not equivalent.

Expiry or size caps. A TTL, SizeLimit on IMemoryCache, or maxmemory with an LRU policy on Redis. Imprecise but free, and correct by construction, because evicting a live entry only costs a recompute.

A sweep, when you can enumerate the keys the current inputs can produce:

/// <summary>Deletes entries whose key no live input can produce.</summary>
public int Prune(IReadOnlySet<string> liveKeys)
{
    int removed = 0;

    foreach (string file in Directory.EnumerateFiles(_directory)
                 .Where(f => !liveKeys.Contains(Path.GetFileName(f))))
    {
        try
        {
            File.Delete(file);
            removed++;
        }
        catch (IOException)
        {
            // Another instance is sweeping too. It is idempotent; let it win.
        }
    }

    return removed;
}

Recompute the key for every live template and configuration at startup, hand the set to Prune, and the cache is bounded to exactly what the current content can produce. That keeps the spirit of the rest of the pattern: what is valid is derived from the live inputs, never tracked in a separate ledger that can drift.

The One Failure Mode

Everything good about this pattern comes from one assumption, and there is exactly one way to break it: leave an input out of the key.

Do that and the key stops changing when the value should. The cache serves the old answer indefinitely, and unlike a location-keyed cache, there is no eviction path anywhere to save you. It is a quiet bug, and the usual shape is an input that did not look like one: an environment variable, a feature flag, a config file the renderer reads on its own, the machine's default culture.

Three habits keep it closed:

• Over-include. A key that is too sensitive costs an unnecessary recompute. A key that is too coarse costs a wrong answer. That trade is not close.
• Make the input list one line of code. If the key is assembled in three places, one of them will fall behind. A single ContentKeys.ForX method is the thing you review when the computation changes.
• Treat implicit inputs as explicit. Anything the computation reads that is not a parameter (config, flags, ambient culture) either goes into the key or gets passed in as a parameter so it does.

Where This Fits, and Where It Does Not

Reach for a content key when all three hold:

• The computation is deterministic, in the sense that any output it produces for a given set of inputs is equally valid.
• You can enumerate the inputs, all of them.
• Deriving the value is expensive relative to hashing it. Hashing a few KB is microseconds. Rendering a document, resizing an image, running a model, compiling something: easy call.

That covers more than it sounds like: report and document rendering, image transforms, code generation, compiled query plans, expensive pure aggregations over immutable data, and LLM calls at temperature zero.

It does not cover data with genuine freshness semantics. A stock price, an inventory count, a user's notification badge: those change because the world changed, not because an input to a derivation changed. Those still want a TTL and a deliberate caching strategy, and no amount of hashing helps.

One From Production

Katabench, my coding platform, runs on this for a value that has no hand-written answer at all.

Many katas do not ship an expected output. Instead the platform derives one: it runs the kata's reference solution against the test's input inside a sandbox and keeps whatever comes back. A full sandboxed execution per test is far too slow to repeat on every submission, so it has to be cached.

The location-keyed version of that cache would be {puzzleId}:{testName}, and it would need an eviction hook on every edit to a reference solution, a test input, or a seed script. The content-keyed version puts the reference solution's source code and the test's full input into the key. Editing either one produces a different key, a miss, and a fresh derivation, with no eviction code anywhere in the system.

The kind of bug that would keep me up otherwise (grading somebody's submission against an expected answer derived from a reference solution I edited last week) cannot happen, because there is no code path that produces it.

The Takeaway

Cache invalidation is hard when the key is a location. It disappears when the key is a hash of everything the value depends on, because "the inputs changed" and "the key changed" become the same event.

The move worth making is smaller than adopting a pattern. Next time you cache an expensive derived value, write down every input it actually depends on, including the code that produces it. If that list is finite and you can hash it, you can have a cache that is never wrong, and the only thing left to manage is disk.

If you want to see the idea running under real load, the sandboxed grading on Katabench is built on it, and I am always happy to hear what breaks.

What is Vertical Slice Architecture?

Vertical Slice Architecture organizes code by feature instead of by layer. Each feature (or "slice") contains everything it needs - the request, the handler, the validation, and the data access - in one place.

Instead of scattering a single feature across Controllers, Services, and Repositories, you keep it together. This makes each slice self-contained, easier to understand, and simpler to change without affecting unrelated features.

The result is a codebase where adding a new feature means adding a new slice, not modifying five different layers.

Getting Started

These articles introduce the core ideas behind Vertical Slice Architecture, explain when it makes sense, and show you how to get started.

• Vertical Slice Architecture
• Vertical Slice Architecture Is Easier Than You Think
• Screaming Architecture
• Vertical Slice Architecture vs Clean Architecture
• When to Choose Vertical Slice Architecture

Structuring Your Slices

Once you understand the basics, you'll need patterns for organizing slices as your project grows. These articles cover structure, shared logic, and CQRS integration.

• Vertical Slice Architecture: Structuring Vertical Slices
• Vertical Slice Architecture: Where Does the Shared Logic Live?
• CQRS Pattern: The Way It Should Have Been From the Start
• The REPR Pattern in ASP.NET Core
• Vertical Slice Architecture Project Structure
• Feature Folders in .NET
• Combining Vertical Slices with CQRS
• Vertical Slice Architecture with Carter in .NET

Cross-Cutting Concerns and Validation

Even self-contained slices share some concerns. These articles cover how to handle validation and cross-cutting logic without breaking slice isolation.

• Validation in Vertical Slice Architecture
• Cross-Cutting Concerns in Vertical Slice Architecture

Combining with Other Architectures

Vertical slices don't exist in isolation. They work well inside Modular Monoliths and alongside Clean Architecture. These articles explore the combinations.

• Where Vertical Slices Fit Inside the Modular Monolith Architecture
• What Is a Modular Monolith?
• Clean Architecture: The Missing Chapter

Testing and Quality

Vertical slices are inherently testable - each slice is a focused unit with clear inputs and outputs.

• Enforcing Software Architecture with Architecture Tests
• Shift Left with Architecture Testing in .NET
• 5 Architecture Tests You Should Add to Your .NET Projects
• Testing Vertical Slices in .NET

The design gets interesting when the system grows past one machine. Katabench runs its API and its grading workers on separate boxes, with the monitoring stack on a third, and that split forces the question the tutorials skip: who sends telemetry where?

The answer that works is a two-tier collector deployment: an agent on every box, one gateway in front of the storage.

The Topology

Each application box runs a small collector next to the app. The app exports OTLP to http://otel-collector:4317, a name that resolves inside the box's own compose network, and knows nothing else.

The agents forward to the gateway on the monitoring box over a private Tailscale network. The gateway is the only component that knows the backends exist: traces go to Tempo, logs to Loki over its native OTLP ingest, and metrics are exposed on a scrape endpoint for Prometheus.

Adding a box to the system costs zero monitoring configuration. Telemetry is push-based, service.instance.id distinguishes instances, and the new box's agent just needs the one gateway address.

The Agent: A Local Hop That Earns Its Keep

The agent config is short enough to show almost in full:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  # Hard ceiling on the collector's own memory. Spikes are dropped, not queued.
  memory_limiter:
    check_interval: 1s
    limit_mib: 96
    spike_limit_mib: 32
  batch:

exporters:
  otlp/gateway:
    endpoint: ${env:OTEL_ENDPOINT}   # no default: missing value fails at boot
    tls:
      insecure: true                 # the link is WireGuard-encrypted already
    retry_on_failure:
      enabled: true
    sending_queue:
      enabled: true
      queue_size: 5000

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp/gateway]
    # metrics and logs: same shape

Four deliberate decisions live in those thirty lines:

• The app only knows a local address. No cross-box IP is baked into app config. When the monitoring stack moves, app deployments don't change.
• A sending queue plus retry rides out a gateway or network blip instead of dropping spans. Direct app-to-backend export has no such buffer.
• memory_limiter runs first in every pipeline, and the numbers matter on shared boxes. My worker box's RAM is budgeted for sandbox runs, so the agent gets a hard 96 MB ceiling and sheds load rather than competing with the actual workload for memory. An observability sidecar that can trigger the OOM killer is a self-own.
• ${env:OTEL_ENDPOINT} has no default. A missing value crashes the collector at boot. The alternative is a collector that starts fine and silently swallows telemetry, which you discover three weeks later, mid-incident.

One more property worth copying: the agent publishes no host ports. It is reachable only by the app container on the same compose network, so no box exposes an OTLP ingest surface, not even on the private network.

The Gateway: One Ingest Point, Per-Signal Fan-Out

The gateway is where the per-signal routing happens:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889        # scrape surface for Prometheus
  otlphttp/loki:
    endpoint: http://loki:3100/otlp # Loki ingests OTLP natively since 3.0
  otlp/tempo:
    endpoint: tempo:4317

service:
  pipelines:
    traces:
      receivers: [otlp, faro]
      processors: [batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp, faro]
      processors: [batch]
      exporters: [otlphttp/loki]

That faro receiver is the bonus a central gateway buys you. The browser SPA reports real-user monitoring (JS errors, Web Vitals, fetch spans) through Grafana Faro into the same collector, sharing the traces and logs pipelines. A browser fetch and the API span it triggered land in one Tempo trace, stitched by the propagated traceparent. It is the single observability endpoint that must be public, because it is called from users' browsers; everything else stays private.

When Do You Actually Need This?

Rules of thumb, from running it:

• One box, one app: a single collector is fine. Don't build the two-tier setup for a monolith on one VPS.
• Two or more boxes, or any box whose RAM you care about: add agents. The local buffering alone pays for the extra container the first time your monitoring box restarts during a deploy and no telemetry is lost.
• Browser RUM, or multiple teams sending telemetry: you want the gateway as the single, controlled ingest point regardless of box count.

The nice thing about the pattern is that migrating to it is invisible to your applications. The .NET side of the wiring never changes: the OTLP exporter still points at whatever OTEL_EXPORTER_OTLP_ENDPOINT says, which is exactly how it worked back when the whole stack was one docker-compose file (the setup from introduction to distributed tracing with OpenTelemetry in .NET). Only the address changed.

What is a Modular Monolith?

A Modular Monolith is a software architecture style where a single deployable unit is organized into well-defined, loosely coupled modules. Each module encapsulates a specific business capability with its own data, logic, and API surface.

Unlike a traditional monolith, the boundaries between modules are explicit and enforced. Unlike microservices, you get the simplicity of a single deployment, a single database connection, and no distributed system complexity.

The Modular Monolith gives you the best of both worlds - strong modularity with operational simplicity.

Want to master this architecture? My Modular Monolith Architecture course covers the complete approach I use for building production systems.

Getting Started

These articles introduce the core concepts and help you understand when a Modular Monolith is the right choice for your project.

• What Is a Modular Monolith?
• Monolith to Microservices: How a Modular Monolith Helps
• Scaling Monoliths: A Practical Guide for Growing Systems
• Modular Monolith vs Microservices: How to Choose
• How to Build a Modular Monolith in .NET Step by Step

Module Boundaries and Data Isolation

Getting module boundaries right is the most important design decision. These articles cover how to define boundaries, isolate data, and enforce separation.

• Modular Monolith Data Isolation
• How to Keep Your Data Boundaries Intact in a Modular Monolith
• Internal vs Public APIs in Modular Monoliths
• Refactoring Overgrown Bounded Contexts in Modular Monoliths
• Defining Module Boundaries with Bounded Contexts
• Schema-per-Module vs Database-per-Module
• The Shared Kernel Pattern in a Modular Monolith

Communication Patterns

Modules need to communicate without creating tight coupling. These articles cover synchronous and asynchronous patterns for inter-module communication.

• Modular Monolith Communication Patterns
• Orchestration vs Choreography
• How to Use Domain Events to Build Loosely Coupled Systems
• Building a Custom Domain Events Dispatcher in .NET
• Event-Driven Communication Between Modules
• Why the Outbox Pattern Solves the Dual-Write Problem
• The Saga Pattern in a Modular Monolith

Testing

Testing a Modular Monolith requires strategies that validate both individual modules and cross-module interactions.

• Testing Modular Monoliths: System Integration Testing
• Enforcing Software Architecture with Architecture Tests
• 5 Architecture Tests You Should Add to Your .NET Projects

Migrating to Microservices

A Modular Monolith is often the best starting point before moving to microservices. These articles cover when and how to make that transition.

• Breaking It Down: How to Migrate Your Modular Monolith to Microservices
• Understanding Microservices: Core Concepts and Benefits
• Getting Started with Microservices in .NET
• When to Extract a Module into a Microservice
• The Strangler Fig Pattern for Modular Monolith Migration

Vertical Slices in a Modular Monolith

Vertical Slice Architecture is a natural fit inside individual modules. These articles explore how the two approaches complement each other.

• Where Vertical Slices Fit Inside the Modular Monolith Architecture
• Vertical Slice Architecture

My first transport failed that constraint twice, and the fix is a nice case study in what a real job queue gives you. The whole design fits in one article.

Where the Redis List Design Loses Jobs

Version one was the classic minimal queue: a Redis list. The API does RPUSH, workers poll with LPOP, results go into a per-job key with a TTL.

It has two silent loss modes, and both are structural:

• LPOP removes the job with no acknowledgment. A worker that crashes mid-job (and mine run untrusted code, so crashing is normal operation) takes the job with it. Nothing redelivers it.
• No persistence. An in-memory Redis restart or redeploy wipes the queue and every in-flight result.

You can patch around both (use LMOVE to a processing list, add AOF persistence, build a sweeper for stuck jobs), but at that point you are hand-building acknowledgments and durability. That is exactly the feature set of a real message broker.

I picked NATS JetStream over RabbitMQ for one operational reason: it is a single lightweight binary that is trivial to run on a VPS, and it plugs straight into the Prometheus and Grafana stack I already had. I covered the fundamentals in getting started with NATS JetStream in .NET; this is what the production shape looks like.

The Shape: Two Streams

Everything is built on two file-backed streams:

var js = new NatsJSContext(connection);

// The job queue: a message is removed once a worker acks it.
await js.CreateStreamAsync(new StreamConfig("GRADING_JOBS", ["grading.jobs"])
{
    Retention = StreamConfigRetention.Workqueue,
    Storage = StreamConfigStorage.File
});

// Results: short retention, one subject per job id.
await js.CreateStreamAsync(new StreamConfig("GRADING_RESULTS", ["grading.results.>"])
{
    Retention = StreamConfigRetention.Limits,
    MaxAge = TimeSpan.FromMinutes(5),
    Storage = StreamConfigStorage.File
});

The jobs stream uses work-queue retention: acking a job deletes it, so the stream behaves like a queue instead of a log. All workers compete on one shared durable pull consumer, which is how you get the competing-consumers pattern; adding a worker is just starting another process, with zero configuration.

The results stream is the part most people skip. The worker publishes each outcome to grading.results.<jobId>, and the API awaits it with an ephemeral ordered consumer filtered to that one subject. Because the stream retains messages for a few minutes, a result that was published before the API started waiting is still delivered. That closes an entire class of races that a fire-and-forget reply channel has.

The One Ordering Rule That Matters

The worker loop looks like this, and the order of the last two lines is the whole reliability story:

var consumer = await js.CreateOrUpdateConsumerAsync("GRADING_JOBS",
    new ConsumerConfig("workers")
    {
        AckWait = TimeSpan.FromSeconds(60), // redeliver if no ack in time
        MaxDeliver = 4                      // bounded poison retry
    });

await foreach (var msg in consumer.ConsumeAsync<GradingJob>(cancellationToken: ct))
{
    GradingJobOutcome outcome = await grader.GradeAsync(msg.Data, ct);

    // Publish the result FIRST, then ack the job.
    await js.PublishAsync($"grading.results.{msg.Data.JobId}", outcome, cancellationToken: ct);
    await msg.AckAsync(cancellationToken: ct);
}

Publish the result before you ack the job. Walk the failure windows and you'll see why:

• Crash before the publish: the job is un-acked, so JetStream redelivers it after AckWait and another worker grades it. Nothing is lost.
• Crash between publish and ack: the job is redelivered and graded again, and a second identical result is published. Grading is idempotent and keyed by job id, so the duplicate is harmless.

Ack first and you reopen the Redis hole: a crash after the ack but before the publish loses the result with no way to recover it. At-least-once delivery plus idempotent processing beats exactly-once promises every time.

MaxDeliver handles the adversarial case. A submission that reproducibly crashes its worker (I run untrusted code, so this is a when, not an if) is redelivered a bounded number of times and then dropped, and JetStream emits a MAX_DELIVERIES advisory that monitoring alerts on. Without it, one poison job crash-loops your whole worker pool forever.

Masking It All Behind a Synchronous API

From the user's perspective nothing here is asynchronous: the API holds the HTTP request open, awaits the result subject up to a dispatch budget, and returns a retriable 503 on timeout. Every failure mode above degrades to "try again", never to a silently missing result.

Two honest limitations, so you can steal this design with eyes open:

• A single NATS node is a single point of failure. Jobs survive a restart (file-backed streams), but not a dead disk. Clustered JetStream with RAFT replicas is the fix when you outgrow one box; at my volume, one box is fine.
• The results stream is retention-bounded. If a client should be able to fetch a result hours later, the queue is the wrong home for it; persist results to Postgres and treat the stream purely as transport.

And if you want to see the queue from the user's side, every submission on Katabench rides through it, a few hundred milliseconds at a time.

This page maps EF Core performance techniques from quick wins to specialized optimizations. Start with query optimization; that's where the biggest gains hide.

Why EF Core Performance Matters

Entity Framework Core is the most popular ORM in the .NET ecosystem. It makes data access simple, but that simplicity can hide inefficient queries, excessive database round trips, and memory issues.

Without proper optimization, EF Core can become the bottleneck in your application - especially under load.

This guide collects the most impactful performance techniques, organized from quick wins to advanced strategies.

Query Optimization

The biggest performance gains usually come from how you write your queries. These articles cover techniques that reduce database load and improve response times.

• How to Improve Performance with EF Core Query Splitting
• Unleash EF Core Performance with Compiled Queries
• How I Made My EF Core Query Faster with Batching
• How to Use Global Query Filters in EF Core
• DbContext Is Not Thread Safe: Parallelizing EF Core Queries the Right Way
• Common EF Core Query Performance Mistakes
• Solving the N+1 Query Problem in EF Core
• Lazy, Eager, and Explicit Loading in EF Core

Choosing Your Data Access

EF Core is not the only way to talk to your database, and it is not always the fastest. These guides help you pick the right tool and get the most out of a lightweight one.

• EF Core vs Dapper: When to Use Each
• Dapper in .NET: A Complete Guide

Bulk Operations

When you need to insert or update thousands of rows, the standard SaveChanges() approach won't cut it. These articles show you how to handle bulk data efficiently.

• Fast SQL Bulk Inserts with C# and EF Core
• What You Need to Know About EF Core Bulk Updates
• How to Use the New Bulk Update Feature in EF Core 7
• Optimizing Bulk Database Updates in .NET

Concurrency and Locking

Concurrent access to the same data can cause race conditions and data corruption. EF Core provides built-in mechanisms to handle this safely.

• Solving Race Conditions with EF Core Optimistic Locking
• A Clever Way to Implement Pessimistic Locking in EF Core
• Working with Transactions in EF Core

Advanced Features

EF Core has a rich feature set beyond basic CRUD. These articles cover interceptors, raw SQL, soft deletes, multi-tenancy, and more.

• 5 EF Core Features You Need to Know
• How to Use EF Core Interceptors
• EF Core Raw SQL Queries
• Implementing Soft Delete with EF Core
• Multi-Tenant Applications with EF Core
• Using Multiple EF Core DbContext in a Single Application
• Using Stored Procedures and Functions with EF Core and PostgreSQL
• EF Core Compiled Models for Faster Startup
• DbContext Pooling in EF Core
• EF Core Connection Resiliency
• Understanding the EF Core Change Tracker

What's New in EF Core 10

EF Core 10 ships with .NET 10 and adds features that used to require workarounds. These articles cover what changed and how to put it to use.

• Named Query Filters in EF 10: Multiple Query Filters Per Entity
• What's New in EF Core 10: LeftJoin and RightJoin Operators in LINQ

Migrations and Schema Management

Keeping your database schema in sync with your code is a critical part of any EF Core project.

• EF Core Migrations: A Detailed Guide
• EF Core Migrations Best Practices
• Zero-Downtime EF Core Migrations

This failure mode is invisible precisely because nothing fails: the query is correct at 6 rows and a disaster at 60 million, and the difference never shows up in a unit test. It is also, in my experience, the single most common database performance bug in application code, and it usually comes from one innocent-looking habit.

The Habit: Wrapping the Column in a Function

Say a CI server stores one row per build in a builds table, with an index on result. You want every build with a given result, case-insensitively, so you write the defensive classic:

SELECT id FROM builds
WHERE lower(result) = lower(@value)
ORDER BY id;

Correct. And the index on result is now useless.

A B-tree index stores the raw column values in sorted order. Postgres can seek into it for result = 'CANCELLED', but lower(result) is a different value that exists nowhere in the index, so the only option is to compute lower() for every row in the table. That is a sequential scan, by construction.

The property has an old-fashioned name: sargability (from "Search ARGument-able"). A predicate is sargable when the column stands alone on its side of the comparison, and every function you wrap around the column takes the index off the table. The same trap has many costumes:

• lower(email) = lower(@email) and friends
• EXTRACT(YEAR FROM placed_at) = 2026, or in EF Core LINQ, o.PlacedAt.Year == year, which translates to exactly that
• CAST(id AS text) LIKE @pattern
• Arithmetic on the column: price * 1.2 > @limit

The fix is always the same move: transform the parameter, not the column. A year filter becomes a range over the raw column (placed_at >= '2026-01-01' AND placed_at < '2027-01-01'). And the case-insensitive comparison? If the data is stored in one consistent case, compare the raw column and let the index seek; if you genuinely need case-insensitivity, put an expression index on lower(result) or use citext, and the wrapped form becomes sargable.

Seeing It: EXPLAIN Is the Only Truth

You cannot detect this by reading the query, timing it, or counting green tests. The only tool that tells the truth is the query plan:

EXPLAIN (FORMAT JSON)
SELECT id FROM builds
WHERE lower(result) = lower(@value)
ORDER BY id;

EXPLAIN without ANALYZE only plans, never executes, so it is safe anywhere. If the plan tree contains a Seq Scan on your table where you expected an index node, you have your answer.

This mattered enough to me that I built it into a product. Katabench, my coding platform, has a database track where every kata runs your C# (raw SQL via Dapper, or EF Core) against a real, throwaway PostgreSQL instance created for your submission and destroyed afterwards. No in-memory fakes; the same philosophy as Testcontainers, because the planner is the thing being learned.

Here is the kata built on exactly the lower() trap ("Builds by Result"). The starter code ships the defensive query, and the interactive Run shows you the SQL your code produced and the plan it got, right under the test:

Look at the bottom-right: the test passes (175 ms, well inside budget), and the plan underneath says Seq Scan on builds, full table read. That pairing is the whole lesson in one screenshot: correct and slow-at-scale are compatible, and only the plan tells you.

Grading the Plan, Not the Stopwatch

Here is the design problem that made this kata interesting to build: you cannot teach this with a timing gate.

On a small visible fixture, the sequential scan genuinely is the fastest plan (reading six rows beats bouncing through an index), so the naive query would pass any latency threshold you set. Worse, on a tiny table Postgres will seq-scan even a perfectly sargable query, because the planner is right to. Timing gates on small data teach nothing, and timing gates on huge data are flaky.

So the kata grades the plan itself, against a large hidden dataset (sixty thousand rows, seeded and then ANALYZEd so the planner has honest statistics). After the timed runs, the harness re-issues your captured statements as EXPLAIN (FORMAT JSON) with the same bound parameters, and asserts rules over the plan tree: no Seq Scan on builds, the plan must use ix_builds_result, and the answer must be a single statement, one round-trip.

Rewrite the query to compare the raw column, and the verdict flips:

Same green tests, but now the graded plan shows Bitmap Index Scan using ix_builds_result, and all three plan rules hold. The difference between the two screenshots is one lower() call.

The Takeaway Habit

You do not need a kata platform to build the reflex; you need one habit:

When you write a WHERE clause, look at which side of the operator the column is on. If the column is wrapped in anything (a function, a cast, arithmetic, a property extraction that your ORM turns into a function), the index is out of the game, and only EXPLAIN on realistic data will tell you.

And if you want the reflex drilled into your fingers rather than your bookmarks, the database track on Katabench will happily fail your query plan until it sticks.

The reflex answer is Redis and a RedLock library (I surveyed the options in distributed locking in .NET). But there is a lock manager already in the architecture, battle-tested, transactional, and free: Postgres.

Advisory Locks in One Minute

Postgres advisory locks are locks over an application-defined 64-bit key. Postgres never interprets the key; it just guarantees that only one session can hold it at a time:

SELECT pg_advisory_lock(42);    -- blocks until acquired
SELECT pg_advisory_unlock(42);  -- explicit release

Two properties make the session-level variant the right primitive for a distributed lock:

• It serializes across every instance that shares the database. The lock lives in Postgres, not in process memory.
• It auto-releases when the holding connection closes. A crashed pod, a killed deploy, a network partition that drops the connection: in every case, Postgres frees the lock immediately. There is no TTL to tune, no lease to renew, and no stuck key to page you at 3 a.m.

That second property is the whole argument. A TTL-based Redis lease has to pick an expiry: too short and the lock expires mid-critical-section (now you need fencing tokens), too long and a crash wedges the key for the full TTL. Session advisory locks sidestep the dilemma, because the lock's lifetime is the connection's lifetime.

The Implementation

The full class is small. The design decisions are in the details, so let's walk them:

public sealed class PostgresAdvisoryLock(
    string connectionString,
    ILogger<PostgresAdvisoryLock> logger) : IDistributedLock
{
    // How long a caller waits for a contended lock before giving up.
    private static readonly TimeSpan WaitTimeout = TimeSpan.FromSeconds(15);

    public async Task<IAsyncDisposable> AcquireAsync(
        string key,
        CancellationToken cancellationToken = default)
    {
        long lockKey = HashKey(key);
        NpgsqlConnection? connection = null;
        try
        {
            // A dedicated connection: the lock is held for the handle's lifetime.
            connection = new NpgsqlConnection(connectionString);
            await connection.OpenAsync(cancellationToken);

            using var timeout = CancellationTokenSource
                .CreateLinkedTokenSource(cancellationToken);
            timeout.CancelAfter(WaitTimeout);

            using var command = new NpgsqlCommand(
                "SELECT pg_advisory_lock(@key)", connection);
            command.Parameters.AddWithValue("key", lockKey);
            await command.ExecuteNonQueryAsync(timeout.Token);

            return new Handle(connection, lockKey, logger);
        }
        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
        {
            // Our WaitTimeout fired, not the caller's token: a holder is stuck.
            logger.LogWarning(
                "Lock '{Key}' timed out after {Timeout}s; proceeding without it.",
                key, WaitTimeout.TotalSeconds);
            await DisposeQuietlyAsync(connection);
            return NullAsyncDisposable.Instance;
        }
        catch (Exception ex) when (ex is NpgsqlException or TimeoutException)
        {
            logger.LogWarning(ex, "Lock '{Key}' unavailable; proceeding without it.", key);
            await DisposeQuietlyAsync(connection);
            return NullAsyncDisposable.Instance;
        }
    }
}

The lock lives on a dedicated connection. pg_advisory_lock binds the lock to the session that ran it, so the handle owns one connection from acquire to dispose. That is the cost model to keep in mind: each held lock pins a connection for the duration of the critical section. Keep critical sections short, or this pattern will walk you straight into an exhausted connection pool.

The wait is bounded. pg_advisory_lock blocks server-side until the lock is granted, so a stuck holder could hang requests forever. The linked cancellation token caps the wait at 15 seconds, and Npgsql cancels the server-side wait when it fires.

String keys are hashed with FNV-1a, not GetHashCode. Advisory locks take a bigint, and the map from "achievements:user:123" to that bigint must be identical in every process:

public static long HashKey(string key)
{
    const ulong offsetBasis = 14695981039346656037UL;
    const ulong prime = 1099511628211UL;
    ulong hash = offsetBasis;
    foreach (byte b in Encoding.UTF8.GetBytes(key))
    {
        hash ^= b;
        hash *= prime;
    }

    return unchecked((long)hash);
}

string.GetHashCode() is randomized per process in .NET, so two instances would hash the same key to different lock ids and never contend. A 64-bit FNV-1a collision, if you ever hit one, only makes two unrelated keys occasionally serialize: a performance blip, never a correctness bug.

Release has a built-in safety net. Disposal runs pg_advisory_unlock, but even if that command fails, disposing the connection ends the Postgres session, and the session's death releases every advisory lock it held. The lock physically cannot leak.

Failing Open Is a Choice: Make It Consciously

Notice what the catch blocks do: when the lock cannot be acquired (database unreachable, or a stuck holder times out the wait), the method logs a warning and returns a no-op handle, and the caller proceeds without the lock.

That is fail-open, and it is only correct because of what this lock protects: a best-effort feature where the fallback is the pre-lock behavior (a rare duplicate award, resolved by an idempotent write). Degrading to the old race beats turning submissions into 500s because the lock store hiccuped.

Invert the decision the moment the lock guards something that must never run twice: money movement, external side effects, destructive migrations. There, a failed acquisition should fail the operation loudly. The point is that fail-open versus fail-closed is a per-call-site decision about blast radius, not a property of the lock class.

When Postgres Is the Wrong Lock

Honest boundaries, so you know when to reach for something else:

• High lock throughput. A connection open per acquisition is fine at "per-user, occasionally contended" rates and wrong at thousands of acquisitions per second. That is Redis territory.
• No shared database. If the services that need mutual exclusion do not already share a Postgres instance, adding one just for locks buys you nothing over Redis.
• Critical section = exactly one transaction. Use pg_advisory_xact_lock instead: it releases automatically at commit or rollback, and there is no handle to dispose.

But if your instances already share a Postgres database, and your contention profile is "rare and brief", you get a crash-safe distributed lock with zero new infrastructure and about a hundred lines of code. That trade is hard to beat.

What is Clean Architecture?

Clean Architecture is a software design philosophy that separates the elements of a design into ring levels. The key rule is that dependencies can only point inward - outer layers can depend on inner layers, but not vice versa.

In .NET, this typically means organizing your solution into layers like Domain, Application, Infrastructure, and Presentation. Each layer has a clear responsibility, and the dependency rule ensures your business logic stays independent of frameworks, databases, and UI concerns.

This guide brings together everything you need to master Clean Architecture in .NET.

Want to go deeper? My Pragmatic Clean Architecture course teaches the complete system I use to ship production-ready applications.

Getting Started

These articles cover the foundational concepts. If you're new to Clean Architecture, start here to understand the "why" before diving into implementation details.

• Clean Architecture and the Benefits of Structured Software Design
• Clean Architecture Folder Structure
• Building Your First Use Case with Clean Architecture
• A Clean Architecture Solution Template for .NET
• Clean Architecture with Minimal APIs

Core Concepts

Once you understand the basics, these articles explore the principles that make Clean Architecture effective in real-world projects - from handling complexity to managing cross-cutting concerns.

• Why Clean Architecture Is Great for Complex Projects
• Clean Architecture: The Missing Chapter
• Balancing Cross-Cutting Concerns in Clean Architecture
• Getting the Current User in Clean Architecture
• Clean Architecture Anti-Patterns and Common Mistakes
• Clean Architecture vs Onion vs Hexagonal Architecture
• When to Use Clean Architecture (And When Not To)
• The Dependency Rule in Clean Architecture

The Layers

Clean Architecture is built from four layers, each with a distinct responsibility. These guides go layer by layer, covering what belongs where and how the pieces map onto each other.

• The Domain Layer in Clean Architecture
• The Application Layer in Clean Architecture
• The Infrastructure Layer in Clean Architecture
• Mapping Between Layers in Clean Architecture
• Organizing Use Cases in Clean Architecture

CQRS and MediatR

The CQRS pattern is a natural complement to Clean Architecture. It separates read and write operations, keeping your use cases focused and testable.

• CQRS Pattern with MediatR
• CQRS Pattern: The Way It Should Have Been From the Start
• Stop Conflating CQRS and MediatR
• CQRS Validation with MediatR Pipeline and FluentValidation
• MediatR Pipeline Behaviors in .NET

Cross-Cutting Concerns

Clean Architecture gives cross-cutting concerns a clear home instead of letting them leak across layers. These guides cover concerns that appear in many production applications.

• Exception Handling in Clean Architecture
• Logging Strategy in Clean Architecture
• Authentication and Authorization in Clean Architecture
• Caching in Clean Architecture
• Background Jobs in Clean Architecture
• Transactions in Clean Architecture

Testing

A well-structured Clean Architecture solution is inherently testable. These guides cover testing strategies at different levels.

• Unit Testing Clean Architecture Use Cases
• Enforcing Software Architecture with Architecture Tests
• 5 Architecture Tests You Should Add to Your .NET Projects

Domain-Driven Design

Clean Architecture provides the structure, and DDD provides the modeling techniques. These articles cover the DDD fundamentals you'll use inside the Domain layer.

• Value Objects in .NET: DDD Fundamentals
• How to Use Domain Events to Build Loosely Coupled Systems
• Refactoring From an Anemic Domain Model to a Rich Domain Model
• From Transaction Scripts to Domain Models: A Refactoring Journey

Related Architectures

Clean Architecture isn't the only option. These complementary approaches can be used alongside it or as alternatives depending on your project's needs.

• Vertical Slice Architecture
• What Is a Modular Monolith?
• Screaming Architecture

What Is the REPR Pattern?

REPR stands for Request-Endpoint-Response. It's a pattern for organizing web API code where each endpoint is:

1. Request - a strongly-typed object representing the input
2. Endpoint - a single function handling one HTTP operation
3. Response - a strongly-typed object representing the output

Instead of grouping dozens of actions into controller classes (which violates the Single Responsibility Principle), each endpoint is its own thing.

This is how Minimal APIs naturally work - and it pairs perfectly with CQRS and Clean Architecture. The pattern itself was popularized by the FastEndpoints library and Ardalis (Steve Smith), but you don't need any library to use it.

The Problem With Controllers

Traditional controllers tend to grow into God classes:

[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;

    // 15 constructor parameters...
    // 20 action methods...
    // 500+ lines of code...

    [HttpPost]
    public async Task<IActionResult> PlaceOrder(PlaceOrderRequest request) { ... }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetOrder(Guid id) { ... }

    [HttpPut("{id}/cancel")]
    public async Task<IActionResult> CancelOrder(Guid id) { ... }

    [HttpGet]
    public async Task<IActionResult> GetOrders([FromQuery] GetOrdersRequest request) { ... }

    // ... 16 more methods
}

Problems:

• Violates SRP - one class handles many operations with different dependencies
• Constructor bloat - every action's dependencies are injected, even if only one action needs them
• Hard to navigate - finding the right action in a 500-line file is painful
• Merge conflicts - multiple developers editing the same controller file

REPR With Minimal APIs

Each endpoint becomes a focused, single-purpose function:

The Request

public sealed record PlaceOrderRequest(
    Guid CustomerId,
    List<OrderItemRequest> Items);

public sealed record OrderItemRequest(
    Guid ProductId,
    int Quantity);

The Endpoint

public sealed class PlaceOrderEndpoint : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/orders", Handle)
            .WithTags("Orders")
            .WithName("PlaceOrder")
            .Produces<PlaceOrderResponse>(StatusCodes.Status201Created)
            .ProducesProblem(StatusCodes.Status400BadRequest);
    }

    private static async Task<IResult> Handle(
        PlaceOrderRequest request,
        ICommandHandler<PlaceOrderCommand, Guid> handler,
        CancellationToken cancellationToken)
    {
        var command = new PlaceOrderCommand(request.CustomerId, request.Items);

        var result = await handler.Handle(command, cancellationToken);

        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", new PlaceOrderResponse(result.Value))
            : result.ToProblemDetails();
    }
}

IEndpoint is a one-method interface that powers auto-discovery. I define it in the auto-discovery section below.

The Response

public sealed record PlaceOrderResponse(Guid OrderId);

Each endpoint lives in its own file with its own request, response, and handler reference. No shared state, no bloated constructor.

Organizing REPR Endpoints by Feature

Api/
  Endpoints/
    Orders/
      PlaceOrderEndpoint.cs
      PlaceOrderRequest.cs
      PlaceOrderResponse.cs
      GetOrderEndpoint.cs
      GetOrderResponse.cs
      CancelOrderEndpoint.cs
    Customers/
      RegisterCustomerEndpoint.cs
      RegisterCustomerRequest.cs
      GetCustomerEndpoint.cs
    Products/
      CreateProductEndpoint.cs
      GetProductsEndpoint.cs

Or colocate request/response inside the endpoint class for smaller endpoints:

public sealed class CancelOrderEndpoint : IEndpoint
{
    public sealed record CancelOrderResponse(Guid OrderId, string Status);

    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapPut("/api/orders/{orderId:guid}/cancel", Handle)
            .WithTags("Orders");
    }

    private static async Task<IResult> Handle(
        Guid orderId,
        ICommandHandler<CancelOrderCommand> handler,
        CancellationToken cancellationToken)
    {
        var command = new CancelOrderCommand(orderId);

        var result = await handler.Handle(command, cancellationToken);

        return result.IsSuccess
            ? Results.Ok(new CancelOrderResponse(orderId, "Cancelled"))
            : result.ToProblemDetails();
    }
}

Auto-Discovering Endpoints

Instead of manually registering each endpoint, define a small interface and scan the assembly at startup:

public interface IEndpoint
{
    void MapEndpoint(IEndpointRouteBuilder app);
}

public static class EndpointExtensions
{
    public static void MapEndpoints(this IEndpointRouteBuilder app)
    {
        var endpointTypes = typeof(Program).Assembly
            .GetTypes()
            .Where(t => t is { IsClass: true, IsAbstract: false } &&
                        t.IsAssignableTo(typeof(IEndpoint)));

        foreach (var type in endpointTypes)
        {
            var endpoint = (IEndpoint)Activator.CreateInstance(type)!;

            endpoint.MapEndpoint(app);
        }
    }
}

// Program.cs
app.MapEndpoints();

Now every class implementing IEndpoint is automatically registered. Activator.CreateInstance works here because endpoint classes are stateless (their dependencies arrive as Handle parameters). I walk through a production-ready version of this approach (including DI registration of endpoint classes) in automatically registering Minimal APIs, and how I structure Minimal APIs covers where these files should live.

REPR + CQRS

REPR and CQRS are natural partners:

• POST/PUT/DELETE endpoints map to Commands
• GET endpoints map to Queries

// Write endpoint → Command
public sealed class PlaceOrderEndpoint : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app) =>
        app.MapPost("/api/orders", Handle);

    private static async Task<IResult> Handle(
        PlaceOrderRequest request,
        ICommandHandler<PlaceOrderCommand, Guid> handler,
        CancellationToken ct)
    {
        var command = new PlaceOrderCommand(request.CustomerId, request.Items);
        var result = await handler.Handle(command, ct);
        return result.IsSuccess
            ? Results.Created($"/api/orders/{result.Value}", result.Value)
            : result.ToProblemDetails();
    }
}

// Read endpoint → Query
public sealed class GetOrderEndpoint : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app) =>
        app.MapGet("/api/orders/{orderId:guid}", Handle);

    private static async Task<IResult> Handle(
        Guid orderId,
        IQueryHandler<GetOrderByIdQuery, OrderResponse> handler,
        CancellationToken ct)
    {
        var result = await handler.Handle(new GetOrderByIdQuery(orderId), ct);
        return result.IsSuccess ? Results.Ok(result.Value) : Results.NotFound();
    }
}

Each endpoint is a thin adapter between HTTP and your Application layer.

REPR vs MVC Controllers

How the two approaches compare in practice:

• Granularity: REPR gives you one class per operation; controllers give you one class per resource with many actions.
• Dependencies: a REPR endpoint declares only what that operation needs. A controller's constructor accumulates every action's dependencies.
• File size: REPR endpoints stay at 20-50 lines. Controllers routinely grow into hundreds.
• Merge conflicts: rare with one file per operation, common when a team shares one controller file.
• Navigation: with REPR, the file name is the operation. With controllers, you scroll.
• Testing: identical. In both styles the real logic lives in the handler, and the HTTP layer stays thin.
• OpenAPI metadata: REPR endpoints declare Produces metadata explicitly; [ApiController] conventions infer more automatically.

The one scenario where controllers still earn their keep: if you depend heavily on MVC-specific features (filters with complex ordering, model binding conventions, view results), migrating to REPR is a bigger lift than the benefit justifies.

Do You Need a Library?

Three ways to get REPR in practice:

• Plain Minimal APIs (what this article shows): zero dependencies, full control, you own the ~30 lines of auto-discovery code.
• FastEndpoints: a mature library built entirely around REPR, with base classes per endpoint, built-in validation, and its own request pipeline. Great if you want conventions decided for you; the cost is a framework layer between you and ASP.NET Core.
• Single-action controllers: one controller class per operation. Works if your team must stay on MVC, but you keep the controller ceremony without gaining much.

I default to plain Minimal APIs. The pattern is simple enough that a library is optional, and staying on the framework's primitives means every ASP.NET Core feature (filters, rate limiting, OpenAPI) works without adapter layers.

The Vertical Slice Decision

The REPR pattern treats each API operation as an independent unit: one request, one endpoint function, one response.

Combined with Minimal APIs and CQRS, it gives you focused, maintainable endpoint files that map cleanly to your Application layer commands and queries.

Stop writing 500-line controllers. One endpoint, one file, one responsibility.

What Makes a Good Unit Test?

A good unit test has four properties:

1. Fast - runs in milliseconds, not seconds
2. Isolated - doesn't depend on databases, file systems, or external services
3. Repeatable - produces the same result every time
4. Self-validating - passes or fails without manual inspection

If your tests take minutes to run, developers stop running them. If they fail randomly, developers stop trusting them. If they're hard to maintain, developers stop writing them.

The AAA Pattern

Structure every test with Arrange, Act, Assert:

[Fact]
public void Order_AddLineItem_IncreasesTotalAmount()
{
    // Arrange
    var order = Order.Create(Guid.NewGuid());
    var price = Money.Create(25.00m, "USD");

    // Act
    order.AddLineItem(Guid.NewGuid(), price, quantity: 2);

    // Assert
    order.TotalAmount.Amount.Should().Be(50.00m);
}

Clear separation between setup, execution, and verification. One glance tells you what's being tested.

Name Tests Clearly

Test names should describe the scenario and expected outcome:

// Bad - what does this tell you?
[Fact]
public void Test1() { }

// Bad - too vague
[Fact]
public void OrderTest() { }

// Good - describes the behavior
[Fact]
public void Cancel_WhenOrderIsShipped_ReturnsFailure() { }

[Fact]
public void AddLineItem_WithValidProduct_IncreasesTotal() { }

[Fact]
public void Create_WithEmptyEmail_ReturnsValidationError() { }

Use the pattern: Method_Scenario_ExpectedResult or Given_When_Then. Pick one convention and use it consistently across your project.

Test One Behavior Per Test

Each test should verify one logical behavior. Not one assertion - one behavior.

// Bad - testing multiple behaviors
[Fact]
public void PlaceOrder_WorksCorrectly()
{
    var order = Order.Create(customerId);
    order.AddLineItem(productId, price, 2);
    order.Complete();

    order.LineItems.Should().HaveCount(1);
    order.TotalAmount.Should().Be(Money.Create(50, "USD"));
    order.Status.Should().Be(OrderStatus.Completed);
    order.DomainEvents.Should().ContainSingle(e => e is OrderCompletedDomainEvent);
}

// Good - one behavior per test
[Fact]
public void AddLineItem_IncreasesLineItemCount()
{
    var order = Order.Create(customerId);
    order.AddLineItem(productId, price, 2);

    order.LineItems.Should().HaveCount(1);
}

[Fact]
public void Complete_RaisesOrderCompletedEvent()
{
    var order = CreateOrderWithItems();
    order.Complete();

    order.DomainEvents.Should().ContainSingle(e => e is OrderCompletedDomainEvent);
}

When a test fails, you immediately know which behavior broke.

Use Domain-Specific Assertions

Assertion libraries like FluentAssertions (or the free Shouldly and AwesomeAssertions alternatives, worth knowing since FluentAssertions v8 moved to a paid license for commercial use) make tests more readable. The FluentAssertions alternatives comparison covers the licensing and API trade-offs in detail:

// Without FluentAssertions
Assert.Equal(OrderStatus.Completed, order.Status);
Assert.True(result.IsSuccess);
Assert.NotNull(customer);

// With FluentAssertions
order.Status.Should().Be(OrderStatus.Completed);
result.IsSuccess.Should().BeTrue();
customer.Should().NotBeNull();

For domain-specific assertions, create extension methods:

public static class ResultAssertionExtensions
{
    public static void ShouldBeSuccess<T>(this Result<T> result)
    {
        result.IsSuccess.Should().BeTrue(
            $"Expected success but got failure: {result.Error}");
    }

    public static void ShouldBeFailure<T>(
        this Result<T> result, Error expectedError)
    {
        result.IsFailure.Should().BeTrue();
        result.Error.Should().Be(expectedError);
    }
}

[Fact]
public void Cancel_WhenDraft_ReturnsSuccess()
{
    var order = CreateDraftOrder();
    var result = order.Cancel();

    result.ShouldBeSuccess();
}

Use Test Data Builders

Constructing test objects inline makes tests brittle and noisy:

// Brittle - if Customer constructor changes, every test breaks
[Fact]
public void Test()
{
    var customer = new Customer(
        Guid.NewGuid(),
        "John Doe",
        Email.Create("john@example.com").Value,
        Address.Create("123 Main St", "NYC", "NY", "10001", "US").Value,
        false);
}

Use a builder:

public class CustomerBuilder
{
    private Guid _id = Guid.NewGuid();
    private string _name = "John Doe";
    private Email _email = Email.Create("john@example.com").Value;
    private bool _isVip = false;

    public CustomerBuilder WithName(string name) { _name = name; return this; }
    public CustomerBuilder WithEmail(string email) { _email = Email.Create(email).Value; return this; }
    public CustomerBuilder AsVip() { _isVip = true; return this; }

    public Customer Build() => Customer.Create(_id, _name, _email, _isVip);
}

[Fact]
public void VipCustomer_GetsDiscount()
{
    var customer = new CustomerBuilder().AsVip().Build();
    var discount = _discountService.CalculateDiscount(customer);

    discount.Should().Be(10);
}

Builders isolate your tests from constructor changes and make the test's intent clear. I go deeper on this pattern (composition, factory methods, combining with Bogus) in test data builders in C#.

Don't Test Implementation Details

Test behavior, not implementation. Tests that verify internal state or call order are brittle.

// Bad - testing implementation details
[Fact]
public void PlaceOrder_CallsRepositoryAdd()
{
    _mockRepository.Verify(r => r.Add(It.IsAny<Order>()), Times.Once);
}

// Good - testing observable behavior
[Fact]
public async Task PlaceOrder_ReturnsOrderId()
{
    var result = await _handler.Handle(new PlaceOrderCommand(...), CancellationToken.None);

    result.IsSuccess.Should().BeTrue();
    result.Value.Should().NotBeEmpty();
}

The first test breaks if you rename the repository method. The second test passes as long as the behavior is correct, regardless of how it's implemented. The focused guide to testing CQRS handlers applies this rule to success paths, validation failures, and persistence boundaries.

When to Use Mocks (and When Not To)

Mock external dependencies - things at the system boundary:

• Database repositories
• HTTP clients
• Email services
• Message brokers
• Time providers

Don't mock domain objects - test them directly:

// Don't mock the Order - test it directly
[Fact]
public void Order_Cancel_WhenShipped_Fails()
{
    var order = CreateShippedOrder();
    var result = order.Cancel();

    result.IsFailure.Should().BeTrue();
    result.Error.Should().Be(OrderErrors.AlreadyShipped);
}

If you find yourself mocking too many things, your class has too many dependencies. Consider refactoring.

And know your vocabulary: mocks, stubs, fakes, and spies are different tools with different failure modes. I break down when to use each test double separately.

Parameterized Tests

Use [Theory] with data sources to test multiple scenarios without duplicating code. I covered data-driven tests with xUnit in detail, but here's the short version:

[Theory]
[InlineData("", false)]
[InlineData("not-an-email", false)]
[InlineData("john@example.com", true)]
[InlineData("jane@company.co.uk", true)]
public void Email_Create_ValidatesFormat(string input, bool shouldSucceed)
{
    var result = Email.Create(input);
    result.IsSuccess.Should().Be(shouldSucceed);
}

For complex test data, use [MemberData]:

public static IEnumerable<object[]> InvalidOrderData =>
    new List<object[]>
    {
        new object[] { Guid.Empty, "Customer ID is required" },
        new object[] { Guid.NewGuid(), null },  // null items
    };

[Theory]
[MemberData(nameof(InvalidOrderData))]
public void PlaceOrder_WithInvalidData_Fails(Guid customerId, string errorMessage)
{
    // ...
}

Test Domain Logic, Not Frameworks

Focus your unit tests on code you own - domain entities, value objects, and domain services.

Don't unit test:

• EF Core configurations (use integration tests instead)
• ASP.NET Core middleware
• Third-party library behavior
• DTOs and simple mappings

// Worth unit testing - domain invariant
[Fact]
public void Order_AddLineItem_WhenNotDraft_ThrowsDomainException()
{
    var order = CreateCompletedOrder();
    var act = () => order.AddLineItem(productId, price, 1);

    act.Should().Throw<DomainException>()
       .WithMessage("Cannot modify a non-draft order.");
}

// NOT worth unit testing - it's just EF Core
[Fact]
public void DbContext_CanSaveOrder()
{
    // This tests EF Core, not your code. Use integration tests.
}

Organize Tests to Mirror Source

tests/
  Domain.UnitTests/
    Orders/
      OrderTests.cs
      OrderLineItemTests.cs
    Customers/
      CustomerTests.cs
      EmailTests.cs
  Application.UnitTests/
    Orders/
      PlaceOrderCommandHandlerTests.cs
      CancelOrderCommandHandlerTests.cs

Mirror the source project structure so tests are easy to find.

What the Test Should Prove

Good unit tests protect your domain logic and give you confidence to refactor. Bad unit tests slow you down and break every time you change anything.

Follow these practices:

• Use AAA structure consistently
• Name tests descriptively
• Test behaviors, not implementation details
• Use builders for test data
• Mock only external boundaries
• Prefer parameterized tests for multiple scenarios

Your unit tests should be assets, not liabilities. And keep them in proportion: unit tests protect your domain logic, but they can't tell you the system works end to end, which is why I don't chase the classic test pyramid shape.

This guide covers the full setup: token generation, validation, refresh tokens, and the configuration mistakes that weaken an otherwise sound design. If another identity provider issues the token, use the stricter third-party JWT validation checklist.

What Is JWT Authentication?

JWT (JSON Web Token) is a compact, URL-safe token format used to represent claims between two parties. It's the most common way to authenticate REST APIs.

The flow:

1. Client sends credentials (username + password)
2. Server validates credentials and generates a JWT
3. Client includes the JWT in the Authorization header of subsequent requests
4. Server validates the JWT on every request

Setting Up JWT Authentication

Install the required package:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Configure the authentication middleware:

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.MapInboundClaims = false;

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecretKey"]!)),
            ClockSkew = TimeSpan.Zero  // Disable the default 5-minute grace period
        };
    });

builder.Services.AddAuthorization();

Note the MapInboundClaims = false line. By default, the JWT handler silently renames standard claims to legacy XML claim type URIs, so sub arrives as ClaimTypes.NameIdentifier and FindFirst(JwtRegisteredClaimNames.Sub) returns null. Disabling the mapping keeps claims exactly as they appear in the token, and it is the number one JWT gotcha I see in real projects.

Add the middleware in the correct order:

app.UseAuthentication();
app.UseAuthorization();

Generating JWT Tokens

Create a token provider service that issues both tokens: a short-lived JWT access token and a random refresh token persisted to the database. The RefreshToken entity is defined in the refresh tokens section below.

public sealed class TokenProvider
{
    private readonly IConfiguration _configuration;
    private readonly AppDbContext _dbContext;

    public TokenProvider(IConfiguration configuration, AppDbContext dbContext)
    {
        _configuration = configuration;
        _dbContext = dbContext;
    }

    public (string AccessToken, string RefreshToken) GenerateTokens(User user)
    {
        var accessToken = GenerateAccessToken(user);

        var refreshToken = new RefreshToken
        {
            Id = Guid.NewGuid(),
            UserId = user.Id,
            Token = Convert.ToBase64String(RandomNumberGenerator.GetBytes(64)),
            ExpiresAt = DateTime.UtcNow.AddDays(7),
            CreatedAt = DateTime.UtcNow
        };

        _dbContext.RefreshTokens.Add(refreshToken);

        return (accessToken, refreshToken.Token);
    }

    private string GenerateAccessToken(User user)
    {
        var claims = new List<Claim>
        {
            new(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
            new(JwtRegisteredClaimNames.Email, user.Email),
            new(JwtRegisteredClaimNames.Name, user.FullName),
            new("permission", "orders:read"),
            new("permission", "orders:write")
        };

        // Add role claims
        foreach (var role in user.Roles)
        {
            claims.Add(new(ClaimTypes.Role, role.Name));
        }

        var key = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_configuration["Jwt:SecretKey"]!));

        var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(claims),
            Expires = DateTime.UtcNow.AddMinutes(30),
            SigningCredentials = credentials,
            Issuer = _configuration["Jwt:Issuer"],
            Audience = _configuration["Jwt:Audience"]
        };

        return new JsonWebTokenHandler().CreateToken(tokenDescriptor);
    }
}

I'm using JsonWebTokenHandler from Microsoft.IdentityModel.JsonWebTokens here, not the legacy JwtSecurityTokenHandler. It's the same handler ASP.NET Core uses to validate tokens since .NET 8, and it ships transitively with the JwtBearer package.

Register the provider (scoped, because it uses the DbContext):

builder.Services.AddScoped<TokenProvider>();

The Login Endpoint

The login endpoint returns both tokens. The access token authenticates requests, and the refresh token is the entry point for the refresh flow covered below.

public sealed record LoginRequest(string Email, string Password);

public sealed record LoginResponse(string AccessToken, string RefreshToken);

app.MapPost("/api/auth/login", async (
    LoginRequest request,
    IUserRepository userRepository,
    IPasswordHasher passwordHasher,
    TokenProvider tokenProvider,
    AppDbContext dbContext) =>
{
    var user = await userRepository.GetByEmailAsync(request.Email);

    if (user is null || !passwordHasher.Verify(request.Password, user.PasswordHash))
    {
        return Results.Unauthorized();
    }

    var (accessToken, refreshToken) = tokenProvider.GenerateTokens(user);

    await dbContext.SaveChangesAsync();

    return Results.Ok(new LoginResponse(accessToken, refreshToken));
});

The SaveChangesAsync call persists the refresh token that GenerateTokens added to the DbContext.

Security note: Always return the same error for "user not found" and "wrong password." This prevents user enumeration.

Protecting Endpoints

Use RequireAuthorization() on Minimal API endpoints:

// Requires any authenticated user
app.MapGet("/api/orders", GetOrders)
    .RequireAuthorization();

// Requires specific role
app.MapPost("/api/orders", CreateOrder)
    .RequireAuthorization(policy => policy.RequireRole("Admin", "Manager"));

// Requires specific claim
app.MapDelete("/api/orders/{id}", DeleteOrder)
    .RequireAuthorization(policy => policy.RequireClaim("permission", "orders:delete"));

Or use the [Authorize] attribute on controllers:

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [Authorize(Roles = "Admin")]
    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(Guid id) { ... }
}

Accessing User Claims

Get the current user's information from the JWT claims:

public sealed class UserContext : IUserContext
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public UserContext(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public Guid UserId => Guid.Parse(
        _httpContextAccessor.HttpContext?.User
            .FindFirst(JwtRegisteredClaimNames.Sub)?.Value
        ?? throw new UnauthorizedAccessException());

    public string Email =>
        _httpContextAccessor.HttpContext?.User
            .FindFirst(JwtRegisteredClaimNames.Email)?.Value
        ?? throw new UnauthorizedAccessException();

    public bool IsAuthenticated =>
        _httpContextAccessor.HttpContext?.User.Identity?.IsAuthenticated ?? false;
}

Looking up JwtRegisteredClaimNames.Sub only works because we set MapInboundClaims = false earlier. With the default mapping, sub would arrive as ClaimTypes.NameIdentifier and UserId would throw for every authenticated user.

Register it:

builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<IUserContext, UserContext>();

Inject IUserContext into your Application layer to access the current user without depending on ASP.NET Core. I covered this abstraction in depth in getting the current user in Clean Architecture.

For authorization beyond simple role checks, see my guide to claims-based authorization.

Refresh Tokens

Access tokens should be short-lived (15-30 minutes). Use refresh tokens for extended sessions.

public sealed class RefreshToken
{
    public Guid Id { get; set; }
    public Guid UserId { get; set; }
    public string Token { get; set; }
    public DateTime ExpiresAt { get; set; }
    public bool IsRevoked { get; set; }
    public DateTime CreatedAt { get; set; }
}

This is the entity that TokenProvider.GenerateTokens stores on every login. The client sends the refresh token back to exchange it for a new token pair:

public sealed record RefreshRequest(string RefreshToken);

app.MapPost("/api/auth/refresh", async (
    RefreshRequest request,
    AppDbContext dbContext,
    TokenProvider tokenProvider,
    IUserRepository userRepository) =>
{
    var storedToken = await dbContext.RefreshTokens
        .FirstOrDefaultAsync(r =>
            r.Token == request.RefreshToken &&
            !r.IsRevoked &&
            r.ExpiresAt > DateTime.UtcNow);

    if (storedToken is null)
    {
        return Results.Unauthorized();
    }

    // Rotate the refresh token
    storedToken.IsRevoked = true;

    var user = await userRepository.GetByIdAsync(storedToken.UserId);
    var (accessToken, newRefreshToken) = tokenProvider.GenerateTokens(user!);

    await dbContext.SaveChangesAsync();

    return Results.Ok(new LoginResponse(accessToken, newRefreshToken));
});

Key security practices:

• Rotate refresh tokens on every use (issue a new one, revoke the old)
• Store refresh tokens in the database (not just in memory)
• Set a reasonable expiration (7-14 days)
• Revoke all refresh tokens when the user changes their password

Rotation also lets you detect stolen tokens: if a revoked token is ever presented again, someone replayed it, and you should revoke the whole session family. I dig into that mechanism in refresh token rotation in ASP.NET Core.

Configuration

Store JWT settings in appsettings.json:

{
  "Jwt": {
    "Issuer": "https://myapp.com",
    "Audience": "https://myapp.com",
    "SecretKey": "your-256-bit-secret-key-here-minimum-32-chars"
  }
}

For production, use a proper secret management solution - not appsettings.json.

Common Security Mistakes

1. Weak signing keys. Use at least 256-bit keys for HMAC. Better: use RSA keys.

2. Storing tokens in localStorage. Vulnerable to XSS. Use HttpOnly cookies for web applications.

3. Long-lived access tokens. Keep them short (15-30 minutes). Use refresh tokens for longer sessions.

4. Not validating all token properties. Always validate issuer, audience, lifetime, and signing key.

5. Setting ClockSkew too high. The default 5-minute clock skew means expired tokens are valid for 5 extra minutes. Set it to TimeSpan.Zero and handle clock synchronization at the infrastructure level.

6. Including sensitive data in the payload. JWTs are signed but not encrypted by default. Don't put passwords, SSNs, or API keys in claims.

The Safe Default

JWT authentication in ASP.NET Core is straightforward:

1. Configure AddJwtBearer with proper validation and MapInboundClaims = false
2. Create a TokenProvider that generates access and refresh tokens
3. Use RequireAuthorization() on endpoints
4. Implement refresh token rotation for extended sessions
5. Store secrets properly and keep access tokens short-lived

For more advanced scenarios, consider using an identity provider like Keycloak instead of managing JWTs yourself.

Polly v8 threw that API out and rebuilt the library around a single concept: the resilience pipeline. It wasn't churn for its own sake. The rewrite (done in collaboration with Microsoft, who built Microsoft.Extensions.Http.Resilience on top of it) fixed real problems: duplicated sync/async APIs, allocation-heavy execution, bolt-on telemetry, and the perpetually confusing PolicyWrap ordering.

Here's the new model, the migration mapping, and the one behavior (strategy ordering) that deserves more attention than it gets.

From Policies to Pipelines

The v8 mental model has three pieces:

• A strategy is one resilience behavior: retry, circuit breaker, timeout, rate limiter, fallback, hedging.
• A pipeline is an ordered composition of strategies, built once and cached.
• Everything is configured through options classes with ShouldHandle predicates, instead of fluent Handle chains.

Side by side. Polly v7:

var retry = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)));

var timeout = Policy.TimeoutAsync(TimeSpan.FromSeconds(10));

var wrapped = Policy.WrapAsync(retry, timeout);

await wrapped.ExecuteAsync(() => httpClient.GetAsync(url));

Polly v8:

dotnet add package Polly.Core

using Polly;
using Polly.Retry;

ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        ShouldHandle = new PredicateBuilder().Handle<HttpRequestException>(),
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromSeconds(1),
        BackoffType = DelayBackoffType.Exponential,
        UseJitter = true
    })
    .AddTimeout(TimeSpan.FromSeconds(10))
    .Build();

await pipeline.ExecuteAsync(
    async ct => await httpClient.GetAsync(url, ct),
    cancellationToken);

Details worth noticing:

• One API for sync and async. ResiliencePipeline has Execute and ExecuteAsync; the v7 split between Policy and AsyncPolicy is gone.
• Cancellation is first-class. The callback receives a CancellationToken that the pipeline manages; a timeout strategy cancels your delegate through it, not by abandoning it.
• Jitter is a property, not a contrib package. Exponential backoff with jitter is UseJitter = true.
• Generic pipelines (ResiliencePipeline<HttpResponseMessage>) handle result-based conditions, like retrying on 5xx status codes, and are required for result-producing strategies like fallback and hedging.
• Build once, reuse forever. Pipelines are thread-safe and designed to be cached. Building one per request wastes the allocation work v8 did; the execution path itself is designed to be allocation-free.

The migration mapping, compactly: WaitAndRetryAsync becomes AddRetry with RetryStrategyOptions; AdvancedCircuitBreakerAsync becomes AddCircuitBreaker with failure-ratio options; TimeoutAsync becomes AddTimeout; BulkheadAsync becomes AddConcurrencyLimiter (the bulkhead pattern under a more accurate name); FallbackAsync becomes AddFallback; and PolicyWrap disappears entirely, because the pipeline is the composition. The v8 package still ships the legacy API, so migration can be incremental.

Ordering: The Same Strategies, Different Machine

PolicyWrap confused everyone about what wrapped what. Pipelines make it deterministic: strategies execute in the order added, first added is outermost. A call flows inward through each strategy to your delegate, and the outcome flows back out through them in reverse.

This isn't cosmetic. The same strategies in a different order are a different machine. The canonical example is timeout placement relative to retry:

// A: timeout OUTSIDE retry. One 10-second budget for ALL attempts.
new ResiliencePipelineBuilder()
    .AddTimeout(TimeSpan.FromSeconds(10))
    .AddRetry(retryOptions)
    .Build();

// B: timeout INSIDE retry. Each attempt gets its own 10 seconds.
new ResiliencePipelineBuilder()
    .AddRetry(retryOptions)
    .AddTimeout(TimeSpan.FromSeconds(10))
    .Build();

In A, retries race a shared deadline: the third attempt might get 1 second, and TimeoutRejectedException escaping the pipeline means the whole operation is over. In B, three attempts can burn 30 seconds plus backoff, and the retry sees each timeout and decides whether to go again. Neither is wrong; they answer different questions, and a robust pipeline often uses both, which is the heart of a sane timeout strategy.

The recommended general-purpose order, which is also what Microsoft's standard handler uses:

1. Rate limiter or concurrency limiter (shed load before spending effort on it)
2. Total timeout (the overall budget)
3. Retry
4. Circuit breaker (inside retry, so it sees every raw attempt and its failure stats stay honest; the retry then sees BrokenCircuitException and stops)
5. Per-attempt timeout

The retry vs circuit breaker interaction in step 4 is the subtlest part of the ordering, and the one worth internalizing before you tune any thresholds. And if you add chaos strategies with Simmy, they go last, innermost, so injected faults pass through all the real strategies.

Dependency Injection and Reuse

Polly.Extensions adds the DI registration model. You register a pipeline under a key, and Polly caches it:

dotnet add package Polly.Extensions

builder.Services.AddResiliencePipeline("database", pipeline =>
{
    pipeline
        .AddTimeout(TimeSpan.FromSeconds(15))
        .AddRetry(new RetryStrategyOptions
        {
            ShouldHandle = new PredicateBuilder()
                .Handle<NpgsqlException>(ex => ex.IsTransient),
            MaxRetryAttempts = 3,
            BackoffType = DelayBackoffType.Exponential,
            UseJitter = true
        });
});

Consume it through ResiliencePipelineProvider:

public class OrderRepository(
    ResiliencePipelineProvider<string> pipelineProvider,
    NpgsqlDataSource dataSource)
{
    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
    {
        var pipeline = pipelineProvider.GetPipeline("database");

        return await pipeline.ExecuteAsync(
            async token => await QueryOrderAsync(dataSource, id, token),
            ct);
    }
}

Registering through DI buys you the second headline feature: telemetry is on by default. Every strategy emits events (retry attempts, breaker state changes, timeouts) through ILogger and System.Diagnostics.Metrics, so the answer to "did the retry actually fire last night?" is in your logs and your OpenTelemetry metrics without any instrumentation code. In v7, that visibility was something you hand-rolled in onRetry callbacks, or more commonly didn't.

HttpClient: You Might Not Need to Build a Pipeline at All

For HTTP, Microsoft.Extensions.Http.Resilience packages the whole thing:

dotnet add package Microsoft.Extensions.Http.Resilience

builder.Services.AddHttpClient("catalog", client =>
{
    client.BaseAddress = new Uri("https://catalog.internal");
})
.AddStandardResilienceHandler();

That one line installs the recommended composition: rate limiter, 30-second total timeout, retry (3 attempts, exponential, jittered, honoring Retry-After), circuit breaker, and a 10-second per-attempt timeout, in exactly the outermost-to-innermost order listed earlier. It's the productized version of everything this article described, and for service-to-service HTTP it's the right default. When the defaults don't fit, override the standard resilience handlers or use AddResilienceHandler to compose your own; the broader patterns are covered in building resilient cloud applications with .NET.

The Resilience Baseline

Polly v8 is a better model, not just a new API.

• Pipelines replace policies and PolicyWrap: one composition mechanism, options-based configuration, unified sync/async, build-once-and-cache.
• Ordering is explicit and semantic: first added is outermost, and moving a timeout across a retry changes what your pipeline promises.
• DI registration gives you cached pipelines plus logs and metrics for every strategy activation, which turns "is our resilience working?" into a dashboard query.
• For HTTP, start with AddStandardResilienceHandler and customize only when you outgrow it.

Migrate incrementally; the legacy API still works. But write new resilience code as pipelines, and spend the time you save thinking about the part the library can't do for you: which strategies, with which thresholds, in which order.