Clean Architecture in C# — A Practical Guide for Software Engineers

Author: Romaan, Last Updated: June 13, 2025, 6:47 a.m.
Tags:

"The only way to go fast is to go well." — Robert C. Martin

As your .NET project grows, so does its complexity. Features that once took hours start taking days. Bugs appear in places you didn’t touch. Code becomes fragile and hard to test.

Clean Architecture is a proven approach to design backend systems that are modular, testable, and scalable — without being locked into frameworks like ASP.NET, EF Core, or any specific infrastructure.

What is Clean Architecture?

Clean Architecture is a layered approach where your business rules live at the center, and all other concerns (web, database, frameworks) sit in outer layers.

Inner layers are stable and independent of external technologies
Outer layers can change without affecting the core
Dependencies always point inward

Diagram: Clean Architecture

        +--------------------------+
        |  Frameworks & Drivers   | ← ASP.NET, EF Core, APIs, UI
        +--------------------------+
                    ↓
        +--------------------------+
        |    Interface Adapters    | ← Controllers, ViewModels, Repositories
        +--------------------------+
                    ↓
        +--------------------------+
        |   Application Services   | ← Use Cases / Business Workflows
        +--------------------------+
                    ↓
        +--------------------------+
        |     Domain Entities      | ← Pure Business Logic & Rules
        +--------------------------+

Layer-by-Layer in C#

1. Domain Layer

Contains the core business models and logic. It has no dependencies.

public class Invoice
{
    public Guid Id { get; set; }
    public decimal Amount { get; set; }

    public void ApplyDiscount(decimal percent)
    {
        if (percent < 0 || percent > 1)
            throw new ArgumentException("Invalid discount percent.");

        Amount -= Amount * percent;
    }
}

2. Application Layer (Use Cases)

Implements specific application workflows. Calls entities and delegates persistence to interfaces.

public interface IInvoiceRepository
{
    Task GetByIdAsync(Guid id);
    Task SaveAsync(Invoice invoice);
}

public class InvoiceService
{
    private readonly IInvoiceRepository _repository;

    public InvoiceService(IInvoiceRepository repository)
    {
        _repository = repository;
    }

    public async Task ApplyEndOfYearDiscount(Guid invoiceId)
    {
        var invoice = await _repository.GetByIdAsync(invoiceId);
        invoice.ApplyDiscount(0.1m); // 10% off
        await _repository.SaveAsync(invoice);
    }
}

3. Interface Adapters

Implements the interfaces defined by the application layer.

public class EfInvoiceRepository : IInvoiceRepository
{
    private readonly AppDbContext _db;

    public EfInvoiceRepository(AppDbContext db)
    {
        _db = db;
    }

    public async Task GetByIdAsync(Guid id)
    {
        return await _db.Invoices.FindAsync(id);
    }

    public async Task SaveAsync(Invoice invoice)
    {
        _db.Invoices.Update(invoice);
        await _db.SaveChangesAsync();
    }
}

4. Framework Layer

Wires up everything using Dependency Injection and Web APIs.

[ApiController]
[Route("api/[controller]")]
public class InvoicesController : ControllerBase
{
    private readonly InvoiceService _service;

    public InvoicesController(InvoiceService service)
    {
        _service = service;
    }

    [HttpPost("{id}/apply-discount")]
    public async Task ApplyDiscount(Guid id)
    {
        await _service.ApplyEndOfYearDiscount(id);
        return Ok();
    }
}

The Dependency Rule

Outer layers depend on inner layers. Never the other way around.

This is enforced using interfaces and constructor injection.

Real-World .NET Example

Layer	Example Classes
Domain Entities	Invoice, Product, Customer
Application Services	InvoiceService, OrderHandler
Interface Adapters	EfInvoiceRepository, InvoiceMapper
Frameworks & Drivers	DbContext, Controllers, Program.cs

Unit Testing Use Cases

You can test use cases without web or database setup:

[Fact]
public async Task AppliesDiscountCorrectly()
{
    var repo = new InMemoryInvoiceRepository();
    var service = new InvoiceService(repo);

    var invoiceId = repo.Seed(new Invoice { Amount = 100 });
    await service.ApplyEndOfYearDiscount(invoiceId);

    var updated = await repo.GetByIdAsync(invoiceId);
    Assert.Equal(90, updated.Amount);
}

When Not to Use Clean Architecture

Simple CRUD apps
Small scripts or throwaway tools
Early MVPs prioritizing speed

But it's ideal when:

You want long-term maintainability
Multiple developers or teams are involved
You need business logic isolated and testable

Further Resources

Conclusion

Clean Architecture helps you design decoupled, testable, and flexible systems by isolating business rules from infrastructure and delivery.

If you're working in .NET, especially on enterprise systems or public APIs, investing in Clean Architecture will help you ship features faster with confidence — and avoid the dreaded "rewrite".

RK !