Hexagonal Architecture
Coined by Alistair Cockburn
Hexagonal architecture, also known as Ports and Adapters, is a software architecture pattern that isolates an application's core business logic from external concerns (databases, UIs, APIs, messaging systems) by defining explicit…
Definition
Hexagonal architecture, also known as Ports and Adapters, is a software architecture pattern that isolates an application's core business logic from external concerns (databases, UIs, APIs, messaging systems) by defining explicit interfaces ('ports') that any external technology must implement via 'adapters'.
Overview
Hexagonal architecture was coined by Alistair Cockburn in the early 2000s to address a recurring problem: business logic that becomes tightly entangled with infrastructure code — database queries, HTTP handling, UI frameworks — making it hard to test in isolation, hard to swap technologies, and hard to reason about which code represents actual business rules versus incidental technical plumbing. The pattern's central image is a hexagon (chosen arbitrarily to allow room for multiple sides/ports rather than implying exactly six) with the application's core domain logic at the center, surrounded by 'ports' — abstract interfaces defined by the core that express what the application needs from or offers to the outside world (e.g., 'a way to persist orders,' 'a way to notify customers'). External technologies connect to these ports through 'adapters' — concrete implementations that translate between the port's abstract interface and a specific technology. A 'driving' (primary) adapter, such as a REST controller or CLI handler, calls into the application core to trigger use cases; a 'driven' (secondary) adapter, such as a database repository implementation or an email-sending client, is called by the application core to fulfill its needs. Crucially, dependencies point inward: the core knows nothing about any specific adapter or technology, only about its own port interfaces, which is the same Dependency Inversion Principle that underlies the Repository pattern and clean architecture. The practical payoff is testability and flexibility: the application core can be tested with fast, in-memory fake adapters instead of a real database or network call, and swapping a technology (moving from a REST API to a message queue, or from PostgreSQL to a different database) means writing a new adapter without touching business logic. Hexagonal architecture is closely related to, and largely a predecessor of, Robert C. Martin's Clean Architecture and Jeffrey Palermo's Onion Architecture — all three describe the same core idea (dependencies point inward toward domain logic, infrastructure is pluggable at the edges) with different visual metaphors and terminology, and are often discussed together as variants of the same 'dependency inversion at the architecture level' family of patterns.
Key Concepts
- Isolates core business logic from external technologies via explicit interfaces ('ports')
- External technologies connect through 'adapters' that implement the ports
- Distinguishes 'driving' (primary) adapters that call into the app from 'driven' (secondary) adapters the app calls out to
- Dependencies point inward — the core has no knowledge of specific adapters or technologies
- Enables testing business logic with fast in-memory fake adapters instead of real infrastructure
- Makes swapping technologies (databases, messaging, UI) possible without touching domain logic
- Closely related to Clean Architecture and Onion Architecture (same core principle, different terminology)
- Coined by Alistair Cockburn in the early 2000s