Trigpoint
Collections › Software & Systems Architecture › Hexagonal architecture (ports and adapters)
“Wrap it in an interface and it is decoupled”: not necessarily.

Hexagonal architecture (ports and adapters)

Hexagonal Architecture (Ports and Adapters) · Cockburn (2005)
Checked against the sources ✓ Software architecture · direction of dependency Read first: Domain-driven design (DDD) Tell the editor privately ▸
In three sentences The core defines its ports in its own vocabulary: what the outside may ask it to do, and what it needs the outside to provide. At run time the core may call out through a port to a database; source-code dependency still always points from the outside in, and the core knows no concrete technology. The criterion: given test inputs and fake adapters, can the core run and have its business rules verified without a real database, user interface or outside service.

↳ Seen a counter-example?

Holds when
When one core must be driven several ways (people, tests, batch runs), or its outside technology needs to be swappable.
Evidence
Conceptual framework; Checked against the sources
Breaks down when
Ports shaped by a tool rather than the core, or used where nothing needs swapping: an extra layer that buys no flexibility.
Hexagonal architecture (ports and adapters) Cockburn (2005) Swap anything outside; the core never knows Adapters: one per technology Ports: declared by the core Core business rules; knows only its ports Primary side people operating it automated tests batch or another app Secondary side database outside systems an in-memory fake arrows = dependency: adapters know the core, never the reverse run time: core → port → DB adapter → database code: DB adapter written to the core's port Figure: trigpoint.pub
Figure 1 · Three layers from the inside out: the core, the ports the core defines, and an adapter for each technology. The arrows show source-code dependency only, not the order of calls at run time. The primary side on the left makes requests; the secondary side on the right is called by the core. Along the bottom, one database access shows the two directions side by side. The layers are conceptual: no hexagon is drawn, and there are no measured numbers. View full size ▸

1. What happened

The symptom the author was addressing is concrete, and it has to do with testing: business logic had seeped into the interface layer, so the system could not be driven by automated tests, and switching from a person operating it to a batch run or a call from another program was difficult.

The root cause is that dependency points the wrong way: the core has come to know about concrete technologies (a particular database driver, a particular user-interface framework). Once that is true, testing the core means standing all of those technologies up first.

This architecture reverses the direction: the core defines the ports, and technologies only write adapters around the outside[1]Cockburn, A. (2005, September 4). The Hexagonal (Ports & Adapters) Architecture. HaT Technical Report 2005.02, v0.9. alistair.cockburn.us/hexagonal-architecture/. Bibliographic details checked against the official record. Claims matched against the full text. Intent, verbatim: “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.”. A port is a purposeful conversation defined by the core and independent of technology, and it comes in two kinds: one says what the outside may ask the core to do, the other says what the core needs the outside to provide. The two sides therefore relate to their ports differently. A primary-side adapter turns a web request, a command line or similar input into a call on the core; a secondary-side adapter is written to a port the core defines, and turns the core's requests into a database query or a call to an outside service.

The two directions are what most often gets confused. When an operation needs data, the call at run time goes from the core out through a port to the database adapter and on to the database, and the result comes back the same way. Source-code dependency runs the other way: the database adapter is written to the core's port, and the core never refers to it. So the core says "save this article", not some database client's insert command; and testing the core means attaching one fake in-memory adapter.

The statement of intent in the original is worth keeping word for word: allow an application to be driven equally by users, programs, automated tests or batch scripts, and to be developed and tested in isolation from its eventual runtime devices and databases[1]Cockburn, A. (2005, September 4). The Hexagonal (Ports & Adapters) Architecture. HaT Technical Report 2005.02, v0.9. alistair.cockburn.us/hexagonal-architecture/. Bibliographic details checked against the official record. Claims matched against the full text. Intent, verbatim: “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.”.

Cockburn's 2005 report stresses symmetry: the diagram has no upper and lower layers, and database and user interface alike are merely external technologies attached to some port. What separates the primary side (what drives the core: people, tests, batch) from the secondary side (what the core calls: databases, outside systems) is who triggers and is in charge of the conversation, not architectural rank[1]Cockburn, A. (2005, September 4). The Hexagonal (Ports & Adapters) Architecture. HaT Technical Report 2005.02, v0.9. alistair.cockburn.us/hexagonal-architecture/. Bibliographic details checked against the official record. Claims matched against the full text. Intent, verbatim: “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.”. The symmetry holds only in the diagram, though: interviewed in 2020, the author said that driver-side and driven-side adapters could not, in the end, be written the same way, so his quest for total symmetry failed[5]Garrido de Paz, J. M. (2020, September 9). Interview with Alistair Cockburn. jmgarridopaz.github.io/content/interviewalistair.html. Bibliographic details checked against the official record. Claims matched against the full text. The author, interviewed and speaking in the first person: he first drew the hexagon in 1994, in notes for his object-oriented programming class; he first published it without the Ports and Adapters name; only in June 2005 did he see that each side of the hexagon is a port, and the same month he created a wiki page under the name Ports and Adapters. What he saw was ports and adapters, not symmetry. He also said that driver-side and driven-side adapters could not, in the end, be written the same way, which ended his quest for total symmetry..

2. Why this matters to you

Swap technology for tools and models and this page turns into a very practical piece of advice: your criteria should not be bound to any one tool.

Many people's workflows run the other way, with the criteria living inside the tool. Prompts written into one platform's project settings, classification rules written into one note application's fields, checklists stored as one service's templates. That is entirely fine while the single tool suits you, right up until you change tools, or want to do the same thing with a second one, or that tool changes what it offers.

What this architecture does is reverse the direction: the criteria live in a place of your own, declared in your own vocabulary as what inputs and outputs I need, and each tool then gets a thin layer of attachment. Change tools and you change the attachment. The criteria do not move. Conversely, if you do this in one tool only and have no plan to switch, writing the criteria down clearly is enough; there is no hurry to build attachments for it.

It also gives you a testable criterion, which is the most valuable part of this page. The question is not do I have decoupling (that question has no answer). The question is: can my criteria be stated clearly and carried out by a person with no particular tool present. If your classification rules only make sense with reference to one application's fields, they are already bound.

The fake decoupling is worth guarding against too. You wrap a layer around the tool, and the shape of that layer follows the tool exactly: your spec, say, is full of one platform's proprietary terms. Formally that is one more layer. In substance nothing has been bought, because changing tools means rewriting the layer entirely. The shape of a port has to be settled by the core, and that is the sentence in the principle that gets skipped most easily.

Verification layer · Members
The guided layer of this node is open to all readers.
Verification details and failure boundaries are for members.
US$8.25 a month on average · or subscribe monthly ▸

Lab cases Written only where there is evidence

No field record for this node yet.

Common misreadings

Page verification: Checked against the sources ✓ · Content last revised 2026-11-15

  • A common account says the six sides stand for six layers or six kinds of port. The hexagon is only a drawing convenience: the author chose it to leave room for drawing several ports, without being constrained by a one-dimensional layered drawing. Counting the sides misses the point. As for the name, Cockburn's 2005 report gives Ports and Adapters as the pattern's name and lists hexagonal architecture as an alternative; by the author's own account in a 2020 interview, he had drawn the hexagon by 1994 and took up the name Ports and Adapters only in June 2005. The original also describes it as a particular use of the Adapter pattern and lists several closely related existing patterns, so this site marks the author as the one who put it forward and named it, not as an originator without precedent. #
  • A common account says onion architecture and clean architecture are derivatives of this one. The three are one family by different authors, each named separately, and what they share is the principle that dependency points only inward. Do not mix up the attributions. #
References

How to read the source notes “Bibliographic details checked” means author, year, title and venue were confirmed. It does not mean the source's claims were checked. “Matched against the full text” means the claim was compared with the text of the source itself. Definitions as of 2026-09-20.

  1. [1] Cockburn, A. (2005). The Hexagonal (Ports & Adapters) Architecture. HaT Technical Report 2005.02. alistair.cockburn.us/hexagonal-architecture/ ↩
  2. [5] Garrido de Paz, J. M. (2020). Interview with Alistair Cockburn. jmgarridopaz.github.io/content/interviewalistair.html ↩

↳ Is a citation wrong?

Tell me when a new shelf opens

Tell me when a new shelf opens

Shelf notices are sent only when a new shelf opens or when the reading rules change.

Trial

Tell the editor privately: a correction, a counter-example or where it applies

Submissions are read only by the editor, and nothing is published before they are handled. Once a note is handled, a summary and response written by the editor are published. No sign-up is needed, and the nickname may be left blank.

What are you submitting?
Set a public name to be credited by name ▸
Submit anonymously, without signing in

Signing in lets you follow the status on your page. What you have written is kept.

You are signed in: this note is linked to your account, visible only to you and the editor, so you can follow its status on your page. The text is never published. Full privacy policy ▸

Submit anonymously instead, not linked to your account ▸

No email is collected. Your original text and nickname are read only by the editor and are never published; the site publishes only a summary the editor writes. The human check is provided by Cloudflare Turnstile. To limit abuse, the system keeps a hash of your IP address, not the address itself. Your original text is stored with our cloud provider and can be deleted on request. Full privacy policy ▸