Onion Architecture, Clean Architecture, and Hexagonal Architecture are often used interchangeably in job descriptions and blog posts. Structurally, how does Onion Architecture relate to the other two, and what does it actually add or change relative to a plain layered architecture?

## Why the three get confused The confusion between Onion, Hexagonal, and Clean Architecture is understandable because they were developed independently by different authors over roughly a decade, converged on the same core insight, and are now frequently cited together or even used as synonyms in industry job postings — but they do have distinct origins and distinct emphases, and understanding both the commonality and the differences is useful for reading unfamiliar codebases and for not getting tripped up by terminology mismatches in an interview or design review. ## Hexagonal — ports and adapters **Hexagonal Architecture**, introduced by Alistair Cockburn around 2005, is the oldest of the three. Its central metaphor is the hexagon (chosen mainly to avoid implying a fixed number of sides or a top/bottom, unlike a traditional layered diagram) with the application's core logic in the middle and **'ports'** — interfaces the core defines for what it needs from, or offers to, the outside world — around its edges. **'Adapters'** are the concrete implementations that plug into those ports from the outside: - a REST controller is a 'driving' or 'primary' adapter that calls into the core through an inbound port; - a database repository implementation is a 'driven' or 'secondary' adapter that the core calls out to through an outbound port. Hexagonal's emphasis is on this symmetry — the same architectural mechanism explains both how an HTTP request reaches the core and how the core reaches a database — and on adapters being swappable and testable in isolation. ## Onion — concentric rings **Onion Architecture**, coined by Jeffrey Palermo in 2008, shares the same inward-pointing dependency rule but presents it as a series of concentric rings rather than a hexagon with ports on its edges: - domain model at the absolute center; - domain services around that; - application services around that; - and infrastructure/UI as the outermost ring. Its distinguishing contribution is naming and separating domain services from application services explicitly as two different rings with two different responsibilities (pure cross-entity business rules versus use-case orchestration), which Hexagonal's port/adapter framing doesn't call out as separate concepts — Hexagonal is largely agnostic about how the core itself is internally organized, as long as ports mediate the boundary. ## Clean — the explicit use-case layer **Clean Architecture**, popularized by Robert C. Martin in a 2012 blog post and later a 2017 book, is best understood as a synthesis and refinement of the two ideas above, adding one significant organizing concept: **use cases as the explicit unit of the application layer**, each one representing a single thing the system can do, often paired with dedicated input/output boundary objects so that data crossing a layer boundary is always a plain, layer-owned model rather than a domain entity or an infrastructure model leaking through. Clean Architecture's diagram uses four rings (Entities, Use Cases, Interface Adapters, Frameworks and Drivers) and is more prescriptive than either Onion or Hexagonal about exactly how data should be shaped when it crosses a boundary. In practice, 'Clean Architecture' in casual industry usage often just means 'onion/hexagonal with an explicit use-case layer,' since that's the one concrete addition most teams actually adopt from Martin's formulation. ## The one rule they share What all three share, and what actually matters for a working engineer far more than the label, is a single underlying rule: **dependencies point inward**, from concrete/volatile outer layers toward abstract/stable inner layers, and the core business logic has zero awareness of frameworks, databases, or delivery mechanisms. What differs between them is mostly vocabulary and which structural detail gets a name: | Formulation | What it contributes | |---|---| | Hexagonal | names the boundary mechanism but stays quiet about internal core structure | | Onion | names the internal core structure but is looser about adapter symmetry | | Clean | adds the use-case-as-unit-of-organization idea and boundary-model discipline on top of both | ## Against a plain layered architecture Relative to a plain N-tier layered architecture (UI to business logic to data access, with each layer freely depending on the one 'below' it, and often the data access layer's model reused directly as the business layer's model), all three add the same thing: an explicit inversion so that the innermost logic doesn't depend on the outermost technology, rather than a layered architecture's typical arrangement where the business layer directly imports and depends on data-access types. In interviews and design reviews, this means the useful skill is being able to say 'I mean dependencies point inward, ports/interfaces owned by the core, and here's specifically how I'd structure the internal rings' rather than defending one label as uniquely correct — real codebases routinely mix the vocabulary without contradiction, because the underlying discipline is identical.