Onion Architecture

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

The Onion Architecture was coined by Jeffrey Palermo in 2008. As I see it, it builds on the Ports & Adapters Architecture by adhering to the idea of placing the domain in the centre of the application, externalising the delivery mechanisms (UI) and infrastructure used by the system (ORM, Search engines, 3rd party APIs, …). But it goes further and adds internal layers to it.

We went from the Layered Architecture, with usually 4 layers (Presentation, Application, Domain, Persistence), to the Ports & Adapters Architecture which only implicitly mentions two concentric layers:

  1. An external layer representing the delivery mechanisms and infrastructure;
  2. An internal layer representing the business logic.

Both Ports & Adapters and Onion Architecture share the idea of isolating the application core from the infrastructure concerns by writing adapter code so that the infrastructure code does not leak into the application core. This makes it easier to replace both the tools and the delivery mechanisms used by the application, providing some protection against technology, tooling and vendor lockdown.

It also gives the application the pleasant ability to be able to run without the need for real infrastructure nor delivery mechanisms as they can be swapped by mocks, which is great for testing.

However, the Onion Architecture also tells us that, in enterprise applications, we will have more than those two layers, and it adds some layers in the business logic which we might recognise from Domain Driven Design:

2008 - Onion Architecture

Furthermore, it makes explicit the implicit idea of Ports & Adapters Architecture about the direction of dependencies:

  • Outer layers depend on inner layers;
  • Inner layers do not know about outer layers.

This means that the direction of coupling is towards the centre, providing us with an independent object model (domain model), who in its core depends on nothing. We have the flexibility of being able to change the outer layers without impacting the inner, and more important, layers. It makes use of the Dependency Inversion Principle, at an architectural level.

Key tenets of Onion Architecture:

  • The application is built around an independent object model
  • Inner layers define interfaces. Outer layers implement interfaces
  • Direction of coupling is toward the center
  • All application core code can be compiled and run separate from infrastructure

Jeffrey Palermo 2008, The Onion Architecture: part 3

Also, any outer layer can directly call any inner layer, which does not break the coupling direction and avoids creating proxy methods and even proxy classes that contain no business logic, just for the sake of complying with some layering scheme. This also comes in line with the preferences expressed by Martin Fowler.

[…] the layers above can use any layer beneath them, not just the layer immediately beneath.

Jeffrey Palermo 2008, The Onion Architecture: part 3


Onion Architecture builds on the Ports & Adapters Architecture to add some internal organisation to the business logic of the application based on a few Domain Driven Design concepts.

Again, this is an evolution in further segregating responsibilities, providing for low coupling and high cohesion, which in turn provides for more testability and maintainability.


2002 – Martin Fowler – Patterns of Enterprise Application Architecture

2008 – Jeffrey Palermo – The Onion Architecture: part 1

2008 – Jeffrey Palermo – The Onion Architecture: part 2

2008 – Jeffrey Palermo – The Onion Architecture: part 3

2013 – Jeffrey Palermo – The Onion Architecture: part 4 – After Four Years

6 thoughts on “Onion Architecture

  1. Hey , i really love this series of post , really hope it won’t go offline… Any way you can Zip it or something?

    You did all the work for us , reading all those books while the only book i have read was clean architecture , it seems that ivar said it all long time ago ,but here and then people re-discover it.

    Any recommended book if can read only one?

    Thank you


    1. Tkx, and you’re welcome.

      The book that had the most impact on me was the blue book, “Domain-Driven Design: Tackling Complexity in the Heart of Software” by Eric Evans. There is a more recent one on tge same subject “Implementing Domain-Driven Design” by Vaughn Vernon but I haven’t read it.
      Another very good one is “Lean Architecture for agile software development” by James Coplien, and another MUST READ is “The mythical man month” by Frederick P Brooks.
      These 3 books are, for me, the MUST READs for any serious software engineer and/or software architect. They were game changers for me.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s