Clean Architecture

The idea in one minute

Clean Architecture puts the code that encodes business rules at the centre and pushes everything that is a delivery or storage detail to the edge: UI, database, file formats, devices, frameworks, network protocols.

The centre does not know the edge exists. It defines interfaces (ports) for what it needs; outer code implements them (adapters). You can replace the database, the UI technology or a device protocol without touching the rules, and you can test the rules without any of those in place.

When it fits

The dependency rule

There is exactly one hard rule: source-code dependencies point only inwards. Nothing in an inner ring may name anything in an outer ring — no class, function, framework type or data format.

The rings are ordered by how often and why they change — stable policy inside, volatile detail outside. It is the Stable Dependencies Principle applied to a whole system.

Crossing a boundary

Control flows outward-in and back out (UI → use case → UI), yet source dependencies may only point inwards. Dependency inversion solves this: the use case declares an interface, and the outer ring implements it.

Data crossing a boundary should be plain structures — request and response models, DTOs — never ORM rows, HTTP requests or framework objects. Many teams drop the separate Presenter and return a response object from the use case; that is a common, acceptable simplification.

Vocabulary

The Czech column gives the usual technical translation.

Martin’s rings vs. the 4-project template

Most .NET material — including many beginner articles^[4] — describes the community template popularised by Jason Taylor and Steve Smith (Ardalis), not Martin’s book directly. The mapping:

The template brings choices Martin never required — CQRS, MediatR, one project per layer, mapping libraries. When someone says “we use Clean Architecture”, ask which of these they mean.

Worked example: a configuration tool

An illustrative C# sketch of a device-parameter configuration tool that validates a configuration against rules and writes it to a device. The project references alone already enforce the dependency rule:

src/
  ConfigTool.Domain/            // no project references at all
  ConfigTool.Application/       // → Domain
  ConfigTool.Infrastructure/    // → Application (implements its ports)
  ConfigTool.Desktop/           // WPF/MVVM → Application; composition root also → Infrastructure
tests/
  ConfigTool.Domain.Tests/      // pure unit tests, no mocks needed
  ConfigTool.Application.Tests/ // use cases with in-memory fakes / simulated device
  ConfigTool.ArchitectureTests/ // enforce the dependency rule

Domain — entities and rules, no I/O:

public sealed class DeviceConfiguration
{
    public ConfigId Id { get; }
    public DeviceModel Model { get; }
    private readonly Dictionary<ParameterKey, ParameterValue> _values = new();

    public void Set(ParameterKey key, ParameterValue value)
    {
        var def = Model.Definition(key);   // throws if the model has no such parameter
        def.EnsureInRange(value);          // invariant lives with the data
        _values[key] = value;
    }

    public ValidationResult Validate(IEnumerable<IConfigRule> rules) =>
        ValidationResult.Combine(rules.Select(r => r.Check(this)));
}

Application — one use case and the ports it owns:

public interface IConfigurationRepository { Task<DeviceConfiguration?> Load(ConfigId id); }
public interface IRuleCatalog { IReadOnlyList<IConfigRule> For(DeviceModel model); }
public interface IDeviceGateway { Task Write(DeviceAddress target, ConfigImage image); }

public sealed class DeployConfiguration(
    IConfigurationRepository repo, IRuleCatalog rules, IDeviceGateway device)
{
    public async Task<DeployResult> Handle(DeployRequest req)
    {
        var cfg = await repo.Load(req.ConfigId);
        if (cfg is null) return DeployResult.NotFound(req.ConfigId);

        var check = cfg.Validate(rules.For(cfg.Model));
        if (!check.IsValid) return DeployResult.Invalid(check.Errors);

        await device.Write(req.Target, ConfigImage.From(cfg));
        return DeployResult.Ok();
    }
}

Infrastructure — adapters, swappable per technology:

public sealed class CanOpenDeviceGateway(ICanBus bus) : IDeviceGateway { /* SDO writes… */ }
public sealed class SimulatedDeviceGateway : IDeviceGateway { /* tests, demos, CI */ }
public sealed class JsonFileConfigurationRepository : IConfigurationRepository { /* … */ }
public sealed class YamlRuleCatalog : IRuleCatalog { /* rules as data */ }

Where it is used in practice

Few companies publish “we use Clean Architecture” verbatim. The ideas show up as hexagonal designs, official platform guidance and widely used templates.

• Google — Android app architecture guide. Recommends UI and data layers plus an optional domain layer of use cases for complex or shared logic — a deliberately softened Clean Architecture that warns against layers you don’t need.^[6]
• Microsoft — “Common web application architectures”. The .NET architecture e-book presents Clean Architecture (with Onion and Hexagonal) as the recommended structure for domain-heavy ASP.NET Core apps; the eShopOnWeb reference app follows it.^[7]
• Netflix Studio Workflows (hexagonal). A studio-production app pulled data from many services over gRPC, JSON API and GraphQL that kept moving. A hexagonal core of entities, repositories and interactors let them swap data sources without touching business logic.^[5]
• AWS Prescriptive Guidance. Uses ports and adapters to keep domain logic independent of AWS services.^[8]
• Jason Taylor and Ardalis templates (.NET). The two most-used starting points and the origin of the 4-layer structure. Ardalis now also ships a minimal, single-project variant organised by vertical slices — a hint where the community is heading.^[10][11]
• Embedded — “Clean Embedded Architecture” (James Grenning, chapter 29 of Martin’s book). Hardware and OS abstraction layers so logic can be tested off-target.

Gains and costs

Martin himself says full boundaries are often too expensive and suggests partial boundaries where full ones aren’t justified. Pragmatism about layers is consistent with the source.^[1]

How it goes wrong

1. Folders, not boundaries. The four project names exist, but Domain references EF Core and Application references HTTP types. Nothing enforces the rule.
2. Anaemic domain. Entities are property bags; all logic sits in handlers or services. The centre is empty and the rings only add cost.
3. ORM entity = domain entity. Persistence concerns (lazy loading, nullable keys, navigation properties) leak into the core.
4. A use case per CRUD call. Hundreds of GetXByIdQuery handlers that only forward to a repository. Ceremony without behaviour.
5. Interface for everything. Abstractions with exactly one implementation and no test or variation need behind them.
6. Template cargo cult. MediatR, CQRS, AutoMapper adopted because the template had them, not because a requirement asked.
7. The real complexity is elsewhere. In many systems the hard part is the rule model, schema versioning or import/export; neat layering doesn’t address any of it.

Enforcing it

An architecture that isn’t checked decays within months. Good answers to “how is the rule enforced?”:

• Project or module references that make wrong dependencies fail to compile — the cheapest guard.
• Architecture tests in CI — NetArchTest^[12] or ArchUnitNET (.NET), ArchUnit (Java), dependency-cruiser (TypeScript), import-linter (Python).
• Review checklist and ADRs recording why each boundary exists.

[Fact]
public void Domain_has_no_outward_dependencies()
{
    var result = Types.InAssembly(typeof(DeviceConfiguration).Assembly)
        .ShouldNot()
        .HaveDependencyOnAny("ConfigTool.Application", "ConfigTool.Infrastructure",
                             "Microsoft.EntityFrameworkCore", "System.Windows")
        .GetResult();

    Assert.True(result.IsSuccessful);
}

Relatives and alternatives

Several of these are complementary rather than competing — a system may need Clean Architecture plus a plugin model plus MVVM.

Origins

Robert C. Martin published it in a 2012 blog post^[1] and expanded it in Clean Architecture: A Craftsman’s Guide to Software Structure and Design (2017). He presented it as a synthesis of earlier ideas: