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, 81 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
A jump-to index of every table row in this cheat sheet.
An interactive map of every table and concept in this topic.
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 | ||
REST controller, GraphQL resolver, CLI command, message queue consumer | • Adapter that triggers domain logic by calling inbound ports • left-side of the hexagon • converts external requests into domain operations | ||
Database repository, HTTP client, email service, message broker publisher | • Adapter invoked by domain logic implementing outbound ports • right-side of the hexagon • performs infrastructure operations requested by the domain | ||
Domain defines OrderRepository, infrastructure implements it | • High-level modules should not depend on low-level modules • the domain defines interfaces, and infrastructure implements them, reversing traditional dependency flow | ||
Application with one REST API port and three database ports | • The hexagon can have different numbers of ports on each side • not all ports are symmetric or paired • asymmetry reflects real system needs. |