Onion Architecture

The Onion Architecture was created by Jeffrey Palermo in 2008. It is seen by many as an evolution of the Ports and Adapters Architecture.

The idea of the Onion Architecture is to place the Domain and Services Layers at the centre of your application. And externalize the Presentation and Infrastructure.

Externalize infrastructure and write adapter code so that the infrastructure does not become tightly coupled.

It might sound similar to how I explained and see the Layered Architecture of today. But it goes further than just layers.


Externalizing infrastructure is the premise of both Ports and Adapters and the Onion Architecture.

But Ports and Adapters only implicitly mention 2 layers. The internal layer representing the business logic, and the external layer representing delivery mechanics and infrastructure.

Then remember that in the Layered Architecture. We have 4 layers. Presentation, Application, Domain and Infrastructure.

So what the Onion Architecture then does is combine the 2 ideas. Thus explicitly define this inner layer as having Application Services, Domain Services and Domain Models.

Full Circle

This brings us full circle. So the Onion Architecture is layering, but then in a circle! Right??

Well, it’s not that simple.

Look again!

The Domain Model is in the middle! The difference is that we have a core. And that we move through the Onion.

From the UI trough our Application Service to our Domain Model and so back to the outside. We cross-cut the Onion.

It is important to note that all dependency move inwards. The layers inside the application core define the interfaces that the outer layers can use.

The outer layers thus depend on the inner layers interfaces. And the inner layers do not have any dependencies towards the outside layers.

We now have the flexibility to change the outer layers without impacting any of the inner layers. If I want to change the infrastructure implementation of sending emails. No problem, just make sure we use the interfaces defined by our application core. We can upgrade and change our infrastructure or framework without impacting our application core.

Peeling of onions

Another way to see the Onion Architecture is like an onion that you can peel off.  If you peel off the outer layer with infrastructure, presentation and tests. Then the inner layer (application core) should still work.

The application core should be able to run without infrastructure and presentation.


The Onion Architecture is an evolution of the Ports and Adapters Architecture. And in here we add layers and some extra ideas.

In short applying the Onion Architecture means:

  • The system is built around an independent Application Core
  • The inner layers (inside the core) define interfaces. The outer layers then implement these interfaces.
  • The outer layers are coupled to the inner layers
  • The Application core (inner layers) can be run and separated from the infrastructure and presentation. You can peel them of the onion and still have a working core.

Thus, by applying ideas of this architecture; you can lower coupling and improve cohesion. All of this helps us improve the testability and maintainability of the systems.

But don’t always blindly apply all these concepts. It’s always a good idea to think about what Onion Architecture is, why and when to use it. See how it all fits into your situation. Remember that the Onion Architecture can also be combined with other concepts as CQRS and event sourcing.

As always, think before you code!