Clean Architecture Is One Rule, Not Four Circles
Dependencies point inward. That one rule makes business logic testable and the database replaceable. Here is how to apply it without the ceremony.
On this page
Open a “clean architecture” repo and you often find fourteen folders, a mapper for every mapper, and a one-line use case wrapped in three interfaces. That is the costume, not the idea. The idea fits on a sticky note: your business logic must not depend on your frameworks.
The four layers, innermost first
- Entities
The enterprise-wide business rules: what an
Orderis, what makes a refund legal. The most stable code in the system, with no knowledge of databases, HTTP or UI. - Use cases
Application-specific operations such as
PlaceOrderorCancelSubscription. They orchestrate entities and talk to the outside world only through interfaces they define. They do not care how data is shown or stored. - Interface adapters
Controllers, presenters and gateways. They convert data from the shape the outside world uses (HTTP JSON, SQL rows) into the shape use cases understand, and back.
- Frameworks and drivers
The web framework, the database, the message broker, the UI toolkit. Details, deliberately on the outside, depending on everything inside them.
The dependency rule in one example
A use case needs to save an order. It must not import a Postgres client. Instead it declares what it needs:
// inner layer: owned by the use case
interface OrderRepository {
save(order: Order): Promise<void>;
}
class PlaceOrder {
constructor(private repo: OrderRepository) {}
async run(cmd: PlaceOrderCommand) {
const order = Order.create(cmd.items); // business rules in the entity
await this.repo.save(order);
}
}
// outer layer: implements the interface
class PostgresOrderRepository implements OrderRepository {
async save(order: Order) { /* SQL here */ }
}
The arrow of source code points from PostgresOrderRepository to OrderRepository, inward. At runtime the use case calls the repository, outward. This inversion is the entire trick, and it is the same dependency inversion principle you may know from SOLID.
Two concrete things. Tests: pass an in-memory OrderRepository and the use case runs in milliseconds with no database. Replaceability: swapping Postgres for another store, or REST for a queue consumer, touches only the outer layer.
When it is worth it, and when it is theatre
| Situation | Verdict |
|---|---|
| Rich domain rules, several delivery mechanisms, long-lived product | Worth the structure |
| Thin CRUD over one database, small team, short horizon | Keep the rule (no framework imports in logic), skip the layers |
| Prototype you may throw away | Skip it, but do not let SQL leak into business rules |
Signs you are doing the costume: use cases that only forward to a repository, a DTO per layer with identical fields, and folders created because a diagram had a box for them.
Do
Keep business rules free of framework and database imports, define the interfaces where they are used, and let the outer layers adapt to them.
Don't
Add layers, mappers and interfaces “for later”. Indirection you do not need costs every reader every day, and you can add a seam when a second implementation actually appears.
Takeaway
Clean Architecture is a discipline about the direction of dependencies, not a folder template. Protect the inside from the outside, test the inside without the outside, and add structure only where the domain or your infrastructure choices have earned it.
Frequently asked questions
What is the dependency rule?
Source code dependencies may only point inward, toward higher-level policy. Inner layers such as entities and use cases must not know anything about outer layers like web frameworks, databases or UI. If an outer detail must be used, the inner layer defines an interface and the outer layer implements it.
What lives in each layer of Clean Architecture?
Entities hold core business rules. Use cases hold application-specific operations that orchestrate entities. Interface adapters convert data between use cases and the outside world: controllers, presenters, gateways. Frameworks and drivers are the outermost details: the web framework, the database, devices. Dependencies always point from outside to inside.
Is Clean Architecture overkill for a small app?
Often, yes. The full layering adds files and indirection that a small CRUD app never repays. The dependency rule is still useful at any size: keep business logic free of framework imports. Add the extra layers when the domain gets complex or you need to swap infrastructure.
How does this help testing?
Because use cases depend on interfaces, not on the database or web framework, you can test business rules by supplying in-memory fakes. The tests run in milliseconds without starting a server or database, and they fail only when business behaviour changes.



/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.