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.