dotnet-clean-architecture

When to activate

• Scaffolding a new .NET / ASP.NET Core project
• "How do I structure this feature?" in a C# context
• Writing a Command, Query, Handler, or Domain Event
• Designing entities, aggregates, or value objects
• Configuring dependency injection or DbContext
• Refactoring a "fat controller" or a service with too many responsibilities
• Any mention of MediatR, FluentValidation, EF Core architecture

Solution Structure

Always enforce this 4-layer structure. Dependencies flow inward only.

src/
├── YourApp.Domain/           # Zero external dependencies
│   ├── Entities/
│   ├── ValueObjects/
│   ├── Events/
│   └── Interfaces/
│
├── YourApp.Application/      # Depends only on Domain
│   ├── Features/
│   │   └── Orders/
│   │       ├── Commands/CreateOrder/
│   │       │   ├── CreateOrderCommand.cs
│   │       │   ├── CreateOrderCommandHandler.cs
│   │       │   ├── CreateOrderCommandValidator.cs
│   │       │   └── CreateOrderResponse.cs
│   │       └── Queries/GetOrderById/
│   │           ├── GetOrderByIdQuery.cs
│   │           └── GetOrderByIdQueryHandler.cs
│   ├── Common/
│   └── DependencyInjection.cs
│
├── YourApp.Infrastructure/   # Depends on Application + Domain
│   ├── Persistence/
│   ├── Services/
│   └── DependencyInjection.cs
│
└── YourApp.API/              # Depends on Application + Infrastructure
    ├── Controllers/
    ├── Middleware/
    └── Program.cs

Non-negotiable Rules

1. Domain has zero external dependencies. No EF Core, no MediatR, no HTTP.
2. Application depends only on Domain. Never reference Infrastructure from Application.
3. One Handler per Command/Query. No shared handlers.
4. Controllers are thin. Receive → mediator → return. Nothing else.
5. IRepository in Domain. Implementation in Infrastructure.
6. No business logic in Controllers or Infrastructure.

CQRS Pattern

Licensing — check before adopting. MediatR changed license in v13.0.0: its release notes state "moving from Apache license to dual commercial/OSS license" and "requiring license key". v12.5.0 and earlier are Apache-2.0. From v13 the key is set with cfg.LicenseKey, or through the MEDIATR_LICENSE_KEY / LUCKYPENNY_LICENSE_KEY environment variables; running without one logs a warning. Confirm procurement approval before adding it to a regulated project. The patterns below — one handler per command, pipeline behaviors, thin controllers — do not depend on MediatR specifically, so an in-process dispatcher you own is a valid substitute.