Hexagonal Ports and Adapters
The hexagonal pattern isolates the domain at the center with ports for every external interaction, so the domain is testable and substitutable by swapping adapters without touching the core.
Definition
The hexagonal ports and adapters pattern places the domain logic at the center with symmetric ports — driving ports for inbound, driven ports for outbound — and adapters that implement those ports against specific technologies, so that the domain is independent of infrastructure and both sides are substitutable.
Context and scope
Applied in domain-driven design, testable architectures, and any system where the domain must be tested in isolation and the infrastructure must be swappable.
Common misconceptions
- Ports are interfaces — ports are intent-driven interfaces owned by the domain; an interface owned by the infrastructure is not a port
- The hexagon has six sides — the name is about symmetry, not a literal six; the number of ports is the number of interactions
Anti-patterns
- Putting a port in the infrastructure layer so the domain depends on infrastructure, inverting the pattern
- Using one port for every external concern, so the domain cannot distinguish a database from a notifier and cannot express different intent
Related concepts
Authoritative source
What it is
The hexagonal ports and adapters pattern places the domain logic at the center with symmetric ports — driving ports for inbound, driven ports for outbound — and adapters that implement those ports against specific technologies, so that the domain is independent of infrastructure and both sides are substitutable. Applied in domain-driven design, testable architectures, and any system where the domain must be tested in isolation and the infrastructure must be swappable. The organizing principle is which decisions are hard to reverse and should be made once, versus which are easy to reverse and should be deferred.
How it works
Boundaries are drawn along axes of change: things that change together are colocated, things that change independently are separated by interfaces whose contracts are explicit and versioned. Dependencies point toward stability — domain logic depends on abstractions, infrastructure depends on domain, never the reverse. The structure makes the system’s intent legible without reading every module.
When to choose and pitfalls
Choose this structure when the system will outlive its first deployment and face requirements you cannot now predict. The pitfall is premature abstraction — adding indirection for a flexibility that never materializes, paying its complexity cost forever. The opposite pitfall is entangling concerns that later need to separate, forcing a rewrite instead of a refactor.