Skip to content
Technology transformation expertise firm · ARDIANE Group Innovate, secure, succeed

Glossary

Hexagonal architecture: definition, ports and adapters

Domain

Engineering

In brief

Hexagonal architecture, also called ports and adapters, is a design pattern described by Alistair Cockburn that separates the core of an application from what surrounds it: interface, database, other systems. The application exchanges with the outside through ports, defined by the purpose of the exchange, and each technology plugs into them through a replaceable adapter.

Page contents

Definition of hexagonal architecture

Hexagonal architecture is a design pattern for an application that separates its inside, where the business logic sits, from its outside, where the interfaces, databases and other systems sit. It was described by Alistair Cockburn in a technical report published on his website (alistair.cockburn.us) and dated 2005. The pattern is called “Ports and Adapters” there, with “Hexagonal Architecture” as its other name.

The author’s stated intention fits in one sentence: to allow an application to be driven equally by users, programs, automated tests or batch processes, and to be developed and tested in isolation from the devices and databases it will use in service.

The flaw targeted: business logic mixed with the interface and the database

Cockburn starts from two observations. On the user side, business logic seeps into the interface code: automated tests then depend on display details, and the application can be driven neither by a batch process nor by another program. On the data side, the logic becomes tied to a specific database: when that database is unavailable or replaced, developers are brought to a halt.

He sees a single error in this, the entanglement of business logic and exchanges with the outside, and draws a rule from it: what belongs to the inside must not leak to the outside. Regression tests run without an interface also serve to detect such a leak. Our article on automated testing covers how to organise them.

Ports, adapters, primary side and secondary side

The pattern rests on two notions and one distinction.

  • The port is a conversation between the application and the outside, defined by its purpose and not by a technology. It takes the form of a programming interface.
  • The adapter converts this interface to a given technology, and vice versa. Several adapters can plug into the same port: a screen, a test suite and an HTTP interface on one side, an SQL database, a file or an in-memory substitute on the other.
  • A port is said to be primary when the external actor drives the application, secondary when it is the application that calls upon the actor.

The hexagon does not have six sides out of necessity: according to the author, the figure gives room to draw the ports and breaks with the image of stacked layers. The number of ports is a matter of judgement. Cockburn says he keeps a small number: two, three or four.

Hexagonal architecture, layers and clean architecture: not to be confused

Layered architecture stacks presentation, processing and data. Cockburn criticises it on two counts: the boundaries between layers are not taken seriously, and an application can have more than two ports, which stacking does not represent.

Robert C. Martin’s clean architecture lists hexagonal architecture among the patterns it seeks to bring together. Cockburn’s article deals with the boundary between the application and the outside; Martin’s text additionally orders software into concentric circles subject to a dependency rule, presented in the entry devoted to it.

Finally, the pattern describes an application and its boundary. Splitting a system into separately deployed services is another decision.

Example: a shipping rate calculation and its adapters

Consider an application that calculates the shipping rate for a parcel. Its core contains the calculation rules. A primary port, “request a rate”, receives three adapters: the agents’ screen, an HTTP interface open to e-commerce websites and a suite of automated tests. A secondary port, “read the rate table”, receives two: the company’s database and an in-memory table for tests.

When the company changes database, only one adapter is rewritten, and the calculation tests remain valid. The trade-off is a larger number of interfaces and conversions to write, which can cost more than it brings on an application whose business logic is thin.

The decision to use this pattern is made among the design rules set by IT architecture, and it is applied during custom software development.

FAQ

Frequently asked questions

Another question? Ask us

What is hexagonal architecture?

Hexagonal architecture is a software design pattern described by Alistair Cockburn under the name ports and adapters. The core of the application communicates with the outside only through ports, and each technology (screen, database, other program) connects to them through an adapter. The application can thus be developed and tested without its interface or its database.

Why is it called a hexagon?

The number six has no significance. Alistair Cockburn writes that the hexagon leaves the person drawing room to add ports and adapters, and that it breaks with the diagram of stacked layers. The figure highlights the contrast between the inside and the outside of the application, in place of the contrast between top and bottom.

What is the difference between a port and an adapter?

A port refers to a conversation between the application and the outside, defined by its purpose and expressed in the form of a programming interface. An adapter translates this interface for a given technology. A single port accepts several adapters: for a storage port, an SQL database, a file or an in-memory substitute reserved for tests.

What are a primary adapter and a secondary adapter?

In Alistair Cockburn's article, a primary adapter serves an actor that drives the application: a user, another program, a suite of automated tests. A secondary adapter connects the application to an actor it calls upon, to obtain a response or notify a fact: a database, for example. The distinction depends on who triggers the exchange.

A project to bring to completion?

A first conversation is enough to understand your challenge, identify the right people and tell you frankly what we can bring.