The Onion Architecture

  • Post published:May 2, 2020

In the late 2000s Jeffrey Palermo, presented an architectural pattern called the Onion Architecture. The main purpose of this architectural pattern was to control coupling in a software system, to improve separation of concerns (SoC) and to force the externalization of infrastructure.

The below diagram presents the onion architecture.


 The fundamental rule is that all code can depend on layers more central, but code cannot depend on layers further out from the core. In other words, all coupling is toward the center.

Jeffery Palermo

The main difference between traditional architectures (example the 3-tier internet architecture) and the onion architecture is that any outer layer in the onion can directly call any inner layer but an inner layer has no knowledge of any outer layer.

Also, all infrastructure is pushed to the edges where no business logic couples to it, thus making it possible to change/replace obsolete infrastructure products seamlessly and without impacting the core behavior of the software system.

Since infrastructure or things that change often are pushed to the outer edges of the onion, the onion architecture relies heavily on the Dependency Inversion Principle.


The core (also called the application core) consists of the domain layer, repositories layer and services layer. The number of layers in the application core will vary, however, the domain will always be the very center of the onion architecture.


The domain layer (also called the domain model) is in the very center of the onion architecture. It represents the state, processes, rules and behavior of an organization. Since all coupling in an onion architecture is toward the center, the domain is only coupled to itself.


The repositories layer (also called the domain services) is the first layer around the domain. This layer is responsible for storing interfaces that provide object saving and retrieving behavior.

Since a repository typically interacts with a database, the actual implementation of a repository is not found in this layer. The concrete implementation of a repository is implemented outside the application core, thus decoupling the actual database from the application core.


The services layer (also called application services) is a layer providing additional services needed for an application, example a message service, notification service, encoder service, etc.

If the implementation of a service consists of things that change often, then only the interface of this service will be in this layer. The actual implementation of the service will be found in the outer layer of the onion.

For example, if a message service is used and Azure Service Bus was picked as the message system infrastructure component, then the services layer will contain an interface and the concrete implementation using Azure Service Bus will be found in the layer outside of the application core.

Outermost Layer of the Onion

The outermost layer (or outer edge) of the onion is the layer that is directly outside the application core. The purpose of this layer is to externalize infrastructure components, example SQL Database, Azure Cosmos Database, Azure Service Bus etc. This layer is reserved for things that change. Tests and user interfaces are also found in this layer.

Key tenets of the Onion Architecture

1. The application is built around an independent object model

2. Inner layers define interfaces. Outer layers implement interfaces

3. Direction of coupling is toward the center

4. All application core code can be compiled and run separate from infrastructure

Jeffery Palermo


The onion architecture was embraced by the software industry and is a widely used architectural pattern, especially in enterprise software.

Today, most Agile methodologies are encouraging rapid development to implement or enhance features as quickly as possible. To embrace this, the software architecture of the system needs to be simple and easy to extend. The onion architecture is a simple, robust, maintainable and extensible software architecture that fits perfectly in an Agile world.

Further information on The Onion Architecture can be found at the following link:

The onion architecture by Jeffery Palermo