Clean architecture

Clean architecture, popularised by Robert C. Martin, builds on earlier models such as hexagonal architecture (ports and adapters) and onion architecture. Its single governing principle is the dependency rule: source code dependencies may only point inward, toward higher-level policy. An inner layer never knows the name of an outer one.

The layers, from the centre outward, are typically:

• Entities — enterprise-wide business rules and core domain objects, the most stable part of the system.
• Use cases — application-specific business rules that orchestrate entities to fulfil a given operation.
• Interface adapters — controllers, presenters and gateways that convert data between the use cases and external formats.
• Frameworks and drivers — the web framework, database, UI and third-party tools, kept at the outermost edge.

Crossing inward over a boundary is done through interfaces (abstractions) defined by the inner layer and implemented by the outer one. This dependency inversion is what lets a database engine, an API client or even the entire web framework be swapped without touching the domain.

Traditional layered (n-tier) or MVC applications often let the domain depend on the framework and the persistence layer, which couples business rules to technical choices. Clean architecture inverts that direction.

The trade-off is upfront effort: more interfaces, mapping between layers and boilerplate. For short-lived or trivial projects this overhead is rarely justified; for long-lived business platforms it pays back in maintainability.

The practical benefit of clean architecture is that the parts most likely to change — UI, frameworks, databases, external services — are kept furthest from the parts that change least: the business rules. This separation produces several concrete advantages:

• Independent testing — use cases can be exercised with in-memory test doubles, without spinning up a database or HTTP server.
• Technology flexibility — migrating from one database or framework version to another affects adapters, not the domain.
• Clear boundaries — each layer has a defined responsibility, which limits the blast radius of a change.
• Longevity — business logic survives the inevitable churn of front-end and infrastructure choices.

Clean architecture is most relevant for systems with substantial, durable business logic: ERP, CRM, billing engines and other platforms expected to evolve over years. For prototypes or thin CRUD interfaces, a lighter layered approach is usually a more proportionate choice.