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 most operations read or write a single entity with little business logic (CRUD-heavy APIs), or Clean Architecture feels like over-engineering.

Avoid when invariants span several entities, business rules outgrow CRUD, or event sourcing is on the roadmap — see "When to Use DDD" in skills/ddd/SKILL.md. Aggregate count alone doesn't decide it.

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")
            .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));
    }
}

// Program.cs — scan and register all IEndpointGroup implementations
var endpointGroups = typeof(Program).Assembly
    .GetTypes()
    .Where(t => t.IsAssignableTo(typeof(IEndpointGroup)) && !t.IsAbstract)
    .Select(Activator.CreateInstance)
    .Cast<IEndpointGroup>();

foreach (var group in endpointGroups)
    group.MapEndpoints(app);

DTOs

Use records. Never share request/response types between features — duplication here is intentional and correct.

// CreateOrderRequest.cs
public record CreateOrderRequest(Guid CustomerId, IReadOnlyList<OrderItemRequest> Items);
public record OrderItemRequest(Guid ProductId, int Quantity);

// CreateOrderResponse.cs
public record CreateOrderResponse(Guid OrderId);

Validation

Use FluentValidation per-request. Wire via a generic endpoint filter so individual endpoints don't repeat the call.

// Features/Orders/CreateOrder/CreateOrderValidator.cs
public class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity).GreaterThan(0);
        });
    }
}

// Infrastructure/Filters/ValidationFilter.cs
public class ValidationFilter<T>(IValidator<T> validator) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var request = ctx.GetArgument<T>(0);
        var result = await validator.ValidateAsync(request);
        if (!result.IsValid)
            return TypedResults.ValidationProblem(result.ToDictionary());
        return await next(ctx);
    }
}

Register validators and the filter in DI:

builder.Services.AddValidatorsFromAssemblyContaining<Program>();
builder.Services.AddScoped(typeof(ValidationFilter<>));

Cross-Cutting Concerns

Handle via endpoint filters, not base classes:

Extracting to Shared Domain

Extract to Domain/ only when two or more feature slices reference the same concept and it carries meaningful behavior (not just a DTO shape):

• Order entity referenced by CreateOrder, CancelOrder, GetOrder → extract to Domain/Orders/
• OrderStatus enum used across multiple features → extract
• CreateOrderRequest used by only one feature → keep it in the feature folder

The Domain/ folder must stay infrastructure-free: no EF Core attributes, no HTTP types, no Polly.

Testing

Test each slice independently. Use WebApplicationFactory for full-stack slice tests.

public class CreateOrderTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    [Fact]
    public async Task CreateOrder_ValidRequest_ReturnsCreated()
    {
        var client = factory.CreateClient();
        var request = new CreateOrderRequest(Guid.NewGuid(), [new(Guid.NewGuid(), 2)]);

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

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

For handler-only tests, instantiate the handler directly with a DbContext pointed at a Testcontainers database (see skills/testing-dotnet/SKILL.md). Don't mock DbContext or use the EF in-memory provider — it skips constraints, transactions and SQL translation, so tests pass against behaviour production doesn't have.

Do / Don't

See Also

• knowledge/decisions/adr-001-vsa-default.md — why VSA is the default for new APIs
• knowledge/decisions/adr-005-multi-architecture.md — when to choose Clean Architecture or DDD instead
• knowledge/common-infrastructure.md — IEndpointGroup interface definition and bootstrap