Layered vs Hexagonal vs Onion Architecture
On this page
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 likePlaceOrder). - 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 | Hexagonal | Onion / clean | |
|---|---|---|---|
| Center | Data access at the bottom | Application core | Domain model |
| Business logic depends on | The data layer | Only its own ports | Only inner rings |
| Swapping a database or provider | Touches business code | New adapter | New infrastructure implementation |
| Testing business rules | Needs the database or heavy mocking | Fake adapters, fast | Fake 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.