The Onion Architecture in 5 Minutes

Write Maintainable Software by preventing external dependencies from polluting your application core

Martin Cerruti


Photo by Wilhelm Gunkel on Unsplash

The Onion Architecture was first introduced by Jeffrey Palermo around 2008. At its very essence, the architecture focused on modeling business logic and entities at the application’s core, without any notion of the outside world.

Because the business has no notion of the outside world — for example, it doesn’t know its data is stored in a database — the outside world can never contaminate the domain. This way, you are able to keep the core of the application relatively simple; focused on business-specific operations without having to account for endless “what-if’s”.

As a result, if done well, the onion architecture significantly reduce the amount of refactoring by separating application and infrastructural concerns.

The Onion Architecture’s model looks — perhaps unsurprisingly — like an onion:

Layers of the Onion Architecture

One of the foundational rules of the Onion Architecture is that dependencies can only ever point inward. That is, while it is fine for the UI to reference the Application Services, it would be absolute heresy for the Domain Model to reference its services.

Peeling The Onion

The outer layers consist of the Infrastructure layer. This is where our database, message queue, and perhaps a file system lives. This layer is unique, because it provides to the application in a supporting manner.

Tests and User Interface

The Tests and User Interface layer are interesting because they are similarly different. They both use the Application Services in the sense that they are its customers. The tests are fairly one dimensional in the sense that they perform actions and observe and validate the result.

The User Interface can literally be any UI. This can be a Command Line application used by technical support staff, or a full-blown nifty Web App used by the company’s end-users.



Martin Cerruti

Software Architect, Technology Writer, but most of all a programmer.