Vertical Slice Architecture (VSA)
Core Principles
- Organize by feature, not by layer — Each feature is a self-contained vertical slice containing its endpoint, handler, request/response types, and validation. No more jumping between Controllers/, Services/, Repositories/ folders.
- Minimize cross-feature coupling — Features should not reference each other directly. Shared concerns go in a
Common/orShared/directory. - One file per feature is fine — A simple CRUD endpoint doesn't need 5 files spread across layers. Start with everything in one file, extract only when complexity demands it.
- The handler is the unit of work — Each handler does one thing. No god-services with 20 methods.
Patterns
Feature Folder Structure
Pattern A: Mediator Handlers (Recommended Default)
Source-generated mediator — MIT licensed, no reflection, Native AOT compatible. Uses IRequest<T> / IRequestHandler<TRequest, TResponse> with pipeline behaviors. Near-identical API to MediatR but faster and free. Package: Mediator.Abstractions + Mediator.SourceGenerator.
Pattern B: Wolverine Handlers
Convention-based — no interfaces to implement. Wolverine discovers handlers by method signature.
Pattern C: Raw Handler Classes (No Library)
Direct handler classes with no external dependency. Good for small projects or teams that want full control.
Adding Module Boundaries (Optional)
For larger applications that grow beyond a single project, introduce module boundaries. Each module is a separate class library with its own features and DbContext.
Modules communicate via:
- Integration events (preferred) — async, decoupled via Wolverine or MassTransit
- Shared contracts — a
MyApp.Contractsproject with DTOs/interfaces (use sparingly)
Shared Concerns
Cross-cutting concerns live outside feature folders:


