Hexagonal Architecture — Ports and Adapters, Cockburn’s preferred name — puts domain logic at the center and pushes technology to the rim. The core owns its ports: interfaces for everything that drives it (UI, API, tests) and everything it drives (database, broker, external services). Adapters implement the ports, and source-code dependencies point only inward.

Clean Architecture (Martin) and Onion Architecture (Palermo) restate the same dependency rule as concentric rings; this page covers the family. The hexagon carries no meaning — the rule that the core never names a technology does.

Hexagonal Architecture: the domain core sits inside a hexagon and owns its ports; driving adapters such as web UI and test harness call inbound ports on the left, driven adapters such as database and message broker sit behind outbound ports on the right; all source-code dependencies point inward.

How It Works

  • The domain core holds entities and use cases, free of framework, persistence, and transport imports.
  • Ports take their shape from domain needs, never from adapter APIs.
  • Driving adapters (web controller, test harness) call inbound ports; driven adapters (database gateway, broker client) implement outbound ports.
  • A composition root wires adapters to ports at startup; the core never references an adapter.

Failure Modes

  • Framework or persistence annotations creep into domain types; the boundary survives on the diagram only, and core tests drag infrastructure along.
  • Ports mirror a vendor’s API instead of a domain need, so swapping the technology rewrites the core anyway.
  • An anemic core reduces use cases to pass-throughs: every call pays the indirection while no logic is protected.
  • Domain, persistence, and transport models drift across the mapping layers; a field added in one copy goes missing in another.

Verification

  • An architecture test in CI reports zero imports from the core into frameworks, adapters, or drivers.
  • The core’s unit-test suite runs without database, network, or container — seconds, not minutes.
  • Every driven port has two implementations — production adapter and in-memory fake — passing one shared contract-test suite.
  • Clean Architecture (Martin, 2012) merges Hexagonal, Onion, and BCE into concentric rings under one Dependency Rule.
  • Onion Architecture (Palermo, 2008) centers the rings on the domain model; the inward rule is identical.
  • Layered architecture stacks top-down dependencies; Hexagonal inverts the data layer so the domain owns the interfaces.

References