Skip to content
Technology transformation expertise firm · ARDIANE Group Innovate, secure, succeed

Glossary

Clean architecture: definition, dependency rule and circles

Domain

Engineering

In brief

Clean architecture is a model for organising code proposed by Robert C. Martin, which arranges software in concentric circles, from business rules at the centre to technical tools at the edge. It rests on one rule, known as the dependency rule: source code dependencies point only inwards.

Page contents

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.

FAQ

Frequently asked questions

Another question? Ask us

What is clean architecture?

Clean architecture is a model for organising code presented by Robert C. Martin in a blog post dated 13 August 2012. Software is arranged in concentric circles, with business rules at the centre and technical tools on the outside. Source code dependencies go only from the outside inwards.

What does the dependency rule say?

According to Robert C. Martin's blog post, source code dependencies can only point inwards. Nothing in an inner circle knows anything at all about an outer circle: neither the name of a function or class, nor a data format. A change of database or interface should therefore not reach the business rules.

Does clean architecture require four circles?

No. Robert C. Martin writes that the circles in his diagram are schematic and that software may need more of them. The dependency rule, however, applies whatever their number: dependencies point inwards, and the level of abstraction increases as you move towards the centre.

What is the difference between clean architecture and hexagonal architecture?

Alistair Cockburn's hexagonal architecture separates the application from the outside world through ports and adapters. Clean architecture cites it among the models it seeks to unite into a single idea. It adds an order within the application, entities then use cases, and a dependency rule stated for all circles.

A project to bring to completion?

A first conversation is enough to understand your challenge, identify the right people and tell you frankly what we can bring.