vertical-slice

Vertical Slice Architecture

Reference material for structuring .NET APIs by feature rather than by layer.

Core Concept

Organize code by feature (vertical slice), not by technical layer (horizontal). Each slice owns everything needed for one feature: endpoint, handler, DTOs, validation. Two features never share request/response types — coupling through shared DTOs is how VSA projects collapse back into layered code.

Use when: ≤10 aggregates, CRUD-heavy API, team prefers feature-branch isolation, or Clean Architecture feels like over-engineering.

Avoid when: rich domain model with 10+ aggregates, complex cross-aggregate business rules, or event sourcing is on the roadmap — prefer Clean Architecture or DDD instead. See knowledge/decisions/adr-005-multi-architecture.md.

Folder Structure

src/MyApp/
  Features/
    Orders/
      CreateOrder/
        CreateOrderEndpoint.cs     # IEndpointGroup implementation
        CreateOrderHandler.cs      # Command handler (or inline in endpoint)
        CreateOrderRequest.cs      # Input DTO record
        CreateOrderResponse.cs     # Output DTO record
        CreateOrderValidator.cs    # FluentValidation validator
      GetOrder/
        GetOrderEndpoint.cs
        GetOrderQuery.cs
        GetOrderResponse.cs
      CancelOrder/
        CancelOrderEndpoint.cs
        CancelOrderCommand.cs
  Domain/                          # Shared only if 2+ features use it
    Orders/
      Order.cs
      OrderStatus.cs
  Infrastructure/
    Persistence/
      AppDbContext.cs
      Configurations/
  Program.cs

The Domain/ folder is for shared domain concepts only. If only one feature references an entity, keep it inside that feature's folder.

IEndpointGroup Pattern

Each feature registers its own route via IEndpointGroup. The interface is registered and scanned in Program.cs.

public interface IEndpointGroup
{
    void MapEndpoints(IEndpointRouteBuilder app);
}

// Features/Orders/CreateOrder/CreateOrderEndpoint.cs
public class CreateOrderEndpoint : IEndpointGroup
{
    public void MapEndpoints(IEndpointRouteBuilder app)
    {
        app.MapPost("/orders", HandleAsync)
            .WithName("CreateOrder")
            .WithOpenApi()
            .AddEndpointFilter<ValidationFilter<CreateOrderRequest>>()
            .RequireAuthorization();
    }

    private static async Task<IResult> HandleAsync(
        CreateOrderRequest request,
        AppDbContext db,
        CancellationToken ct)
    {
        var order = new Order(request.CustomerId, request.Items);
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return TypedResults.Created($"/orders/{order.Id}", new CreateOrderResponse(order.Id));
    }
}