Ports & Adapters

"Hexagonal architecture" is Alistair Cockburn's name, and its more descriptive title is Ports and Adapters. The hexagon is just a picture; the substance is two concepts. A port is an interface the application defines for a way it talks to the outside world. An adapter is a concrete implementation of a port for a specific technology. Learn to see every boundary as a port with adapters plugged into it, and the architecture becomes mechanical.

Ports: the application's sockets

A port is an interface owned by the application core, describing an interaction in the domain's own terms - not the technology's. The core defines the shape; it doesn't care who plugs in.

// A port for something the application NEEDS from outside (a "driven"/outbound port)
interface AccountRepository {                 // owned by the core, in domain language
    Optional<Account> findById(AccountId id);
    void save(Account account);
}

// A port for something the application OFFERS to the outside (a "driving"/inbound port)
interface TransferMoney {                     // a use case the app exposes
    TransferResult transfer(AccountId from, AccountId to, Money amount);
}

The hexagon's edges are these ports. Everything inside is pure domain and use cases; everything crossing the boundary does so through a port.

Adapters: the plugs

An adapter implements a port for a specific technology. Multiple adapters can satisfy one port, and that's the point - the core is written once, and you plug in whichever adapter you need:

class JpaAccountRepository implements AccountRepository { ... }        // adapter: Postgres via JPA
class InMemoryAccountRepository implements AccountRepository { ... }   // adapter: a HashMap, for tests
class DynamoAccountRepository implements AccountRepository { ... }     // adapter: swap the DB, core untouched

The core depends on AccountRepository (the port); at runtime, DI wires in JpaAccountRepository for production or InMemoryAccountRepository for a test. Neither the port nor the domain changes. Adapters are where all the framework code lives - JPA, Spring MVC, Kafka clients - quarantined at the edge.

Driving vs. driven

The crucial symmetry Cockburn emphasizes: ports come in two kinds, on two sides of the hexagon.

• Driving (primary/inbound) ports - the ways the outside world drives the application. A REST controller, a CLI, a scheduled job, or a test calls in through a driving port (a use-case interface). The adapter here translates an HTTP request into a use-case call.
• Driven (secondary/outbound) ports - the ways the application drives the outside world. The core calls out through a driven port to save data, send email, or publish an event. The adapter translates the domain's call into a database query or an SMTP message.

   Driving side (inbound)            CORE               Driven side (outbound)
 ┌──────────────┐             ┌──────────────┐         ┌──────────────────┐
 │ REST adapter │──drives──►  │  Use Cases   │ ──uses─►│ JPA adapter      │
 │ CLI adapter  │──drives──►  │  + Domain    │ ──uses─►│ Email adapter    │
 │ Test         │──drives──►  │              │ ──uses─►│ InMemory adapter │
 └──────────────┘             └──────────────┘         └──────────────────┘
   (calls INTO the app)                                (the app calls OUT)

Both sides use ports and adapters, but the dependency still points inward: the driving adapter depends on the use-case port; the core depends on the driven port; the driven adapter depends inward on that port too. The core sits serenely in the middle, depending on nothing but its own interfaces.