How clean architecture works
Concentric rings of code where every dependency points toward the business rules.
Clean architecture organizes code into concentric layers — Entities at the core, then Use Cases, Interface Adapters, and Frameworks & Drivers on the outside. The Dependency Rule says source-code dependencies may only point inward, so the business rules never know about the database, web framework, or UI. This makes the core testable in isolation and independent of the tools around it.
Entities at the core
The innermost ring holds Entities — the enterprise-wide business rules and the data structures they operate on. These are the concepts that would exist even without this particular application: an Account's rules about balances, an Order's rules about validity. They depend on nothing else in the system, which makes them the most stable and the least likely to change when a framework or screen does.
Use Cases orchestrate
Surrounding the entities are Use Cases — application-specific business rules that describe what the software actually does, like 'transfer funds' or 'place an order.' They orchestrate entities to fulfill a user's goal but remain ignorant of how requests arrive or where data is stored. A change to a screen or database should never force a change here.
Interface Adapters translate
The next ring converts data between the shape convenient for use cases and the shape convenient for the outside world. Controllers take incoming requests and call use cases, presenters format results for display, and gateways/repositories adapt calls to a database or external service. This layer is where the translation happens so the inner layers can stay pure.
Frameworks & Drivers on the edge
The outermost ring is all the details that could be swapped out: the web framework, the database engine, the UI toolkit, external devices and APIs. Clean architecture treats these as plugins to your application rather than its foundation. Because they sit at the edge, replacing Postgres with MySQL or Express with Fastify should ripple no further than this layer.
The Dependency Rule holds it together
The rule that makes the whole scheme work is that source-code dependencies may point only inward — outer layers depend on inner ones, never the reverse. When an inner use case needs the outside world, it defines an interface that an outer adapter implements, inverting the dependency. This is what lets you test the core with no database or web server, and swap frameworks without touching business logic.
The problem it solves
Most codebases rot in a predictable way: the business logic gets tangled up with the framework, the database, and the UI until you can't change one without breaking the others. Swapping Postgres for a different store means editing business rules; upgrading the web framework means touching everything; and testing a simple rule requires spinning up a database and an HTTP server. The system becomes rigid and fragile because the important part — the logic that makes the business money — is held hostage by the least important, most volatile parts.
Clean architecture, articulated by Robert C. Martin, is a way to stop that. It is one of a family of similar ideas (Hexagonal / Ports and Adapters, Onion Architecture) that all share one goal: keep the business rules at the center, isolated from and independent of the mechanisms that deliver them. The promise is a system that is independent of frameworks, independent of the UI, independent of the database, and — crucially — testable without any of them.
The concentric layers
Clean architecture is usually drawn as a set of concentric circles, from the most abstract and stable at the center to the most concrete and volatile at the edge:
- Entities (innermost) — the enterprise-wide business rules and the core objects they act on. These encapsulate the ideas that would be true across the whole business, application or not: what makes an order valid, how interest accrues. They are the most stable code you have.
- Use Cases — the application-specific business rules. Each use case orchestrates entities to accomplish one user-facing goal ("transfer money," "register a user"). They define *what the application does*, without knowing how it's triggered or stored.
- Interface Adapters — controllers, presenters, and gateways that convert data between the form the use cases like and the form the outside world needs. This is a translation layer.
- Frameworks & Drivers (outermost) — the web framework, database, UI, external services, and devices. Martin's advice is to treat these as *details*: plugins to your application, not its foundation.
The further out a ring, the more replaceable it should be.
The Dependency Rule
The single rule that gives clean architecture its power is the Dependency Rule: *source-code dependencies may only point inward.* An outer layer may depend on and call an inner layer, but an inner layer must know absolutely nothing about any outer layer. The name of a class, function, or variable in an outer circle must never appear in an inner one.
Concretely, this means the entities don't import the use cases, the use cases don't import the controllers or the ORM, and nothing in the core references Express, React, or Postgres. Data crossing a boundary is passed as simple structures the inner layer defines. Because the flow of *control* often needs to go outward (a use case needs to save something to the database) while the flow of *dependencies* must stay inward, clean architecture leans heavily on dependency inversion: the inner layer declares an interface (a "port" — say, OrderRepository) and an outer adapter implements it. The use case depends only on its own interface; the database adapter depends on the use case. The arrow still points inward, and the core never learns what actually stores the data.
Why this buys testability and independence
The payoff of the Dependency Rule is concrete and large.
- Testability. Because the core has no dependency on frameworks or I/O, you can test entities and use cases as plain objects, with in-memory fakes standing in for the database and network. Tests run in milliseconds, in isolation, without booting a server or a database — which is exactly the kind of test suite that stays fast and trustworthy as a project grows.
- Framework independence. The web framework becomes a delivery detail plugged in at the edge. You can move from one framework to another, or add a CLI or a queue consumer alongside the HTTP API, by writing new adapters — the business rules don't change.
- Database independence. Swapping Postgres for MongoDB, or adding a cache, means writing a new gateway that satisfies the same repository interface. The use cases never notice.
- UI independence. The same use cases can drive a web app, a mobile app, and an admin tool, because the presentation lives entirely in the outer ring.
In short, the parts most likely to change are quarantined at the edges, and the parts most valuable and stable are protected at the center.
Trade-offs and practical use
Clean architecture is not free, and applying it dogmatically to everything is a mistake. The cost is indirection and boilerplate: ports, adapters, and data-transfer objects at every boundary add layers of code and mapping that a small CRUD app simply doesn't need. Forcing it onto a throwaway service or a thin data-shuffling API produces ceremony without benefit, and beginners often over-abstract, creating interfaces with a single implementation that will never change.
The judgment is to apply it where the *business logic is rich and long-lived* — complex domains, systems expected to outlast their current frameworks, code that must be thoroughly testable — and to relax it where the app is mostly moving data in and out of a database. It also pairs naturally with Domain-Driven Design: DDD gives you the vocabulary and modeling techniques for the entities and use cases at the center, while clean architecture gives you the structural rules for keeping that model insulated from infrastructure. Used with judgment, the result is a codebase where you can change your tools without rewriting your business, and prove your rules correct without touching a database — which, over years, is what keeps a system maintainable.
Four concentric layers: Entities → Use Cases → Interface Adapters → Frameworks & Drivers (core to edge).
Entities hold enterprise-wide business rules; Use Cases hold application-specific rules that orchestrate them.
Interface Adapters (controllers, presenters, gateways) translate between the use cases and the outside world.
Frameworks & Drivers (DB, web, UI, devices) are the replaceable outer details.
The Dependency Rule: source-code dependencies point only inward; inner layers know nothing of outer ones.
Result: business logic is framework-independent, database-independent, and testable without any of them.
Quick quiz
Which way may source-code dependencies point in clean architecture?
How can an inner use case trigger an outer detail like a database without depending on it?
Key terms in domain-driven design
A shared language and a toolkit of patterns for modeling complex business domains.
The SOLID principles
Five object-oriented design rules that keep code flexible instead of fragile.
Design patterns every developer should know
Named, reusable solutions to problems that keep reappearing in object-oriented design.
What are modular monoliths
The clean boundaries of microservices without the distributed-systems tax.