Clean Architecture is a widely used way to structure long-lived .NET applications. It keeps your business logic independent of frameworks, databases, and UI, which pays off as the system grows. But the ideas span dozens of topics: layers, the dependency rule, CQRS, cross-cutting concerns, testing, domain modeling. This guide pulls them all together, from the fundamentals to the patterns you'll use in production.
What is Clean Architecture?
Clean Architecture is a software design philosophy that separates the elements of a design into ring levels. The key rule is that dependencies can only point inward - outer layers can depend on inner layers, but not vice versa.
In .NET, this typically means organizing your solution into layers like Domain, Application, Infrastructure, and Presentation. Each layer has a clear responsibility, and the dependency rule ensures your business logic stays independent of frameworks, databases, and UI concerns.
This guide brings together everything you need to master Clean Architecture in .NET.
Want to go deeper? My Pragmatic Clean Architecture course teaches the complete system I use to ship production-ready applications.
Getting Started
These articles cover the foundational concepts. If you're new to Clean Architecture, start here to understand the "why" before diving into implementation details.
- Clean Architecture and the Benefits of Structured Software Design
- Clean Architecture Folder Structure
- Building Your First Use Case with Clean Architecture
- A Clean Architecture Solution Template for .NET
- Clean Architecture with Minimal APIs
Core Concepts
Once you understand the basics, these articles explore the principles that make Clean Architecture effective in real-world projects - from handling complexity to managing cross-cutting concerns.
- Why Clean Architecture Is Great for Complex Projects
- Clean Architecture: The Missing Chapter
- Balancing Cross-Cutting Concerns in Clean Architecture
- Getting the Current User in Clean Architecture
- Clean Architecture Anti-Patterns and Common Mistakes
- Clean Architecture vs Onion vs Hexagonal Architecture
- When to Use Clean Architecture (And When Not To)
- The Dependency Rule in Clean Architecture
The Layers
Clean Architecture is built from four layers, each with a distinct responsibility. These guides go layer by layer, covering what belongs where and how the pieces map onto each other.
- The Domain Layer in Clean Architecture
- The Application Layer in Clean Architecture
- The Infrastructure Layer in Clean Architecture
- Mapping Between Layers in Clean Architecture
- Organizing Use Cases in Clean Architecture
CQRS and MediatR
The CQRS pattern is a natural complement to Clean Architecture. It separates read and write operations, keeping your use cases focused and testable.
- CQRS Pattern with MediatR
- CQRS Pattern: The Way It Should Have Been From the Start
- Stop Conflating CQRS and MediatR
- CQRS Validation with MediatR Pipeline and FluentValidation
- MediatR Pipeline Behaviors in .NET
Cross-Cutting Concerns
Clean Architecture gives cross-cutting concerns a clear home instead of letting them leak across layers. These guides cover concerns that appear in many production applications.
- Exception Handling in Clean Architecture
- Logging Strategy in Clean Architecture
- Authentication and Authorization in Clean Architecture
- Caching in Clean Architecture
- Background Jobs in Clean Architecture
- Transactions in Clean Architecture
Testing
A well-structured Clean Architecture solution is inherently testable. These guides cover testing strategies at different levels.
- Unit Testing Clean Architecture Use Cases
- Enforcing Software Architecture with Architecture Tests
- 5 Architecture Tests You Should Add to Your .NET Projects
Domain-Driven Design
Clean Architecture provides the structure, and DDD provides the modeling techniques. These articles cover the DDD fundamentals you'll use inside the Domain layer.
- Value Objects in .NET: DDD Fundamentals
- How to Use Domain Events to Build Loosely Coupled Systems
- Refactoring From an Anemic Domain Model to a Rich Domain Model
- From Transaction Scripts to Domain Models: A Refactoring Journey
Related Architectures
Clean Architecture isn't the only option. These complementary approaches can be used alongside it or as alternatives depending on your project's needs.
Summary
Clean Architecture organizes a .NET solution into Domain, Application, Infrastructure, and Presentation layers, with dependencies pointing only inward. The structure pays off in long-lived applications with real business rules; for prototypes and simple CRUD systems, the extra projects and abstractions can cost more than the independence they provide. Start with the fundamentals, work through the layers, then add CQRS, cross-cutting concerns, and architecture tests as your system grows.
Frequently Asked Questions
What are the layers of Clean Architecture in .NET?
A typical .NET solution has Domain, Application, Infrastructure, and Presentation layers. Domain owns business rules, Application coordinates use cases, Infrastructure implements external integrations, and Presentation translates transport input and output.
What is the dependency rule in Clean Architecture?
Source-code dependencies point inward. Domain depends on no outer layer, Application can depend on Domain, and Infrastructure and Presentation depend on abstractions owned by the inner layers. The runtime call direction can differ; the compile-time dependency direction may not.
Does Clean Architecture require CQRS or MediatR?
No. CQRS and MediatR can help organize use cases and cross-cutting behavior, but neither defines Clean Architecture. You can use application services or your own command and query handler interfaces while preserving the same dependency boundaries.
How many projects should a Clean Architecture solution have?
Use enough projects to enforce meaningful dependency boundaries, commonly four for Domain, Application, Infrastructure, and the API. A small application can combine outer layers or begin as one feature-oriented project and extract boundaries when the complexity justifies them.
When is Clean Architecture a poor fit?
It is usually a poor fit for prototypes, short-lived applications, and simple CRUD systems with little business logic. In those cases the extra projects, mapping, and abstractions can cost more than the independence they provide.
