Clean Architecture
Clean Architecture puts enterprise rules at the centre and rings the rest around them. The rings are Entities, Use Cases, Interface Adapters, and Frameworks and Drivers. One rule governs every dependency: source-code dependencies point inward, and only inward. The centre holds the highest-level policy; the rim holds the mechanisms — the web, the database, the frameworks [1].
Martin presents Clean Architecture as a synthesis: it gathers the concentric-ring family — hexagonal, onion, and others — under one rule and one picture [1]. So the question is not whether it admits to being a design. It does. The question is which parts of it embody the domain’s knowledge and which parts it invents.
This page applies the same test used for onion architecture and hexagonal architecture: does the domain’s change-driver structure mandate the cut?
1 At a glance
| Underlying principle | Succeeds when | Fails when |
|---|---|---|
| Clean nests a role partition (Entities, Use Cases, Adapters, Frameworks) inside a stability ordering: depend toward the stable core. | The domain has one capability, the core is genuinely stable, and providers are substitutable — role tracks the change driver and ring position tracks real stability. | Role does not track the change driver (the use-case ring aggregates independent capabilities); ring position does not track real stability (a volatile domain core, a concrete-but-inert framework); or the client depends on a provider’s specifics. |
2 The claim
Clean draws four rings. At the centre sit Entities, the enterprise-wide business rules. Around them sit Use Cases, the application-specific rules. Around those sit Interface Adapters, which convert data between the use cases and the outside. At the rim sit Frameworks and Drivers: the web, the database, the devices. Martin’s rule is that source-code dependencies point only inward. An inner ring knows nothing of an outer one.
3 Clean is a role partition plus a stability ordering
Clean is the composition of two ingredients. The first is a partition criterion: group every element into one of four rings by its role in the application flow. The second is a dependency-direction constraint: enforce the Stable Dependencies Principle across ring boundaries — depend toward the stable core.
The stability ordering rests on Martin’s metrics. Instability is , the ratio of efferent to total coupling: is maximally stable (many depend on it, it imports nothing); is maximally volatile. Abstractness is , the fraction of abstract types. The Main Sequence is the optimal locus; the entity ring sits near , the framework ring near [1].
The stability here is structural self-containment on the import graph, not actual change frequency. An element counts as “stable” because nothing imports force it to change, not because an external authority changes rarely. Clean’s axis therefore couples a role partition to a structural stability ordering, and asserts that ring position determines stability for every element, whatever actually governs it.
IVP groups by which change activates an element. Role and ring-position stability are proxies for that. They can coincide with the partition — in a domain where role tracks the change driver and ring position tracks real stability. They do not determine it [2].
4 The rings are not in the domain’s analysis
No business analysis or functional analysis organises knowledge as Entities, Use Cases, Interface Adapters, and Frameworks. Analysis names rules, entities, processes, events, decisions, responsibilities, and policies. “Entity” and “use case” are domain-near; the ring stratification is not. The rings appear when a designer lays out code; they are an encoding. Absence from the analysis is evidence, not the test; the test is coincidence with the partition.
5 Entities are not coupled only to themselves
Clean’s strongest claim is that Entities — the centre — are the most stable rules, encapsulating the most general business rules, and that outer rings depend on them and never the reverse. That is a claim about the direction of reference. Clean exists to isolate change, so the coupling at issue here is change coupling.
Under the framework’s reading, if recording a new domain fact is taken as one change driver covering the field, the column, and the wire field, then an entity’s state and its mapping carry the same change-driver assignment. Clean puts the entity at the centre and its mapping in an outer ring. The ring boundary therefore runs through one Γ-equivalence class. It separates the entity type from its mapping and splits that class — a Unit Completeness failure. It is exactly the failure the entity-at-the-centre claim is meant to prevent. The entity is not quiescent: under the framework’s reading, it is coupled to the very mechanics the rings were meant to isolate.
6 What Clean embodies, and what it invents
Two parts are worth separating.
- The Dependency Rule is a claim about direction, not about the cut. Direction is domain-determined only where the domain itself orders the elements: where one element’s requirement is chosen to satisfy another’s. Clean’s blanket rule points every dependency inward, whether or not the domain orders them that way. Where they align, the rule adds no structure; where they do not, it asserts a direction the domain does not have.
- The rings are a claim about the cut. Entities, Use Cases, Interface Adapters, Frameworks and Drivers: the stratification is not in the analysis.
A representation is unavoidable. What is not unavoidable is inventing a concept — a named kind, boundary, or category — that the knowledge does not contain. A ring is such an invention exactly when it does not coincide with a change-driver class. If the ring groups elements with different change-driver assignments, it invents a unity; if its boundary splits elements with the same assignment, it invents a division. Only a ring that coincides with a Γ-equivalence class is not an invention, and then it is a redundant name for a real class.
By IVP’s foundational claim, the change-driver partition is the domain’s only organising knowledge [2]. Faithfulness admits no concept that does not correspond to a Γ-equivalence class; any structure beyond the partition is deviation, and deviation is the accidentality. Clean’s rings are that deviation, most sharply in the Use Case and Interface Adapter rings: the split between “application rules” and “adapters” is a code distinction the domain does not name.
7 The split is not the style
The proof is in the artifacts. Grouping by change driver yields the partition; an engineer who embeds the domain faithfully, and who has never heard of Clean, arrives at the partition and not at the rings. The rings are not a structure a developer arrives at on their own: the impulse to keep business rules out of the database is common, but the four-ring scheme is a taught pattern.
Non-spontaneity is evidence, not proof, that a structure is a convention and not knowledge. Clean fails wherever a ring straddles a Γ-equivalence class — the persisted entity, for example. The encoding is the designer’s, the partition is the domain’s.
8 The IVP account
IVP groups elements by change-driver assignment: elements with the same assignment belong together. A module is pure when all its elements share one change-driver assignment set [2]. Judged by that standard, Clean’s rings are correct where no class straddles them and no two non-equivalent elements are grouped.
For a persisted entity, they are not correct; off the partition, the decomposition is wrong under the change-driver criterion.
9 When Clean is beneficial, and when it is harmful
The theory is not maintenance-only. Each concern the system must respect — logical structure, security, deployment, platform, a latency budget — is, once modelled as knowledge governed by change drivers, a partitioning rule over the same element set. IVP is one such principle, and not the only one: grouping by the full change-driver set (Γ-equivalence) is the common refinement of the concerns’ rules, correct under every one at once [3]. The claim is a re-description, not a proof that no other kind of principle exists. So Clean answers to one decomposition, not one per concern.
Clean does no harm only where its rings coincide with that decomposition — that is, where role tracks the change driver and ring position tracks real stability. That is the single-capability, substitutable-provider domain Clean was calibrated against: one capability, a genuinely stable core, genuinely interchangeable providers. There, role happens to track the change driver and ring position happens to track stability.
Outside that domain, Clean is harmful in three ways. Role does not track the change driver: the use-case ring aggregates independent capabilities, and every capability’s changes propagate through it. Ring position does not track real stability: a domain core that is volatile, or a framework that is concrete but inert, inverts or flattens the assumed gradient, and the Dependency Rule then points dependencies toward the most volatile elements. And the inversion is unconditional: where the client’s correctness depends on a provider’s specifics, the abstraction the pattern demands is fabricated — it claims a substitutability the domain does not grant.
Two caveats bound the claim. The cost model is separate, and it models maintenance cost: the partition minimises total maintenance cost under the coefficient condition the model states, unconditional only in the pure, disjoint change-driver case [4]; whether the metric matches real economic cost is empirical. And the theory does not discover the rule: identifying the domain conditions and building the partition is a separate domain-analysis task [3]. A concern left out of the model is a requirements gap, not a cohesion judgement.
Beneficial, here, means only that Clean does no harm: its rings coincide with the change-driver decomposition. It still adds no decomposition of its own. Outside the band, Clean is harmful wherever its rings do not coincide with the partition.
10 Beyond placement: faithful embodiment
The theory separates three properties: placement — the right knowledge in the right modules — which is what cohesion measures; faithful embodiment — each piece realised as it requires; and dependency parsimony — the dependencies are the ones the purpose requires. The three are independent [3].
Correctness is the second alone. A system satisfies an obligation exactly when every knowledge piece the obligation constrains is correctly embodied by some element; placement does not enter. So cohesion governs the cost of achieving and maintaining correctness — the scope to read and the radius to change — not whether it holds. A module can be placed exactly right and still compute a rule with the wrong formula.
Clean can clear placement and fail this. Nothing in Clean checks whether the code realises the knowledge it carries, and the ring diagram looks the same.
Clean is fully sound only when it clears every bar: its rings coincide with the change-driver decomposition, and the code realises the domain’s knowledge faithfully. Alignment without embodiment is a system placed correctly and still wrong about its domain.
11 Summary
- Clean Architecture rings Entities, Use Cases, Interface Adapters, and Frameworks around a centre, with all dependencies pointing inward. It is a role partition plus a stability ordering.
- The stability ordering uses Martin’s metrics — instability, abstractness, the Main Sequence — which measure structural self-containment on the import graph, not real change frequency.
- The rings — entity, use-case, adapter, framework — appear in no analysis artifact; the use-case/adapter split is a code distinction the domain does not name.
- Entities are not coupled only to themselves: under the framework’s reading, a persisted entity’s state and mapping carry the same change-driver assignment, so the ring boundary splits one class (a Unit Completeness failure).
- Clean does no harm only where its rings coincide with the partition — where role tracks the change driver and ring position tracks real stability; it is harmful where they do not.
- The strongest defensible claim: Clean’s rings are invented concepts except where they coincide with the partition. Its decomposition value is the partition, which one can obtain without it.
- IVP is one modularising principle among those the system’s concerns induce; Γ-equivalence is the common refinement of them. The theory is a re-description, not a proof that no other kind of principle exists.
Compare onion architecture and hexagonal architecture, which reach the same conclusion by different routes.
Back to the verdict ledger.
The formal development. The definitions, theorems, and proofs behind this page are published in:
- The Independent Variation Principle — Zenodo, 2026 — doi:10.5281/zenodo.20794332
- On the Nature of Cohesion: Cohesion as Correctness Relative to a Partitioning Rule — Zenodo, 2026 — doi:10.5281/zenodo.21703193
- Why Minimizing Change Propagation Minimizes Maintenance Cost — Zenodo, 2026 — doi:10.5281/zenodo.21362542