Clean Architecture — the dependency rule
Clean architecture on an interactive canvas: entities, use cases, interface adapters and frameworks, and the dependency rule that keeps the core independent.
Clean architecture organises code into concentric layers — entities, use cases, interface adapters, frameworks — under one rule: dependencies always point inward, so the core never depends on a tool.
Clean Architecture — the dependency rule
The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.
How to read this visual
- Read the left column top to bottom as the four layers, from the innermost (Entities) to the outermost (Frameworks).
- Then read the right column top to bottom as the rule that governs them: dependencies inward, adapters in the middle, the core untouched.
- The arrows flow outward-to-inward in spirit even though they are drawn left to right — each outer layer's code depends on the layer inside it.
The four layers
"Entities — enterprise-wide business rules" is the innermost ring: objects and rules that exist no matter how the app is delivered — a customer, an invoice, the rule that an invoice cannot be paid twice. "Use cases — application-specific rules" orchestrates entities for one application scenario. "Interface adapters — controllers, presenters" translates between the use cases and the outside world, and "Frameworks and drivers — UI, database, web" is the outer ring of tools.
The dependency rule
"Dependencies point inward, never outward" is the single rule the whole architecture exists to enforce: source code dependencies always cross inward. "Outer layers talk through the adapter, not to the core" is the mechanism — a use case declares an interface for saving an invoice, and the database adapter implements it, so the use case never imports the database library.
The payoff
"Swap frameworks without touching the core" and "The core never imports a framework" are the test of whether the rule was kept: migrate from one database or UI to another and the entities and use cases change not at all. That is the whole value proposition — the most important, most expensive code is insulated from the most replaceable.
Key relationships and takeaways
- Dependencies always point inward — that single rule is what the architecture is.
- The core declares interfaces; the outer rings implement them — the adapter is the seam.
- Entities and use cases are framework-independent by construction.
- The payoff is replaceability: swap UI, database or web framework without touching the core.
- Clean architecture is about dependency direction, not about the number of layers.
When to use this visual
- Teaching the dependency rule to a team before they structure a large codebase.
- Reviewing an architecture: a use case that imports a UI or database library is a rule violation, visible on the canvas.
- Planning a rewrite or migration — the canvas shows which layers must survive and which can be replaced.
How it works
Rename the layers to your stack
Replace the generic ring names with your real ones — your entities, your use-case classes, your controllers and gateways, your actual UI and database frameworks.
Draw the interface seams
Add the interfaces the core declares and which adapter implements each, so the diagram documents the seams the dependency rule crosses.
Mark the violations
Add a label or different shape to any layer that currently imports outward, with a note on the refactor that would fix it — the canvas doubles as an audit.
Show a real swap
Add a branch where one outer framework is replaced by another and both connect through the same adapter, ending in the unchanged core.
Frequently asked questions
What is clean architecture?
It is an architectural pattern, popularised by Robert C. Martin, that organises code into concentric layers: entities at the centre, then use cases, then interface adapters, then frameworks and drivers at the edge. Its governing rule is that source code dependencies always point inward, so the core business rules never depend on the delivery mechanisms — UI, database, or web framework.
What is the dependency rule?
The dependency rule says source code dependencies must always cross inward: an outer layer may depend on an inner layer, never the reverse. Practically, the inner layers declare interfaces and the outer layers implement them, so the core's code imports nothing from the tools at the edge. The visual draws this as its own cluster because every other property of the architecture follows from it.
How is clean architecture different from layered architecture?
Layered architecture also separates responsibilities, but its dependencies usually flow top-down — the presentation layer calls the service layer, which calls the data layer. Clean architecture inverts that: the business core sits at the centre and everything else depends on it, so the direction of dependency is the distinguishing feature. The visual's arrow into the core is the difference made visible.
Is clean architecture worth it for a small project?
Not always — the ceremony costs more than it returns when the business rules are trivial or the team is one person. The pattern earns its keep when the business logic is complex enough that it must outlive the tools, or when the UI or database is likely to change. The canvas's payoff boxes state the trade honestly: the core's safety is bought with the adapter layers.
Edit this visual in QueryChart (FlowJam)
Open this exact clean architecture canvas as your own chart, rename the layers to your codebase, and map your dependencies.