Hexagonal, onion and clean architecture

One idea, three names

Hexagonal architecture, onion architecture and clean architecture are three formulations of one idea: put the business logic at the centre, make it independent of user interfaces, databases, frameworks and external services, and make all source code dependencies point towards it. They describe the internal structure of an application, so they combine with any deployment style: a single monolith, a modular monolith whose modules are each built this way, or a microservice.

They grew out of a frustration with the classic layered architecture. In the layered style of Section 5.2 the business layer depends on the persistence layer, which depends on the database, so business rules end up shaped by tables and object-relational mapping, and testing a rule means starting a database. The family of styles in this section flips that dependency with the dependency inversion principle: the business code declares the interfaces it needs, and the infrastructure code implements them. The principle itself is covered in Section 3.5; this section shows the architectures built on it.

Hexagonal architecture: ports and adapters

Alistair Cockburn first described the idea on the Portland Pattern Repository wiki and wrote it up as an article in 2005 under the more descriptive name ports and adapters. His stated intent was to allow an application to equally be driven by users, programs, automated test or batch scripts, and to develop and test it in isolation from its eventual databases and devices. In 2024 he and Juan Manuel Garrido de Paz published a short book, Hexagonal Architecture Explained, restating the pattern.

A port is a purposeful conversation between the application and the outside world, expressed as an interface: "place an order", "store orders", "charge a card". An adapter is the code that translates between a port and a particular technology: an HTTP controller, a SQL repository, a payment provider's SDK, a command-line script, an in-memory fake. One port can have many adapters. The application inside the hexagon knows only its ports.

The hexagon has no meaning as a shape; Cockburn chose it to escape the top-to-bottom picture of layers and to leave room to draw several ports on each side. What matters is the inside/outside boundary and the asymmetry between two kinds of port.

Driving and driven sides

Driving (primary) ports and adapters sit on the left of the usual picture. A driving adapter receives a request from a primary actor (a user's browser, a mobile app, another system, a test, a scheduled job) and calls a driving port, which is the application's own API: in practice a use case such as PlaceOrder. The adapter turns HTTP, a message or a command-line argument into a call with domain values, and turns the result back into a response.

Driven (secondary) ports and adapters sit on the right. The application calls them when it needs something from the outside world: storing an order, charging a card, sending a notification, reading the time. The port is an interface owned by the application and written in its terms (OrderRepository.save(order)), and a driven adapter implements it for a technology (PostgreSQL, a card provider's API, an SMS gateway). This is where dependency inversion happens: at run time the application calls the adapter, but in the source code the adapter depends on the application's interface, not the other way round.

Cockburn's original text speaks of primary and secondary actors; the terms driving and driven are now more common, and he uses them himself. The distinction matters for testing: driving ports are exercised by test harnesses acting as users, and driven ports are replaced by test doubles. It also matters for change: new channels (a voice assistant, a partner API) arrive as new driving adapters, and new infrastructure arrives as new driven adapters.

Someone has to create the adapters and plug them into the application. That happens in a single composition root, typically the program's start-up code, which is the only part of the system that knows about every adapter. A dependency-injection framework can do this work, but plain constructor calls in main are often clearer.

Onion architecture

Jeffrey Palermo described the onion architecture in a series of blog posts starting in July 2008, aimed at long-lived business applications with substantial behaviour (he advised against it for small websites). He drew concentric rings: the domain model at the centre, domain services around it, application services around those, and an outer ring containing the user interface, infrastructure (including the database) and tests. His key tenets are that the application is built around an independent object model, that inner layers define interfaces which outer layers implement, that all coupling is towards the centre, and that the application core can be compiled and run separately from infrastructure.

Compared with hexagonal architecture, onion adds named rings inside the application and makes explicit a point Cockburn's picture leaves implicit: the database is not the foundation of the system but an external service at the edge. Repository interfaces live in the core; their implementations live in the infrastructure ring.

Clean architecture and the dependency rule

Robert C. Martin published "The Clean Architecture" on his blog in August 2012 as a synthesis of hexagonal architecture, onion architecture and other similar proposals, and expanded it into the book Clean Architecture in 2017. His picture has four rings. Entities hold enterprise-wide business rules. Use cases hold application-specific rules that orchestrate entities. Interface adapters convert data between the form the use cases need and the form external agencies need: controllers, presenters and gateways. Frameworks and drivers form the outer ring: the web framework, the database, the UI.

The dependency rule ties it together: source code dependencies point only inwards, and nothing in an inner ring may name anything declared in an outer ring, whether a class, a function or a data format. When control must flow outwards (a use case saving an order), the inner ring declares an interface and the outer ring implements it. Data that crosses a boundary should be simple structures in the inner ring's terms, never a database row or an HTTP request object. Martin also argues that the top-level structure should reveal the system's purpose (orders, payments, deliveries) rather than its framework, an idea he calls screaming architecture.

A use case with a port and two adapters

The following Python example implements the food-delivery platform's PlaceOrder use case in the hexagonal way. The first snippet is the inside: a small domain class, two driven ports written as typing.Protocol classes, and the use case, which acts as the driving port. The second snippet is the outside: a PostgreSQL adapter and an in-memory test double that implement the same port. The third shows why it matters: a fast unit test, and the composition root where production adapters are plugged in.

from dataclasses import dataclass
from decimal import Decimal
from typing import Protocol

@dataclass
class Order:
    id: str
    total: Decimal
    status: str = "new"

class OrderRepository(Protocol):        # driven port
    def save(self, order: Order) -> None: ...

class PaymentGateway(Protocol):         # driven port
    def charge(self, order_id: str, amount: Decimal) -> bool: ...

class PlaceOrder:                       # driving port + use case
    def __init__(self, orders: OrderRepository, payments: PaymentGateway):
        self.orders, self.payments = orders, payments

    def __call__(self, order_id: str, total: Decimal) -> Order:
        if total <= 0:
            raise ValueError("empty basket")
        order = Order(order_id, total)
        order.status = "paid" if self.payments.charge(order_id, total) else "payment-failed"
        self.orders.save(order)
        return order

class PostgresOrderRepository:          # real driven adapter
    def __init__(self, conn):
        self.conn = conn
    def save(self, order):
        with self.conn.cursor() as cur:
            cur.execute(
                "INSERT INTO orders (id, total, status) VALUES (%s, %s, %s) "
                "ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status",
                (order.id, order.total, order.status))
        self.conn.commit()

class InMemoryOrderRepository:          # test double, same port
    def __init__(self):
        self.saved = {}
    def save(self, order):
        self.saved[order.id] = order

class DecliningPayments:
    def charge(self, order_id, amount): return False

def test_failed_payment_is_recorded():
    orders = InMemoryOrderRepository()
    place = PlaceOrder(orders, DecliningPayments())
    place("A-17", Decimal("23.50"))
    assert orders.saved["A-17"].status == "payment-failed"

# composition root (main.py): the only place that knows every adapter
# place_order = PlaceOrder(PostgresOrderRepository(conn), CardProviderGateway(key))
# app.add_route("/orders", make_rest_controller(place_order))   # driving adapter

Notice what the use case does not contain: no SQL, no HTTP status codes, no provider-specific exception types, no framework decorators. The test runs in milliseconds and covers a case (a declined payment) that would be awkward to arrange against a real provider's sandbox. The PostgreSQL adapter needs its own tests, but those are focused integration tests of one class against a real database, not tests of business rules. This is the testability benefit described in Section 2.6: controllability and observability through injected dependencies.

Costs, criticism and when to use it

The benefits are real, and so are the costs. Every port is an extra interface; every boundary may need mapping code to convert between, say, an ORM entity, a domain object and an API response. For an application that mostly moves form fields into tables with little logic in between, this structure adds files without adding protection, and a framework's conventions (an active-record model, a generated admin interface) may give a better result faster. Some experienced practitioners argue that strict versions of clean architecture produce too much indirection and that most teams never swap their database; others reply that the main payoff is not swapping technology but fast, reliable tests and business code that can be read without knowing the framework. Both are right in different contexts.

Use it when the business logic is substantial and will outlive the current frameworks; when the system integrates with external services that are likely to change; when fast, isolated tests of business rules are important; and as the internal structure of modules in a modular monolith or of services built with domain-driven design (Section 5.7). Be cautious with simple CRUD applications, prototypes and short-lived tools, where the framework's default structure is usually good enough. A pragmatic middle path is common: ports for external services and anything likely to change, and the framework's own conveniences elsewhere.

Enforcing the dependency rule

As with layers, the rule erodes unless a machine checks it. In Python, import-linter can declare the rings as a layers contract (adapters above application above domain) and add forbidden contracts that stop the domain and application packages importing web frameworks, database drivers or SDKs. In Java, ArchUnit has a ready-made onionArchitecture() rule in which you name the domain model, domain service, application service and adapter packages, and it fails a test if any dependency points outwards. Splitting the code into separate build modules (a domain module with no framework dependencies at all) makes outward dependencies impossible to compile, which is the strongest check of all. These checks are examples of the fitness functions covered in Chapter 11.

A package structure that makes the rule visible helps reviewers: for example orders/domain, orders/application (use cases and ports) and orders/adapters/{rest,postgres,payments}. Organising by business area first and ring second keeps the structure aligned with the domain boundaries of sections 5.3 and 5.7.