Hexagonal Architecture
Definition
Hexagonal architecture, also called Ports and Adapters, is an architectural style that keeps business logic at the center of the system and isolates infrastructure concerns behind explicit interfaces. The goal is to make the core domain independent from delivery mechanisms such as HTTP, databases, queues, or third-party services.
Core Ideas
- the domain model sits at the center
- ports define what the application needs or exposes
- adapters implement those ports for specific technologies
- external systems plug into the core instead of shaping it
Why Teams Use It
- easier testing of domain logic without real infrastructure
- reduced coupling to frameworks and transport layers
- clearer boundaries between business rules and integration code
- better support for evolving APIs, storage, or messaging choices
Common Adapters
- REST or GraphQL controllers
- database repositories
- message-queue publishers and consumers
- authentication and configuration layers
The source notes also highlight the practical edge: logging, auth, health checks, exception handling, CORS, and similar concerns should exist around the core, not inside it.
The direction vocabulary
Ports and adapters each come in two directions, and the naming triples up because three traditions collided:
| Direction | Port | Adapter | Is |
|---|---|---|---|
| In | inbound / driving | primary / driving / inbound | a REST controller, an MVC controller — something that triggers the domain |
| Out | outbound / driven | secondary / driven / outbound | a database connection, a client for a third-party API — something the domain triggers |
A good port is an interface. That is the whole mechanism: because the outbound port is an interface, swapping an in-memory store for Postgres or DynamoDB means implementing ITicketRepository again with no change to domain logic. A NestJS ticketing example makes the shape concrete — inbound create/findAll for other services, outbound create/find against the store.
Why it arrived with microservices
The pattern became popular alongside the move off monoliths, answering a specific question: what is a good pattern for making microservices flexible enough to talk to each other? Ports and adapters gives each small service a boundary it can keep.
Cockburn’s original 2005 framing states the test directly:
Create your application to work without either a UI or a database so you can run automated regression-tests against the application, work when the database becomes unavailable, and link applications together without any user involvement.
The cost
The honest trade-off: code duplication. Reusing adapters across services, and maintaining similar-but-different model types on each side of a port, is the recurring tax the decoupling charges.
Relationships
- RESTful API — a REST API can be one inbound adapter, not the core application itself
- Software Architecture & Distributed Systems — hexagonal architecture is one of the boundary-shaping approaches in the source notes
- Software Engineering Practices — hexagonal design supports testability and separation of concerns
- Microservices — the decomposition that made the pattern popular
- Databases — swapping the store is the payoff an outbound port buys
References
- _Best Practice of Software Engineering and Architecture
- to be considered in Hexagonal RESTful API