Understanding Onion Architecture: Beyond the Concentric Circles

What Onion Architecture Really Is

Onion Architecture is not about the literal onion or concentric circles; its core principle is that dependencies must converge inward. The concentric circles are merely a visual aid to make the dependency rule obvious.

Six‑Layer Structure

The complete structure consists of six layers, each with a specific responsibility and a strict inward‑only dependency direction:

Domain Model – encapsulates core business rules and domain concepts; does not depend on any outer layer.

Domain Services – executes domain‑level business operations and coordinates multiple domain models; depends only on the Domain Model.

Application Services – orchestrates use‑cases by composing Domain Services and the Domain Model; depends on Domain Services and Domain Model but not on Infrastructure or UI.

Infrastructure – implements database access, message queues, third‑party APIs, etc.; depends on interfaces defined in inner layers.

UI (User Interface) – presentation layer such as Web, CLI, or mobile; depends on Application Services.

Tests – integration or end‑to‑end tests; depend on Application Services.

Each outer layer can be replaced without affecting inner layers because the inner layers never reference outer packages.

Dependency Direction Inward

All outer layers may depend on inner layers, but inner layers must never depend on outer layers. In source code this means import/using statements only point from outer circles to inner circles. This rule implements the Dependency Inversion Principle at the architectural level.

Benefits of the Inward Dependency

Testability: because the core does not rely on databases or web servers, domain logic can be unit‑tested with mocks for Infrastructure.

Replaceability: swapping MySQL for PostgreSQL, RabbitMQ for Kafka, or a REST API for gRPC requires no changes to inner code.

UI and Tests can be changed (e.g., Web to CLI, integration to unit tests) without touching business logic.

Common Misconceptions

"Onion Architecture is just a three‑layer diagram drawn as a circle" – The dependency direction is outer→inner, unlike the linear UI→BLL→DAL flow of classic three‑layer architecture.

"The number of concentric layers is fixed" – Palermo defined six layers as a default; teams can merge or split layers as long as the inward dependency rule stays intact.

"Onion, Clean, and Hexagonal are completely different" – All share the same core idea: dependencies point toward the core, making outer parts replaceable. They differ only in terminology and visual representation.

"The Domain Model layer is just a collection of data entities" – It must contain business rules and behavior; a “anemic” model that only holds getters/setters moves logic to services and defeats the architecture.

Relation to Clean and Hexagonal Architectures

Clean Architecture emphasizes the immutable dependency rule, while Hexagonal Architecture focuses on ports and adapters. Onion Architecture provides the most intuitive visual cue (the concentric circles) to see the direction of dependencies at a glance.

Choosing which representation to use depends on team culture: visual diagrams for "show‑the‑picture" teams, rule‑driven descriptions for "clean" advocates, or contract‑first language for "hexagonal" fans.