Catalog My learning Blog
System Design Roadmap: 100-Day Course for Engineers · Phase 10 · Lesson 91 · 4 min read

Layered vs Hexagonal vs Onion Architecture

On this page
  1. The business rule that needs a database to test
  2. Layered (n-tier) architecture
  3. Hexagonal architecture (ports and adapters)
  4. Onion and clean architecture
  5. The payoff: testable business rules
  6. When clean architecture is too much
  7. Check yourself

The business rule that needs a database to test

A discount rule ("loyal customers get 10 percent off orders over 100 EUR") lives in an OrderService that calls Entity Framework directly, reads configuration from a static class and sends email through an SMTP client. Testing the rule means setting up a database, a config file and a mail server. So nobody tests it, and nobody dares change it. The three patterns in this lesson all solve the same problem: keep the business rules from depending on the infrastructure around them.

Layered (n-tier) architecture

The familiar shape: presentation → business logic → data access, each layer calling only the one below.

It's easy to understand and fine for simple applications. Its weakness is the direction of dependency: business logic depends on the data layer. Over time, database types, ORM entities and query details seep into business code, and the "business layer" can't run without the database.

Hexagonal architecture (ports and adapters)

Alistair Cockburn's hexagonal architecture puts the business logic, the application core, in the middle and inverts the dependencies:

  • The core defines ports: interfaces describing what it needs (IOrderRepository, IPaymentGateway, INotifier) and what it offers (use cases like PlaceOrder).
  • Adapters on the outside implement them: a PostgreSQL repository, a Stripe gateway, an email notifier, an HTTP controller, a message consumer.

The core depends on nothing outside itself. Infrastructure depends on the core.

Onion and clean architecture

Onion architecture (Jeffrey Palermo) and clean architecture (Robert C. Martin) express the same rule as concentric rings: domain model in the center, then application services, then infrastructure and UI on the outside. Dependencies only point inward. They're popular in .NET as solution templates with Domain, Application, Infrastructure and Web projects, where project references enforce the direction.

Layered architecture points dependencies down toward the database; hexagonal and onion put the domain in the center with dependencies pointing inward.
Layered architecture points dependencies down toward the database; hexagonal and onion put the domain in the center with dependencies pointing inward.
LayeredHexagonalOnion / clean
CenterData access at the bottomApplication coreDomain model
Business logic depends onThe data layerOnly its own portsOnly inner rings
Swapping a database or providerTouches business codeNew adapterNew infrastructure implementation
Testing business rulesNeeds the database or heavy mockingFake adapters, fastFake implementations, fast

The payoff: testable business rules

With the discount rule in the core and its dependencies behind interfaces, the test is a few lines with in-memory fakes and runs in milliseconds. Replacing the payment provider means writing one adapter. Adding a message-queue entry point next to the HTTP API means another adapter calling the same use case.

Test the adapters for real, too. A fake repository proves the rule; it can't prove that your SQL, your EF Core mapping or your migrations work. Run adapter tests against a real database in a container (Testcontainers has a .NET library), and keep fakes for the core.

When clean architecture is too much

For a small CRUD service that mostly moves data between HTTP and a table, rings of projects and interfaces add ceremony without benefit. Use the full structure where business rules are rich and long-lived. A pragmatic middle path, often called vertical slices, organizes code by feature (each use case owns its endpoint, logic and data access) and introduces ports only where a dependency needs isolating.

Two common .NET over-applications. A generic IRepository<T> wrapped around EF Core adds a layer that hides EF's own unit of work and query features while giving the core nothing it needs; EF Core's DbContext already is a repository and unit of work. Define ports by what the use case needs (IOrderLookup.FindOpenOrdersFor(customerId)), not one interface per table. And an interface with a single implementation that will never be swapped or faked is just an extra file.

Check yourself

In layering, business logic depends on the data layer. Hexagonal and onion invert that, so the core depends only on its own interfaces and can be tested and changed independently of infrastructure.

Ports are interfaces the core defines for what it needs or offers; adapters are the outside implementations, such as a database repository or an HTTP controller.

Shape ports around what each use case needs, such as a specific lookup, rather than a generic CRUD wrapper over the ORM, which already provides repository and unit of work.

For small, CRUD-heavy services with little business logic, where most code just maps requests to database rows. There, extra layers, interfaces and mapping add ceremony without making anything easier to test or change. Adopt them where business rules are rich enough to deserve isolation.