Definition of clean architecture
Clean architecture is a model for organising the code of an application. Robert C. Martin presented it in a post on his blog (blog.cleancoder.com), “The Clean Architecture”, dated 13 August 2012. The author later published a book bearing this title; this entry is based on the blog post.
The post presents itself as a synthesis. It starts from several related models, including Alistair Cockburn’s hexagonal architecture and Jeffrey Palermo’s “Onion Architecture”, and observes that they pursue the same goal, separation of concerns, by the same means: division into layers, with at least one layer for business rules and another for interfaces. The diagram of concentric circles that opens the post attempts to unite them into a single idea.
The properties the model seeks
The post lists what these architectures have in common. A system built this way does not depend on a framework, which it uses as a tool. Its business rules can be tested without the interface, without the database and without the web server. The interface can change without touching the rest, the database can be replaced, and the business rules know nothing about the outside world.
Its conclusion draws a consequence: an external element that has become obsolete, a database or a web framework, can be replaced at lower cost. This is a way of containing obsolescence, one of the forms of technical debt.
The dependency rule and the circles of the diagram
The dependency rule is stated as follows: source code dependencies can only point inwards. The code of an inner circle mentions no name declared in an outer circle, and does not use its data formats.
| Circle, from the centre outwards | Content according to the post |
|---|---|
| Entities | Business rules valid for the whole enterprise or, for a standalone application, its business objects |
| Use cases | Application-specific rules, which orchestrate exchanges with the entities |
| Interface adapters | Conversion of data between the form useful to the use cases and that of an external agent; SQL code is confined here |
| Frameworks and drivers | Database, web framework: details, kept on the outside |
Sometimes a use case needs to call an outer element, for example to present a result. The post answers this with the dependency inversion principle: the use case calls an interface declared in its own circle, which the outer element implements. The data that crosses a boundary consists of simple structures, never an entity or a database row.
Clean architecture, classic layers and tooling: not to be confused
Clean architecture is neither a framework nor a tool. It prescribes no technology, since it places technologies in the outer circle.
It differs from a stack in which the business layer relies on the data access layer. Here, the direction is reversed: the database-related code depends on the business rules.
It is not a synonym for hexagonal architecture, whose entry describes ports and adapters. Both separate the business from the technical. Martin’s text additionally specifies the internal order, entities then use cases, and formulates a single rule for all circles.
The number of circles is not fixed: the author describes his diagram as schematic.
A textbook case: approving an expense claim
Take an expense claims application. An “expense claim” entity carries the rules valid throughout the company, such as the ceiling per type of expense. An “approve a claim” use case chains the steps: load the claim, apply the rules, record the decision.
To load and save, the use case declares a repository interface in its own circle. One adapter implements it with the company’s database, another with an in-memory list for tests. The day the database changes, the use case and the entity are not modified.
This division has a cost: additional interfaces and conversions, which may seem disproportionate when there are few business rules.
Whether to adopt it is assessed application by application, within the framework set by IT architecture, and is reflected in the code during custom software development.