20 practical guides
Start with the dependency rule and the responsibilities of each layer. Then work through the decisions a real .NET application needs: organizing use cases, handling transactions, adding authentication, and keeping infrastructure out of the domain model.
Start here
A practical map of Clean Architecture in .NET: dependency direction, layer responsibilities, use-case organization, cross-cutting concerns, and the tradeoffs that tell you when the structure is worth its cost.
Read the complete guide →Authentication is infrastructure, authorization is a business rule, and confusing the two is how ASP.NET Core leaks into your domain. Here is where JWT validation, the ICurrentUserService abstraction, permission checks, and ownership rules each live, and how to keep them enforced beyond HTTP endpoints.
Where do background jobs fit in Clean Architecture? Treat them as entry points, exactly like controllers. The job schedules and triggers, the application layer does the work. Here is the structure, the scoped-service wiring that trips everyone up, and complete examples with BackgroundService and Quartz.
Setting up a Clean Architecture project from scratch takes time. Here is a complete .NET solution template with the right project structure, references, and configurations.
Clean Architecture, Onion Architecture, and Hexagonal Architecture all solve the same fundamental problem: decoupling business logic from infrastructure. But they differ in structure, naming, and emphasis. Here is a practical comparison to help you choose.
Minimal API endpoints and Clean Architecture are a natural fit: the endpoint receives HTTP, dispatches a command, and maps the result back. No business logic, no controllers, no ceremony. Here is how to organize endpoints by feature, validate with endpoint filters, and return consistent Problem Details.
Source code dependencies must only point inward. That one sentence decides your project references, where your interfaces live, and why the DI container sits at the edge. Here is how the Dependency Rule works, how control can flow outward while dependencies point inward, and how to enforce it with the compiler and architecture tests.
A domain event is handled in-process, inside the same transaction. An integration event crosses service boundaries through a message broker and needs the outbox pattern to survive a crash. Confusing the two leads to lost events and accidental coupling. Here is where the line sits, with implementation patterns for both sides.
Expected failures are not exceptional, so stop throwing them. A clear strategy gives each layer one job: the domain throws on invariant violations, the application returns typed Results, and a single global handler maps everything else to Problem Details. Here is how the pieces fit together in a .NET Clean Architecture.
A folder structure that works at 5 use cases falls apart at 200. Group by feature, keep one use case per folder, and name with verb-noun domain language, and your Application layer reads like a list of things the system can do. Here are the three layouts you will encounter, and why only one of them scales.
One pipeline behavior can log every use case with timing and failures, so handlers stay clean and the domain never sees an ILogger. Here is a layer-by-layer logging strategy for Clean Architecture: domain events instead of logs in the domain, behaviors in the application, direct logging in infrastructure, and middleware at the edge.
Request to command, command to entity, entity to response: a single operation can pass through three mappings, and most of them are ceremony. EF Core projections eliminate the read-side mapping entirely, and simple extension methods handle the rest. Here is when mapping between layers earns its keep, and why you rarely need AutoMapper.
MediatR pipeline behaviors let you handle logging, validation, caching, and transactions without touching your handlers. Here are four practical IPipelineBehavior implementations you can use today.
The Application layer is where your use cases live: commands, queries, and the handlers that orchestrate your domain objects. A good handler reads like a table of contents (load, act, save). Here is how to structure the layer in .NET and keep business logic from leaking into it.
Every business rule in your system should have exactly one home: the Domain layer. That means entities that guard their invariants, value objects instead of raw primitives, and domain events for side effects. Here is what belongs in the Domain layer, what does not, and how to keep it at zero external dependencies.
Databases, message brokers, email providers, caches: everything that talks to the outside world lives in the Infrastructure layer. It implements the interfaces your inner layers define, and it is the only place EF Core should ever appear. Here is how to structure it in .NET, from repositories and the DbContext to a clean DI registration module.
A five-endpoint CRUD API with four projects, domain events, and a CQRS pipeline is over-engineering, not discipline. Clean Architecture pays off on complex domains, long-lived codebases, and multi-team projects. Here is a decision framework for spotting which one you have, and a migration path for when you guess wrong.
The use case defines what must succeed or fail together, so the transaction boundary belongs to the application layer. Here are three ways to implement that in .NET, ranked: a single SaveChanges as the implicit boundary, a unit of work abstraction, and a transaction pipeline behavior.
Caching is infrastructure, but the decision to cache is application-level. Get that split wrong and cache concerns leak into your use cases, or worse, into your domain. Here are two clean approaches: a decorator over your repositories and a pipeline behavior driven by the use case itself.
A practical map of Clean Architecture in .NET: dependency direction, layer responsibilities, use-case organization, cross-cutting concerns, and the tradeoffs that tell you when the structure is worth its cost.
Clean Architecture is powerful when applied correctly, but easy to get wrong. Here are the most common anti-patterns and mistakes I see in .NET projects - and how to fix them.
