Hexagonal Architecture, also known as Ports and Adapters, is an architectural pattern proposed by Alistair Cockburn in 2005 designed to create loosely coupled applications where the domain logic is completely isolated from external concerns like databases, frameworks, and user interfaces. The core principle is dependency inversion: all dependencies point inward toward the domain, ensuring that business logic remains pure, testable, and independent of technical implementation details. Unlike layered architectures where dependencies often flow downward through layers, hexagonal architecture uses ports (interfaces defined by the domain) and adapters (concrete implementations) to strictly enforce boundaries, making it trivial to swap databases, switch frameworks, or add new delivery mechanisms without touching business rules.
What This Cheat Sheet Covers
This topic spans 15 focused tables and 84 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: Core Concepts and Terminology
Learn this vocabulary first—everything else in the cheat sheet is built on it. The whole pattern rests on a single image: a domain hexagon in the middle, ports as the interfaces it owns, and adapters as the swappable implementations that plug into those ports from the outside. The driving/driven (left/right) distinction is the one most people stumble on, so it's worth pinning down here before moving on.
| Concept | Example | Description |
|---|---|---|
Business logic implementing order validation, payment rules, inventory checks | • The innermost layer containing pure business logic with zero dependencies on external frameworks or infrastructure • all dependencies point inward toward this core | |
interface OrderRepository { save(order: Order): void } | • Interface defined by the domain that specifies what the core needs from external systems • technology-agnostic contract that adapters must implement | |
class PostgresOrderRepository implements OrderRepository | • Concrete implementation of a port that bridges the domain to external technologies (databases, APIs, UIs) • contains all framework-specific code. | |
interface CreateOrderUseCase { execute(data): Result } | • Interface exposed by the domain defining operations that external actors can trigger • represents what the application does. Commands or queries from the outside | |
interface PaymentGateway { charge(amount): boolean } | • Interface required by the domain defining operations it needs from external systems • represents what the application needs. Persistence, messaging, external APIs |