Hexagonal Architecture (Ports & Adapters)

The idea in one minute

Hexagonal Architecture, which its author prefers to call Ports & Adapters, splits an application into two regions: an inside that holds the application logic and an outside that holds everything it talks to. The inside exposes and requires technology-neutral interfaces called ports. Technology-specific adapters plug into those ports from the outside.

Alistair Cockburn stated the goal as letting an application be driven equally by users, programs, automated tests or batch scripts, and be developed and tested in isolation from its eventual run-time devices and databases.^[1] The interesting asymmetry is not left versus right, UI versus database, as in a layered diagram. It is inside versus outside: “the items outside the application can be dealt with symmetrically.”^[1]

Driving side · calls in

CLI adapterEngineer at a terminal

REST adapterFactory MES system

Test driverAutomated tests

→

For configuring devicesApplicationvalidate · diff · write · verifyFor talking to devicesFor storing configurations

→

Driven side · called by the app

CAN bus adapteror Simulator adapter · Real device

JSON file adapteror In-memory adapter · Project files

When it fits

AWS states the trade-off directly: the adapter layer is justified when there are several inputs and outputs or the technology is likely to change; otherwise it is maintenance overhead.^[8]

Ports, adapters and actors

Cockburn usually found two to four ports in an application and noted that choosing a slightly wrong number does little harm.^[1] Group operations by what an actor is trying to achieve, not one port per method.^[6]

Why a hexagon?

The shape has no meaning; “the hexagon is not a hexagon because the number six is important.”^[1] It leaves room to draw several ports and adapters, and it breaks the habit of drawing a one-dimensional stack of layers.

How it differs from Clean and Onion

Martin presented Clean Architecture as a unification of Hexagonal, Onion and similar ideas,^[11] and vendor guides often treat the names as synonyms.^[10] Cockburn’s own book contrasts them: Ports & Adapters specifies only two layers, inside and outside.^[3] In practice that makes it the lighter-weight member of the family. You get the testable core and swappable edges without committing to a particular internal layering.

Worked example: a configuration tool

An illustrative C# sketch: one driving port, two driven ports, several adapters for each.

// Inside: ports owned by the application
public interface IForConfiguringDevices      // driving port (provided)
{
    ApplyResult ApplyProfile(DeviceId id, ConfigProfile profile);
}
public interface IForTalkingToDevices        // driven port (required)
{
    DeviceState ReadState(DeviceId id);
    void WriteParameters(DeviceId id, IReadOnlyList<Parameter> parameters);
}

public sealed class DeviceConfigurator(IForTalkingToDevices devices) : IForConfiguringDevices
{
    public ApplyResult ApplyProfile(DeviceId id, ConfigProfile profile)
    {
        var current = devices.ReadState(id);
        var changes = profile.DiffAgainst(current);      // validate and diff inside
        if (!changes.IsValid) return ApplyResult.Rejected(changes.Errors);
        devices.WriteParameters(id, changes.Parameters);
        return ApplyResult.Applied(changes.Count);
    }
}

// Outside: adapters and the configurator
sealed class CliAdapter(IForConfiguringDevices app)  { /* parse args, call ApplyProfile */ }
sealed class RestAdapter(IForConfiguringDevices app) { /* POST /devices/{id}/profile */ }
sealed class CanBusAdapter(ICanChannel ch) : IForTalkingToDevices { /* frames, timeouts */ }
sealed class SimulatorAdapter : IForTalkingToDevices { /* in-memory device model */ }

IForTalkingToDevices devices = options.UseSimulator ? new SimulatorAdapter() : new CanBusAdapter(channel);
var app = new DeviceConfigurator(devices);   // the configurator decides

Where it is used in practice

• Netflix Studio Workflows. A studio app with entities, repositories (ports), interactors and data sources (adapters). When a data source moved from a JSON API to GraphQL, the team swapped it in about two hours with a one-line change, and data-source choice became configuration. Their suite ran around 3,000 specs in 100 seconds.^[7]
• AWS Prescriptive Guidance. Documents the pattern with a Lambda and DynamoDB sample and a longer guide combining it with commands, handlers and optional CQRS.^[8][9]
• Microsoft’s .NET architecture guide. Describes the same family under the Clean Architecture name for ASP.NET Core applications.^[10]

Gains and costs

How it goes wrong

1. Read as layers. Domain, ports and adapters stacked like N-tier. The pattern has only two regions; ports belong to the inside.^[5]
2. “Ports are just interfaces.” An interface without a purpose, a name and a test double is not a port.
3. One port per method. Fragmented ports that mirror a database API instead of an actor’s goal.^[6]
4. Technology leaking through ports. ORM entities, HTTP or bus details in port signatures; the swap Netflix relied on becomes impossible.
5. Adapters with logic. Validation or rules drifting into the REST or CAN adapter, where tests driving the port never reach them.
6. Fakes that lie. The simulator drifts from the real device, and green tests mean nothing.

Testing through ports

Netflix layered its tests the same way: many interactor tests with mocked repositories, fewer data-source tests checking conformance to the repository interface, and a handful of end-to-end wiring specs.^[7]

Origins

• 1994: Cockburn’s earliest hexagonal drawing, reproduced in the 2024 book.^[3]
• 2005: the article “Hexagonal Architecture”, already subtitled Ports and Adapters, published as a technical report.^[1][2]
• 2008 and 2012: Onion Architecture and Clean Architecture cite it as a shared premise.^[12][11]
• 2024: Hexagonal Architecture Explained by Alistair Cockburn and Juan Manuel Garrido de Paz, who died in April 2024, weeks before it went to print.^[3]