The original article where Alistair Cockburn describes Hexagonal architecture is the best intro and a good read, no matter what year it is.
First and worst, people tend not to take the “lines” in the layered drawing seriously. They let the application logic leak across the layer boundaries
made me think that I want a linter for verifying that the code that is written does not violate the architecture boundaries, and that for example a port never uses a use case, but only the other way around.
Welcome ArchUnit. As I learned in @Ted's video there is ArchUnit which allows writing unit tests for exactly this, in Java. Fun fact, ArchUnit is maintained by TNG, a Munich-based company, around the corner, an active Munich community member 👋🏽 over. (Soon we will all be back in person.)
Back to hexagonal architecture as such.
Primary and Secondary Actors
Alistair observed in applications he built, that there are two types of actors.
A "primary actor" is an actor that drives the application [...].
A "secondary actor" is one that the application drives
These actors are also reflected in what the hexagonal architecture diagram looks like.
draw the "primary ports "and" primary adapters" on the left side (or top) of the hexagon, and the "secondary ports" and "secondary adapters" on the right (or bottom) side of the hexagon
In the video linked below, he says that the difference between a primary and a secondary actor is just "who initiates the conversation". The one who does is the primary actor.
"How Many Ports?"
The headline is actually from his article and was one of the questions I had too.
What exactly a port is and isn’t is largely a matter of taste.
Still he gives some good example. Where a port is something as abstract like "trigger data" or "incoming events" or alike. These can be multiple things, depending what the system does. But it shows a very abstract kind of port. In another example he uses "user-site API" for the incoming data (primary port) and "data-side API" for the outgoing (secondary port).
I read this as "think about it yourself and it might be very different for every app". As usual, there is no one silver bullet.
Alistair in the "Hexagone" 1/3 (youtube video, >30min)
Alistair Cockburn talking (the first time) about Hexagonal Architecture he takes the magic out of the word "ports" by:
What's a "port"? It's an interface. Done
A "translation" of port, or how to find what to call the port is fill the gaps in "for ___ing", or as he says around minute 12 a "port is the intention of the dialog, it's not the technology" That's why a port might be called "adding events" but never "reading kafka".
The Test Case is the First User of your System
"A test case is the first user of your system" That makes even so much more sense when you know hexagonal architecture. Alistair says in the video around minute 29.
Initially I started reading because I want to find a good example of how someone uses React and hexagonal architecture. Yes, there are many examples which show how flux and redux are hexagonal architecture. But I feel these are too often used in a way to create "store all things in global state and call it a redux store". I have not seen really good encapsulated examples of that yet.
In Depth Post
Hexagonal Architecture: three principles and an implementation example
This post contains helpful explanations and also good example code. It even explains how to organize the code inside a method that works with ports, adapters etc.
Alistair Cockburn, Part 2 and 3
Very good 1h in depth
More Testable Code with the Hexagonal Architecture is a very detailed and well explained lesson. Also explaining many related terms. By @Ted M. Young.
A must see
It took me years to understand what he means with this. I mean I get the words, the logic, I get the reasoning, but how to do it and understanding that there is still a lot to learn before accomplishing this, it is not easy. A Classic J.B. Rainsberger - Integrated Tests Are A Scam he sientifically proves why splitting up code, e.g. using hexagonal architecture, pays off.
More Input from Output
Searching for "hexagonal architecture" on twitter reveals constantly new and interesting pieces of knowledge.