Onion Architecture
Coined by Jeffrey Palermo
Onion Architecture is a software architecture pattern, introduced by Jeffrey Palermo, that arranges application layers in concentric rings around a central domain model, with all dependencies pointing inward so that the domain has no…
Definition
Onion Architecture is a software architecture pattern, introduced by Jeffrey Palermo, that arranges application layers in concentric rings around a central domain model, with all dependencies pointing inward so that the domain has no dependency on infrastructure, UI, or external services.
Overview
Onion Architecture was introduced by Jeffrey Palermo in a 2008 blog post as a response to the shortcomings of traditional layered ('N-tier') architecture, where a typical UI-Business Logic-Data Access layering often results in business logic depending directly on data-access code, which in turn couples core logic to a specific database technology and makes independent testing difficult. Palermo's model instead pictures the application as concentric rings, like an onion: at the very center is the Domain Model, containing core entities and business rules with no external dependencies whatsoever. Surrounding that are Domain Services, which implement operations on the domain model. The next ring out holds Application Services, which orchestrate use cases and coordinate domain objects to accomplish application-specific tasks. The outermost ring contains Infrastructure and UI — the database implementations, external service clients, web frameworks, and user interfaces. The governing rule, shared with hexagonal and clean architecture, is that dependencies only point inward: outer rings can reference and depend on inner rings, but inner rings have no knowledge of outer rings. Interfaces for things the domain needs from the outside — like a data-persistence contract — are defined in an inner layer and implemented by a concrete class in an outer layer (typically using the repository pattern), which is then wired together at the application's composition root, often via a dependency-injection container. This means the domain model can be compiled and unit tested with zero database, web server, or external service running. Onion Architecture is essentially a sibling pattern to Hexagonal Architecture and a direct precursor to Clean Architecture; all three express the same 'dependencies point toward the core' principle with different naming and visual metaphors, and in practice teams often use the terms somewhat interchangeably or blend elements of each. Onion Architecture is particularly associated with .NET/C# enterprise application development, where Palermo's original writing and subsequent community adoption were concentrated, though the pattern itself is language-agnostic.
Key Concepts
- Concentric layers: Domain Model at the center, then Domain Services, then Application Services, then Infrastructure/UI
- All dependencies point inward — the domain model has zero external dependencies
- Interfaces needed by the domain are defined inward and implemented outward (via repository pattern)
- Enables unit testing the domain model without any database, web server, or infrastructure
- Wiring between interfaces and implementations happens at the application's composition root
- Sibling pattern to Hexagonal Architecture, direct precursor to Clean Architecture
- Introduced by Jeffrey Palermo in 2008 as an alternative to traditional layered (N-tier) architecture
- Strongly associated with .NET/C# enterprise development, though language-agnostic in principle