Hexagonal architecture

Why: the goal or problem

Imagine a class guide where teachers save schedule pages. Testing its save rule should not require a running web server and database. Replaceable edges matter more than layers alone.

How: work toward a solution

One process: Class Schedule starts unsaved. HTTP or CLI adapters call SaveArticle through its input port.
SaveArticle validates IDs, then calls a memory or embedded-database adapter through SaveRepository. Both storage adapters depend on this application-owned port; the application imports neither implementation.
Saved: 0 → 1; repeat → 1. Invalid IDs or pre-write failure → 0.

Swap edge technology, keep application behavior

Illustrative example

Swap an edge, keep the application

Dani wants to save the Class Schedule · initially unsaved

One process · dotted enclosure

1 · Driving adapters

HTTP
CLI

Imports → input port

2 · Application

Input portSaveArticle

Validate IDs, coordinate saving

Output port · owned hereSaveRepository

3 · Driven adapters

Memory
Embedded database

SaveRepository ← adapter imports

Runtime call

HTTP / CLI
SaveArticle
SaveRepository
Memory / Embedded database

Dashed path: the call reaches storage through the output port; Saved returns to the caller.

The application imports neither adapter implementation. Memory can stand in for the database during a test. Six sides are not six required parts.

Save → repeat: 0 → 1 → 1 entries; return Saved.
From empty: empty IDs or failure before writing → 0. Retry after correction.

HTTP / CLI and memory / embedded database are alternatives; no data migration is implied.

What: the concept

Hexagonal architecture connects an application through ports and technology-specific adapters. Six sides do not mandate six components. Cockburn

Ports add indirection; clean rules can organize policy.

Go further

Optional reading · separate from the overview

Selection & comparison

Choose ports and adapters when the same application behavior must work through different entry points or storage technologies. A test can call the application with a memory adapter before a web server or database exists. Layered architecture may suffice for responsibility separation; clean architecture can add internal policy boundaries. These approaches can coexist. Do not create an interface for every function without a replacement or testing need.

Applications

The class-guide example has an application-owned SaveRepository contract. An HTTP controller and a command-line adapter invoke the same saving operation. A memory adapter supports a fast behavior test; a database adapter supports deployment. Both must honor the same duplicate, invalid-input and failure rules. Replacing an adapter does not migrate existing records or guarantee that a test double matches a database’s behavior.

Implementation & cautions

Read the solid dependency labels separately from the dashed runtime path. A call can travel outward while source dependencies point toward a port owned by the application. Define error and transaction behavior at that boundary, then run contract checks against the real adapter too. Keep domain decisions out of controllers and drivers. Six sides are a drawing convention, not a prescribed count of modules, services or deployments.

Evidence

Alistair Cockburn: Hexagonal architecture ↗
Original ports-and-adapters account explains application isolation and substitutable external connections.
Checked 2026-09-26

Comparison within this category
Concept	Features	Advantages	Limitations	Suitable situations	Combination conditions
Hexagonal architecture	Application ports and external adapters	Test saving with an in-memory adapter	Ports and adapters add indirection	Multiple entry points or storage implementations	Can organize internal policy with clean architecture

Comparison within this category

Concept

Features

Advantages

Limitations

Suitable situations

Combination conditions

Hexagonal architecture

Application ports and external adapters

Test saving with an in-memory adapter

Ports and adapters add indirection

Multiple entry points or storage implementations

Can organize internal policy with clean architecture

Apply this to your project

Starting a project? Describe it to prepare your first prompt.

Create a custom prompt →

Already talking with external AI? Share this article link and explain why the choice fits your project and which tradeoff matters. Ask how it applies to your agreed requirements.

Article link: Hexagonal architecture