The Onion Architecture

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:

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.

The Layers

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, it doesn’t contain any business-related code.

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.

They all use the same set of Application Services and contracts.

Application Services

If the Domain Model defined the business objects and models, the Application Services layer defines the use cases the application supports, and how they can be interacted with.

It also provides the contracts required to support these use cases. Commonly, this is done through interfaces and data contracts. For instance, a repository interface might reside in this layer.

Domain Services

The Domain Services layer contains the implementation of how the Domain Models “move”. That is, if input should be turned into output, the Domain Services layer would be the place to look for the how.

This is the layer where business decisions are implemented. If a customer can only subscribe once, this is the place where a second subscription attempt would cause a ruckus.

Domain Model

The Domain Model layer (sometimes called Domain Entities) contains the business objects, without any notion of how they are being used. They just know there’s an event of type music. They don’t know people can buy tickets to attend this event.

Implementation

Let’s say we operate a cinema, and we need a system that books tickets for screenings for our customers. We’ll be cooking though, not baking. That is to say that we’ll roughly sketch how the system would work, how the various layers would interoperate, but we won’t go into the nitty-gritty.

When booking a ticket, there are a few entities that come to mind as potentially relevant:

• Screening, which is the movie scheduled at a specific time
• Seat, because our audience doesn’t like to stand for hours
• Movie, with title, cast, play time, etc.

There are probably more, but let’s say this is what we’re working with for our simple cinema.

As you may have guessed, these three are all Domain Models. They live in the centermost layer of our application, and even though they are potentially stored in a database further down the line, they have no notion or implementation details bearing resemblance.

When making a reservation, there is a limit to the amount of tickets we can sell. We want our guests to have a good time, and a good time includes a seat and some overpriced popcorn.

Because ensuring a booking doesn’t exceed the maximum amount of tickets available requires interpreting the data represented by the Domain Models, this almost automatically becomes the responsibility of the Domain Services layer.

Now let’s say we want to go to the movies with our friends. However, we’re going as a group of five, and if we can’t get tickets for everyone, we’ll go do something else. In technical terms, you could call this a group reservation use case.

The group reservation is very similar to a singular booking — in all that if one fails, all should fail. This isn’t a business rule, because the business would be perfectly happy selling three tickets to a group of five, and pocketing the profits. Suffice to say the customers wouldn’t be overjoyed.

Performing the logic required to either execute the full booking, or reject them altogether is the responsibility of the Application Services layer. It may do this through a database transaction or other means, but it doesn’t impact business logic at all.

The application layer doesn’t expose the Domain Models to the outside world. Instead, it contains contracts that represent the required data from the domain models for the outside world. This ensures outside applications don’t store our domain models.

Because we want our system to work the way we expect, we’ll test our Application Services in our Tests layer. This in turn tests the Domain Services, and Domain Entities as well.

We expose our reservation system to our customers through a modern Web Application, as well as a Point of Sale interface for our employees at the cinema. These are both in the User Interface layer.

Because we expect a relational model to be just fine for our use case, we’ll keep our Relational Database, as well as our email provider in the Infrastructure layer. We’ll test them using integration tests before releasing.

And that’s it — our application should be good to go!

Adapting to Changes

One of the key aspects of applying the Onion Architecture — and the one alluded to in the introduction, keeping the amount of refactoring down — is how it adapts to changes.

Because the layers mostly lack tight coupling, changes to the outer layers don’t trickle inwards. For example, if you decide to change your database from a SQL Database to a Document Database late into development, you shouldn’t have to refactor your application logic, or even your domain models.

On top of that, as your Application Services layer deals in contracts — and not in Domain Models! — changes to your Domain Models don’t trickle all the way up the chain either. As long as you can map the data from your entities to your contracts, even the outermost layer of your software may not need to change.

This allows you to stay flexible, making changes in relevant portions of your software, while not having to go through rigorous changes and continuous re-testing. It should make changes less scary.

Closing Thoughts

The Onion Architecture is — in my humble opinion — a cornerstone in Software Architecture. There have been numerous variations and continuations of this architecture since it was coined, most notably the Hexagonal Architecture by Alistair Cockburn and Clean Architecture by Robert C. Martin.

While the architecture is primarily a natural fit for backend systems that have strong data ownership, I have seen successful implementations in React and other front-end technologies as well. The architecture’s abstinence from defining what exact constitutes infrastructure plays a large role in this.

The architecture also lends itself very nicely for Domain Driven Design. Allowing the application to evolve around domain models without contaminating them is an excellent starting point for sharing entities within a bounded context.

There isn’t a one-size-fits-all architecture, but this one is definitely a solid one for every architect to keep at the ready.