Getting Started with Clean Architecture in .NET

Clean Architecture has become one of my go-to patterns when building enterprise applications. After implementing it across various projects in automotive, fintech, and healthcare industries, I’ve gathered some practical insights I want to share.

What is Clean Architecture?

Clean Architecture, popularized by Robert C. Martin (Uncle Bob), is about organizing code in a way that makes your business logic independent of frameworks, databases, and external services. The core principle is the Dependency Rule: source code dependencies must point only inward, toward higher-level policies.

The Four Layers

Here’s how I typically structure my .NET projects:

1. Domain Layer (Core)

This is where your business entities and rules live:

public class Order
{
    public Guid Id { get; private set; }
    public string CustomerId { get; private set; }
    public List<OrderItem> Items { get; private set; }
    public OrderStatus Status { get; private set; }

    public void AddItem(Product product, int quantity)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Cannot modify a submitted order");
        
        Items.Add(new OrderItem(product, quantity));
    }
}

2. Application Layer

Contains use cases and application-specific business rules:

public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, OrderDto>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;

    public async Task<OrderDto> Handle(CreateOrderCommand request, CancellationToken ct)
    {
        var order = new Order(request.CustomerId);
        
        foreach (var item in request.Items)
        {
            order.AddItem(item.Product, item.Quantity);
        }
        
        await _orderRepository.AddAsync(order, ct);
        await _unitOfWork.SaveChangesAsync(ct);
        
        return order.ToDto();
    }
}

3. Infrastructure Layer

Implements interfaces defined in the Application layer:

public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
    {
        return await _context.Orders
            .Include(o => o.Items)
            .FirstOrDefaultAsync(o => o.Id == id, ct);
    }
}

4. Presentation Layer

Your API controllers or UI components:

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;

    [HttpPost]
    public async Task<ActionResult<OrderDto>> Create(CreateOrderCommand command)
    {
        var result = await _mediator.Send(command);
        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
    }
}

Why I Use It

After years of working with various architectures, here’s why Clean Architecture works for me:

1. Testability: Business logic is isolated and easy to unit test
2. Flexibility: Swap databases or frameworks without touching core logic
3. Maintainability: Clear separation makes code easier to understand
4. Team scalability: Different teams can work on different layers

When to Use It

Clean Architecture isn’t always necessary. For simple CRUD applications, it might be overkill. But for complex business domains with:

• Multiple integrations
• Complex business rules
• Long-term maintenance needs
• Team collaboration requirements

It’s absolutely worth the initial setup investment.

Conclusion

Clean Architecture has helped me build more maintainable systems across various industries. The initial learning curve is worth it when you see how easy it becomes to adapt to changing requirements.

In future posts, I’ll dive deeper into specific patterns like CQRS with MediatR and how to handle cross-cutting concerns. Stay tuned!