In 2008, I coined a new pattern name called Onion Architecture.  You can read the previous parts here: part 1, part 2, part 3.  Over these four years, I’ve spoken about this pattern at user groups, conferences, and it’s even published in one of the chapters of ASP.NET MVC in Action from Manning.

I’ve been overwhelmed by the traction this pattern name has enjoyed.  Folks from all over the country have written about and have talked about the pattern.  Some of the ones I’ve noticed are here (please comment with more – I welcome it).

• Ayende Rahien’s opinion on Onion Architecture
• “Cunning” Clinton’s view
• Tony Sneed’s view and code sample
• StackOverflow questions on Onion Architecture
• Matt Hidinger’s Chicago .Net User Group video presentation on OA
• One interesting StackOverflow question.

Back in 2008, I defined four 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

Although there has been significant adoption of this pattern, I have received countless questions about how to implement it in various environments.  I mostly get asked about how it relates to domain-driven design.  First, onion architecture works well with and without DDD patterns.  It works well with CQRS, forms over data, and DDD.  It is merely an architectural pattern where the core object model is represented in a way that does not accept dependencies on less stable code.

CodeCampServer was an original sample of onion architecture, but it also grew as a sample of how to do ASP.NET MVC in various ways, how to use Portable Areas, and how to use MvcContrib features like input builders.  If you are just looking for onion architecture, it has too much going on.  I have pushed a much simpler solution that represents onion architecture concepts.  I have intentionally not included a UI input form or an IoC container, which most people associate with onion architecture.  Onion architecture works just fine without the likes of StructureMap or Castle Windsor.  Please check out the code here and let me know if this presents a simple approach – that is the goal.

When there is enough interest, I will continue this series with more parts.  CQRS definitely deserves some addressing within this architecture, and so do object models that support task-based UIs.

Get the code here at my BitBucket repository.

Part 1 – Part 2 – This is part 3. part 4. – My RSS feed

In my previous installments, I described what has become my approach to defining the architecture for an application.  Based on feedback, I’ve modified my diagrams a bit to reduce ambiguity and emphasize key points.  The goal of part 3 of this series is to compare and contrast the Onion Architecture with traditional layered architecture.  I will flatten the Onion Architecture to see what it looks like compared to traditional layered architecture, and I will force the layered architecture into an onion.  Whereas the shape can be either, the structure of the actual application is radically different from what is commonly known and accepted.  I’ll define four tenets of Onion Architecture at the end.

I must stress again:  I am not claiming any breakthroughs in technology or technique.  I have learned from other industry thought leaders like Martin Fowler, Ward Cunningham, Kent Beck, Michael Feathers and others (especially those I’ve had the privilege to work with here in Austin, TX).  I’m putting forth the Onion Architecture as an architectural pattern by which we can communicate this radically different architectural approach.  Not "radically different as in new".  Different as in not mainstream.

Let’s review.  Traditional layered architecture can look somewhat like the diagram depicted on the right.  Each layer communicates with the layer below it.  The UI talks to business logic, but it does not talk directly to data access, WCF, etc.  The layering approach does call out the need to keep certain categories of code out of the UI.  The big downfall is that business logic ends up coupled to infrastructure concerns.  Data Access, I/O, and Web Services are all infrastructure.  Infrastructure is any code that is a commodity and does not give your application a competitive advantage.  This code is most likely to change frequently as the application goes through years of maintenance.  Web services are still fairly new, and the first version in .Net, ASMX, is already deprecated in favor of WCF.  We can be assured that WCF’s days are numbered as well, so it is foolish to tightly couple the business logic to WCF.  Data access changes every two years or so, so we definitely don’t want to be tightly coupled to it.  For long-life, we would want our business logic to be independent of these infrastructure concerns so that as infrastructure changes, the business logic doesn’t have to.

Let’s review Onion Architecture.  The object model is in the center with supporting business logic around it.  The direction of coupling is toward the center.  The big difference is that any outer layer can directly call any inner layer.   With traditionally layered architecture, a layer can only call the layer directly beneath it.  This is one of the key points that makes Onion Architecture different from traditional layered architecture.  Infrastructure is pushed out to the edges where no business logic code couples to it.  The code that interacts with the database will implement interfaces in the application core.  The application core is coupled to those interfaces but not the actual data access code.  In this way, we can change code in any outer layer without affecting the application core.  We include tests because any long-lived application needs tests.  Tests sit at the outskirts because the application core doesn’t couple to them, but the tests are coupled to the application core.  We could also have another layer of tests around the entire outside when we test the UI and infrastructure code.

This approach to application architecture ensures that the application core doesn’t have to change as:  the UI changes, data access changes, web service and messaging infrastructure changes, I/O techniques change.

To the right, I have created a diagram which attempts to show what Onion Architecture would look like when represented as a traditionally layered architecture.  The big difference is that Data Access is a top layer along with UI, I/O, etc.  Another key difference is that the layers above can use any layer beneath them, not just the layer immediately beneath.  Also, business logic is coupled to the object model but not to infrastructure.

To the left here I have attempted to represent traditionally layered architecture using concentric circles.  I have used black lines around the layers to denote that each outer layer only talks to the layer immediately toward the center.  The big kicker here is that we clearly see the application is built around data access and other infrastructure.  Because the application has this coupling, when data access, web services, etc. change, the business logic layer will have to change.  The world view difference is how to handle infrastructure.  Traditional layered architecture couples directly to it.  Onion Architecture pushes it off to the side and defines abstractions (interfaces) to depend on.  Then the infrastructure code also depends on these abstractions (interfaces).  Depending on abstractions is an old principle, but the Onion Architecture puts that concepts right up front. 

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

I encourage you to use the term "Onion Architecture" when speaking about architectures that adhere to the above four tenets.  I believe that this approach to architecture leads to long-lived systems that are easy to maintain.  Also, in my experience, this architecture yields dividends soon after a project starts since it makes the code a breeze to change.

Although I don’t call out an IoC container as a key tenet, when using a mainstream language like Java or C#, an IoC container makes the code fit together very easily.  Some languages have IoC features built-in, so this is not always necessary.  If you are using C#, I highly recommend using Castle Windsor or StructureMap.

part 1. This is part 2. part 3. part 4.  My feed (rss).

In part 1, I introduced an architectural pattern that I have named “Onion Architecture”.  The object-oriented design concepts are not new, but I’m pulling together a lot of techniques and conventions into a single pattern and giving it a name.  My hope is that the industry can use this name to communicate the architectural approach where appropriate.

Part 2:  Practical example:

CodeCampServer uses the Onion Architecture.  If you are looking for a full, working application as an example, please have a look.  The practical example I put before you is taken directly from CodeCampServer.  It is a narrow, vertical slice of an example.  I’m keeping the scope small as to be digestible.  I’ll start with a diagram so you can understand where all the code resides within the layers of the onion.

CodeCampServer uses the ASP.NET MVC Framework, so SpeakerController is part of the user interface.  This controller is coupled to the ASP.NET MVC Framework, and there is no getting around that.  SpeakerController depends on IConferenceRepository and IUserSession (and IClock, but we’ll omit that).  The controller only depends on interfaces, which are defined in the application core.  Remember that all dependencies are toward the center.

Turn your attention to the ConferenceRepository and UserSession classes.  Notice that they are in layers outside of the application core, and they depend on the interfaces as well, so that they can implement them.  These two classes each implement an interface closer to the center than itself.  At runtime, our Inversion of Control container will look at its registry and construct the proper classes to satisfy the constructor dependencies of SpeakerController, which is the following:

public SpeakerController(IConferenceRepository conferenceRepository,
                         IUserSession userSession, IClock clock)
    : base(userSession)
{
    _conferenceRepository = conferenceRepository;
    _clock = clock;
    _userSession = userSession;
}

At runtime, the IoC container will resolve the classes that implement interfaces and pass them into the SpeakerController constructor.  At this point in time, the SpeakerController can do its job.

Based on the rules of the Onion Architecture, the SpeakerController could use UserSession directly since it’s in the same layer, but it cannot use ConferenceRepository directly.  It must rely on something external passing in an instance of IConferenceRepository.  This pattern is used throughout, and the IoC container makes this process seamless.

At the end of this series, I plan on publishing a full working system that adheres to the Onion Architecture pattern.  The systems we build for clients use this approach, but I’m not at liberty to discuss that code, so I will craft a reference application for those of you who prefer a concrete Visual Studio solution to digest.

This is part 1.  part 2. part 3. part 4.  My feed (rss).

I’ve spoken several times about a specific type of architecture I call “Onion Architecture”.  I’ve found that it leads to more maintainable applications since it emphasizes separation of concerns throughout the system.  I must set the context for the use of this architecture before proceeding.  This architecture is not appropriate for small websites.  It is appropriate for long-lived business applications as well as applications with complex behavior.  It emphasizes the use of interfaces for behavior contracts, and it forces the externalization of infrastructure.  The diagram you see here is a representation of traditional layered architecture.   This is the basic architecture I see most frequently used.  Each subsequent layer depends on the layers beneath it, and then every layer normally will depend on some common infrastructure and utility services.  The big drawback to this top-down layered architecture is the coupling that it creates.  Each layer is coupled to the layers below it, and each layer is often coupled to various infrastructure concerns.  However, without coupling, our systems wouldn’t do anything useful, but this architecture creates unnecessary coupling.

The biggest offender (and most common) is the coupling of UI and business logic to data access.  Yes, UI is coupled to data access with this approach.  Transitive dependencies are still dependencies.  The UI can’t function if business logic isn’t there.  Business logic can’t function if data access isn’t there.  I’m intentionally ignoring infrastructure here because this typically varies from system to system.  Data access changes frequently.  Historically, the industry has modified data access techniques at least every three years; therefore, we can count on needing to modify data access three years from now for any healthy, long-lived systems that’s mission-critical to the business.  We often don’t keep systems up-to-date because it’s impossible to do.  If coupling prevents easily upgrading parts of the system, then the business has no choice but to let the system fall behind into a state of disrepair.  This is how legacy systems become stale, and eventually they are rewritten.

I propose a new approach to architecture.  Honestly, it’s not completely new, but I’m proposing it as a named, architectural pattern.  Patterns are useful because it gives software professionals a common vocabulary with which to communicate.  There are a lot of aspects to the Onion Architecture, and if we have a common term to describe this approach, we can communicate more effectively.

The diagram to the left depicts the Onion Architecture.  The main premise is that it controls coupling.  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.   This architecture is unashamedly biased toward object-oriented programming, and it puts objects before all others.

In the very center we see the Domain Model, which represents the state and behavior combination that models truth for the organization.  Around the Domain Model are other layers with more behavior.  The number of layers in the application core will vary, but remember that the Domain Model is the very center, and since all coupling is toward the center, the Domain Model is only coupled to itself.  The first layer around the Domain Model is typically where we would find interfaces that provide object saving and retrieving behavior, called repository interfaces.  The object saving behavior is not in the application core, however, because it typically involves a database.  Only the interface is in the application core.  Out on the edges we see UI, Infrastructure, and Tests.  The outer layer is reserved for things that change often.  These things should be intentionally isolated from the application core.  Out on the edge, we would find a class that implements a repository interface.  This class is coupled to a particular method of data access, and that is why it resides outside the application core.  This class implements the repository interface and is thereby coupled to it.

The Onion Architecture relies heavily on the Dependency Inversion principle.  The application core needs implementation of core interfaces, and if those implementing classes reside at the edges of the application, we need some mechanism for injecting that code at runtime so the application can do something useful.

The database is not the center.  It is external.   Externalizing the database can be quite a change for some people used to thinking about applications as “database applications”.  With Onion Architecture, there are no database applications.  There are applications that might use a database as a storage service but only though some external infrastructure code that implements an interface which makes sense to the application core.  Decoupling the application from the database, file system, etc, lowers the cost of maintenance for the life of the application.

Alistair Cockburn has written a bit about Hexagonal architecture.  Hexagonal architecture and Onion Architecture share the following premise:  Externalize infrastructure and write adapter code so that the infrastructure does not become tightly coupled.

I’ll be writing more about the Onion Architecture as a default approach for building enterprise applications.  I will stay in the enterprise system space and all discussion will reside in that context.  This gets even more interesting when there are multiple processes making up a single software system.