Clean Architecture
Clean Architecture is a way of organizing software so that the most important part — the business rules — stays independent of the details around it: the web framework, the database, the user interface. It was first defined by Robert C. Martin (Uncle Bob) in a 2012 blog post and popularized by his 2017 book of the same name.[1][2] The goal is a system that is easy to test, easy to modify, and where swapping out a framework or database is a small job instead of a rewrite.
Think of a restaurant kitchen. The recipes (the business rules) work exactly the same no matter what brand of stove, pots, or ingredient supplier the kitchen uses. Clean Architecture keeps the recipes in a room that never mentions the equipment — so the equipment can be replaced without touching a single recipe.
Where the idea came from
Uncle Bob did not invent the concept from nothing. He combined earlier, similar ideas:[1]
- Hexagonal Architecture (also called Ports & Adapters, by Alistair Cockburn, 2005) — draws a clear boundary between the core logic of an application and the outside world. Ports are interfaces (contracts) that define how the core talks to the outside; adapters are the implementations of those ports — a database adapter, a web adapter, an external-service adapter. The core has no idea which adapter is currently plugged in.[3]
- Onion Architecture (by Jeffrey Palermo, 2008) — organizes the application into concentric layers with the domain model at the center. The core defines the interfaces; the surrounding infrastructure layers implement them.
- Clean Architecture (2012) — merged these ideas into one model, with four layers and one overriding rule.
The four layers
The software is divided into concentric circles. The further inward you go, the higher-level and more abstract the code becomes (policies and rules). The outer circles are low-level mechanisms (details):
The four concentric circles — the further inward, the higher-level and more abstract the code.[1]
- Entities (innermost) — enterprise-wide business rules: the core objects and rules of the business, the most general and the least likely to change. A change to page navigation or security should never touch this layer.
- Use Cases (also called interactors) — application-specific business rules. They orchestrate the flow of data to and from the entities to achieve a particular goal (e.g. "place order", "cancel booking"). Changes to how the app operates change this layer; changes to the database or UI should not.
- Interface Adapters — the converters. Controllers, presenters, and gateways live here, translating data between the format most convenient for the use cases and the format most convenient for the outside world (web requests, database queries). All SQL lives here — nothing inward knows the database exists.
- Frameworks & Drivers (outermost) — the web framework, the database, the UI toolkit. In Uncle Bob's words: "The web is a detail. The database is a detail." Very little real code lives here beyond glue.
A common shorthand: layers 1–2 are called Domain (or "Business"), layers 3–4 are called Infrastructure.[1]
The Dependency Rule
One rule makes the whole architecture work: source code dependencies can only point inwards. Nothing in an inner circle may know anything at all about something in an outer circle — not even the name of a class or function declared outside it.
That sounds impossible at first — how does a use case display results without calling the outer presenter? The answer is the Inversion of Control trick, normally delivered via Dependency Injection: the use case depends on an interface it defines itself (an output port), and the actual presenter, written in the outer layer, implements that interface. The dependency now points inward (use case → its own interface) while the flow of control runs outward (use case → presenter implementation).
What data may cross the boundaries
The data crossing between layers should be simple data structures — plain DTOs, structs, or function arguments — never database rows and never framework types. A database row structure forced inward would make an inner circle know about an outer circle's format, breaking the rule.
Entities are a similar trap: the normal rule is that entities do not leave the use-case layer. When they leak out (controllers receiving entities from use cases), that is usually an architecture smell. A rare, accepted exception is authentication-related entities that controllers legitimately need.[1]
Four layers are not a law
The circles are schematic, not a requirement. A small application may work fine with fewer layers — removing a layer simplifies the code but reduces modularity and flexibility. The Dependency Rule always applies no matter how many layers you keep.
In practice
For hands-on walkthroughs, two implementations of the same Tic-Tac-Toe game show the pattern in real code: a front-end version with ReactJS and a back-end version with ExpressJS.[1]
Related Notes
- Software Architecture Layers — how layer names map across architecture styles
- SOLID — the design principles Clean Architecture leans on
- Dependency Injection and Inversion of Control — the mechanism behind the Dependency Rule
- CQRS — a command/query style that fits the same layered shape
- Design Principle