Onion Architecture
Onion architecture places a domain model at the centre and wraps it in rings. Around the model sit the application’s other layers; around those sit the infrastructure, the user interface, and the tests. One rule governs every dependency: it points inward. Code may depend on layers closer to the centre, and never on layers further out. The database is external; persistence is reached through interfaces the core defines and an implementation at the rim supplies [1].
Palermo presents onion openly as a named pattern — a set of object-oriented techniques and conventions gathered and named so that they can be communicated [1]. So the question is not whether onion 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 hexagonal architecture: does the domain’s change-driver structure mandate the cut? The argument below is self-contained for onion. The shared machinery — representation, the partition, the shape-versus-rule boundary — is developed on the hexagonal page.
1 At a glance
| Underlying principle | Succeeds when | Fails when |
|---|---|---|
| Onion nests a domain model inside a centripetal stability ordering of rings. | The domain model is genuinely stable and the infrastructure volatile; the gradient is monotonic. | The gradient inverts (a volatile model) or is non-monotonic (a stability valley); the model’s state and its mapping are split. |
2 The claim
The domain model is the innermost ring, and Palermo says it “is only coupled to itself.” The next ring holds the interfaces the core needs — repository interfaces, for example — while their implementations live at the rim. The rim is “reserved for things that change often”: infrastructure, the user interface, tests. It is isolated from the core.
3 Onion justifies the ring order by change frequency
The rule that fixes the ring order is the inward dependency rule. Its justification, though, is stated in terms of change: isolating the volatile rim protects the core from churn. That is a claim about how often things change.
The Independent Variation Principle (IVP) does not rank change drivers by frequency. Frequency orders work; it does not fix a boundary. A boundary is fixed by which change activates which elements, not by how often [2]. So onion’s stated axis — changes often versus changes rarely — is a proxy. It can coincide with the partition. It does not determine it.
4 The rings are not in the domain’s analysis
No business analysis or functional analysis organises knowledge as a domain model at the centre, a repository-interface ring around it, and infrastructure at the rim. Analysis names rules, entities, processes, events, decisions, responsibilities, and policies. The ring scheme is not among those forms. The rings appear when a designer lays out code; they are an object-oriented encoding. Palermo says so directly: the architecture is “unashamedly biased toward object-oriented programming, and it puts objects before all others.” That is an encoding choice, and the designer makes it. Absence from the analysis is evidence, not the test; the test is coincidence with the partition.
5 The domain model is not coupled only to itself
The strongest of onion’s claims is that the domain model is coupled only to itself. That is a claim about the direction of reference: the model imports nothing from an outer layer. Onion 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 the model’s state and its mapping carry the same change-driver assignment.
Onion puts the model at the centre and its mapping at the rim. 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 model-at-the-centre claim is meant to prevent. The model is not quiescent: under the framework’s reading, it is coupled to the very mechanics the rings were meant to isolate.
6 What onion embodies, and what it invents
Two parts are worth separating.
- The inward 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. Onion’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. The domain-model kernel, the repository-interface ring, the domain-service and application-service division: none of these is in the analysis.
A representation is unavoidable: some structure must carry the knowledge. 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. Onion’s rings are that deviation. The repository interface is the clearest case: Palermo places it in the core because the model needs to be saved, but the need to persist is an infrastructure fact, and the interface that expresses it is a code artifact. The core does not gain knowledge from holding it; it gains a dependency on a shape the domain never named.
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 onion, 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 ring scheme is a taught pattern.
Non-spontaneity is evidence, not proof, that a structure is a convention and not knowledge. Onion 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. When the encoding is read as knowledge, the chosen structure goes in as if the domain had asked for it, and the domain never did.
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, onion’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 onion 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 onion answers to one decomposition, not one per concern.
Onion does no harm only where its rings coincide with that decomposition. Where they do not, every change crosses a boundary the domain did not set: a class split across rings scatters one change, and a ring that groups non-equivalent elements couples what the domain keeps apart.
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; the pure, disjoint change-driver case is unconditional [4]. Whether the metric matches real economic cost is an empirical question. Palermo’s advice — onion is “not appropriate for small websites” and suits “long-lived business applications” [1] — is a statement about where that cost matters. The placement result does not depend on it: Γ-equivalence is correct placement for every modelled concern, whatever the cost coefficients.
- The theory does not discover the rule. It defines what cohesion is; identifying the domain conditions that matter 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 onion does no harm: its rings coincide with the change-driver decomposition. It still adds no decomposition of its own; the partition does the work, and onion packages it. Outside the band, onion is harmful wherever its rings do not coincide with the partition.
10 Beyond placement: faithful embodiment
The theory separates three properties, each attached to a different object: 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 the condition. 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.
Onion can clear placement and fail this. Nothing in onion checks whether the code realises the knowledge it carries, and the ring diagram looks the same.
Onion 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
- Onion directs all coupling toward a domain-model centre and rings the rest around it. Its stated axis is change frequency.
- IVP does not rank change drivers by frequency; frequency orders work, not boundaries. The frequency axis is a proxy.
- The rings — model kernel, repository-interface ring, service layers, infrastructure rim — appear in no analysis artifact. They are concepts the designer adds; Palermo presents them as a named pattern of conventions.
- The domain model is not coupled only to itself: 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).
- Where the rings coincide with the partition, onion adds nothing; where they do not, it invents structure the domain did not mandate.
- The strongest defensible claim: onion’s rings are invented concepts except where they coincide with the partition. Its decomposition value is the partition, which one can obtain without it.
- Onion does no harm only where its rings coincide with the change-driver decomposition; it is harmful where they do not. Placement is not faithful embodiment.
- IVP is one modularising principle among those the system’s concerns induce; Γ-equivalence is the common refinement of them, correct under all at once. The theory is a re-description, not a proof that no other kind of principle exists.
Compare hexagonal architecture, which reaches the same conclusion by a different route.
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