Software Engineer

6 minute read

8 min read 1769 words

Clean Architecture, popularized by Robert C. Martin (Uncle Bob), is a software design philosophy that promotes the separation of concerns, making applications independent of frameworks, UI, databases, and external agencies. This post breaks down its core concepts and why it’s a favorite for long-term maintainability.

1. What is Clean Architecture?

At its core, Clean Architecture is about organizing your code into concentric circles (layers) where the innermost circles represent the business logic and the outermost circles represent infrastructure and delivery mechanisms (UI, DB).

The primary goal is to create a system that is:

  • Independent of Frameworks: The architecture doesn’t rely on the existence of some library of feature-laden software.
  • Testable: The business rules can be tested without the UI, Database, Web Server, or any other external element.
  • Independent of UI: The UI can change easily, without changing the rest of the system.
  • Independent of Database: You can swap SQL Server for MongoDB without changing your business rules.

2. Visual Representation (ASCII Diagram)

Think of it as an onion. The dependencies only flow from the outside in. The core (Entities) doesn’t know anything about the database or the web.

          +---------------------------------------+
          |  Frameworks & Drivers (Web, DB, UI)   |  <-- Outer
          |   +-------------------------------+   |
          |   |  Interface Adapters           |   |
          |   |  (Controllers, Repositories)  |   |
          |   |   +-----------------------+   |   |
          |   |   |  Use Cases            |   |   |
          |   |   |  (Application Logic)  |   |   |
          |   |   |   +---------------+   |   |   |
          |   |   |   |   Entities    |   |   |   |  <-- Core
          |   |   |   |   (Domain)    |   |   |   |
          |   |   |   +---------------+   |   |   |
          |   |   +-----------------------+   |   |
          |   +-------------------------------+   |
          +---------------------------------------+
                    (Dependencies point INWARD)

3. The Dependency Rule

The most important rule in Clean Architecture is the Dependency Rule:

Dependencies must only point inwards.

Code in an inner circle cannot know anything about code in an outer circle. For example, your Domain entities should never reference a class from the Infrastructure or Web project.

4. The Four Layers

While you can have many layers, the standard Clean Architecture usually consists of four main ones:

1. Entities (The Domain)

The innermost circle. It contains the business objects of the application. These are the most stable parts of your system and should change only when the fundamental business rules change.

  • Contents: Domain Entities, Value Objects, Domain Exceptions.

2. Use Cases (Application Layer)

This layer contains the application-specific business rules. It coordinates the flow of data to and from the entities.

  • Contents: Application Services, Use Case Interfaces, Request/Response DTOs.
  • Rule: It depends only on the Entities layer.

3. Interface Adapters (Infrastructure/Presentation)

This layer contains the “translators” between the external world (DB, Web) and the Use Cases.

  • Contents: Controllers (Web API), Presenters, Gateways (Repository Implementations).
  • Rule: It depends on both Use Cases and Entities.

4. Frameworks & Drivers (External)

The outermost layer. It consists of tools like the database, web framework, or any third-party libraries.

  • Contents: ASP.NET Core Framework, Entity Framework Core, SQL Server, Identity Providers.

5. Simple Implementation Example

In Clean Architecture, we use interfaces to keep the core independent of details like the database.

1. Entities Layer (Core)

public class User 
{
    public int Id { get; init; } // Using init-only properties for immutability
    public string Name { get; set; } = string.Empty;
}

2. Use Cases Layer (Application)

// The interface is defined in the Application layer, following Dependency Inversion
public interface IUserRepository 
{
    Task<User?> GetByIdAsync(int id, CancellationToken ct = default);
}

// Use Cases (Application Services) coordinate business logic
public class GetUserUseCase
{
    private readonly IUserRepository _repository;
    public GetUserUseCase(IUserRepository repository) 
    {
        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
    }

    public async Task<string> ExecuteAsync(int id, CancellationToken ct = default) 
    {
        var user = await _repository.GetByIdAsync(id, ct);
        return user?.Name.ToUpperInvariant() ?? "NOT FOUND";
    }
}

3. Infrastructure Layer (Outer)

// Implementation of the interface lives in the outer layer (Details)
public class SqlUserRepository : IUserRepository
{
    public async Task<User?> GetByIdAsync(int id, CancellationToken ct = default) 
    {
        // Real database logic (EF Core, Dapper, etc.) would go here
        await Task.Delay(10, ct); // Simulating DB call
        return new User { Id = id, Name = "John Doe" };
    }
}

4. Presentation Layer (Outer)

// Controllers or UI components depend only on Use Cases
public class UserController
{
    private readonly GetUserUseCase _useCase;
    public UserController(GetUserUseCase useCase) => _useCase = useCase;

    public async Task Get(int id) 
    {
        var result = await _useCase.ExecuteAsync(id);
        Console.WriteLine(result);
    }
}

6. Important Aspects to Know

Testability

Because the business logic is decoupled from external dependencies, you can write fast, reliable unit tests for your Use Cases and Entities using mocks for the interfaces defined in the inner layers.

Abstraction over Implementation

Clean Architecture heavily relies on the Dependency Inversion Principle (D from SOLID). You define interfaces in the inner layers (e.g., IUserRepository in Use Cases) and implement them in the outer layers (e.g., UserRepository in Infrastructure).

Separation of Concerns

Each layer has a distinct responsibility. This prevents the “Big Ball of Mud” where business logic is scattered across UI event handlers or SQL stored procedures.

7. Comparison: Clean Architecture vs. N-Tier

Feature N-Tier (Traditional Layered) Clean Architecture
Dependency Top-down (UI -> Logic -> Data). Inward (Outer -> Inner Core).
Center of World The Database. The Domain/Business Logic.
Flexibility Harder to swap DB or UI. Extremely flexible.
Complexity Simple for small apps. High boilerplate for small apps.

In N-Tier, if the database schema changes, it often ripples all the way up to the UI. In Clean Architecture, the core is protected from such changes.

8. Pros and Cons

Pros

  • Maintainability: Code is easy to find, fix, and extend.
  • Scalability: Teams can work on different layers simultaneously with minimal conflicts.
  • Durability: The core business logic survives even if you migrate from ASP.NET MVC to Blazor or from SQL to NoSQL.

Cons

  • Complexity: It requires more projects, interfaces, and mapping (AutoMapper) between layers.
  • Learning Curve: Developers need to understand the principles to avoid breaking the dependency rule.
  • Over-Engineering: For simple CRUD applications, it can be “too much” and slow down initial development.

9. Why People Love and Hate Clean Architecture

Why People Love It ❤️

  • Testability is King: You can test 90% of your business logic without ever touching a database or a UI. Tests run in milliseconds and are extremely reliable.
  • Zero Infrastructure Leakage: Your core business logic doesn’t know (or care) if you use SQL Server, MongoDB, or a JSON file. This makes your “brain” code incredibly clean.
  • Independence from UI: You can easily switch from a Web API to a Console App or a Mobile App because the logic is entirely separate from the delivery mechanism.
  • “Screaming” Architecture: When you look at the project, you see UseCases like PlaceOrder or CancelSubscription instead of generic Services or Repositories.

Why People Hate It 💔

  • “Mapping Hell”: Because layers are strictly separated, you often have to convert an Entity to a Domain Model, then to a DTO, then to a ViewModel. It’s a lot of repetitive code.
  • Too Much Boilerplate: For a simple “Hello World” or a basic CRUD app, Clean Architecture feels like over-engineering. You’ll spend more time creating folders and interfaces than writing logic.
  • Indirection Overload: It can be hard to follow the code’s path because everything is hidden behind an interface. You’ll find yourself clicking “Go to Implementation” a lot.
  • Steep Learning Curve: It takes a while for a team to “click” with the principles. If done incorrectly, it can lead to a mess that’s worse than N-Tier.

10. References & Further Reading

C# Interview Series

Leave a comment

You may also enjoy