Onion architecture

Onion architecture is a software architectural pattern introduced by Jeffrey Palermo in 2008. It organizes a system into concentric layers, like the rings of an onion, with the domain model at the center and infrastructure concerns on the outside. The defining rule is that dependencies may only point inward, toward the center. An inner ring may know nothing about the rings outside it.

The pattern pursues the same objective as Alistair Cockburn’s hexagonal architecture (2005) and Robert C. Martin’s clean architecture (2012): the separation of concerns, achieved by slicing a system into discrete layers and applying dependency inversion at the boundaries between them. The three patterns differ more in vocabulary than in substance. Hexagonal architecture frames the rule as ports and adapters on every boundary. Clean architecture names four specific layers and an explicit dependency rule. Onion architecture emphasizes the concentric shape and the inward direction of every dependency.

The layers

Onion architecture does not prescribe a fixed number of rings, but a common form has four, from the center outward.

  • Domain model. The core entities and the rules that are most stable and least likely to change for external reasons. These objects would exist even if there were no application to use them. The domain model depends on nothing outside itself.
  • Domain services. Operations on the domain model that do not belong to a single entity. This is where the domain layer of domain-driven design typically sits.
  • Application services. The use cases the application supports. This layer orchestrates the flow of data to and from the domain model and enforces the rules that define how the application behaves. It depends on the inner rings, never the reverse.
  • Infrastructure. The outermost ring, holding the details that change most often: the web framework, the database, external APIs, and the UI. This layer is kept intentionally thin, containing only the glue code that connects infrastructure to the application services.

The dependency direction

The dependency direction is the mechanism by which onion architecture achieves its separation of concerns. Because the domain model at the center has no knowledge of the database, the web framework, or the UI, it can be tested in isolation and is insulated from changes in the infrastructure around it. The layered architecture that onion architecture builds on is the same idea expressed as horizontal tiers. Onion architecture rearranges it as concentric rings and makes the inward dependency direction a rule rather than a convention.

Benefits and trade-offs

The primary benefits follow from the inward dependency direction.

  • Testability. The domain model can be tested without the database, the UI, or any external system, since it depends on nothing outside itself.
  • Independence. The application does not depend on any particular framework, database, or UI. Each can be swapped by changing only the outer ring that adapts it.
  • Evolvability. Because the most stable code is the most central, routine changes to infrastructure have no reason to touch the domain model, so the surface area affected by any given change is smaller.

The trade-off is accidental complexity. Every ring adds interfaces, data conversion, and indirection. For small or straightforward applications the discipline of strict concentric layers can be more cost than benefit, and a simpler layered architecture may serve the same ends.

References

See also