The idea of this project is to understand and see how we can apply hexagonal architecture in terms of packaging , naming, structure and all concerns that you can face in a real project.
Everything will be covered with test during the process because it has been done doing outside-in tdd.
Hexagonal architecture is an architectural pattern, a way to build and structure your applications in order to obtain testable, loosely-coupled, framework agnostic, domain-centric, easy to evolve and less prone to errors applications.
But hexagonal is not a new trend, it has been here for a while, this kind of architecture was invented by Alistair Cockburn in an made public in an article published in 2005.
It is important to mention that hexagonal, like onion or clean architectures are a family of architectural patterns that rely on a pattern described by Robert C. Martin (Uncle Bob) in 1996, the dependency inversion principle, the D of solid, as a base pattern.
When people talk about code architectures, they usually to talk about layers, but in hexagonal architecture there are no layers, it is all about ports, adapters and of course, dependency inversion.
As we just said, the whole idea is around Ports and Adapters, let's see what they mean ...
This is how a typical hexagonal app looks like:
The core of the hexagon, all the app code lives here, it is isolated from the rest of the world, only dependencies within itself.
-
Domain: The heart of our application, all the business logic, state and behavior.
-
Ports: The boundaries of the hexagon, every communication from/to the outside world to our app will be through these boundaries, they are just interfaces.
-
Driver/left/input: An input port is a simple interface that can be called by the entrypoints (primary actors) and it is implemented by a use case, basically it is the API of the application.
-
Driven/right/output: a simple interface that can be called by our use cases or domain (inside the hexagon) if they need something from the outside (secondary actors, a database access, for instance). Here, we have Dependency Inversion Principle (the “D” in SOLID) in practice.
-
-
Use-cases/application-services: They implement the driver ports, they expose the functionalities of the app , they orchestrate the infrastructure (ports) and the domain to achieve a single business use case. They are stateless.
This layer is where all components outside of our app live, the I/O components UI, database, frameworks, libs , devices, clients... everything but the app core.
-
Adapters: In hexagonal architecture all the primary and secondary actors interact with the application ports through adapters, they are the translators between the domain and the infrastructure.
-
Driver/left/input: Primary adapters or “driving” adapters, they call/use the driver ports to initiate interactions with the app, the entrypoints to the hexagon. Typically http controllers, schedulers, queue consumers, console and many others belong here.
-
Driven/secondary/output: They implement the driven ports of our domain, they adapt any external interaction with the outside world to our domain, they are called from the inside of the hexagon, either the app domain or the usecases. Repository implementations, http-client or queue producers are the most common ones.
-
-
Everything else: Any other class outside the hexagon would belong here, framework related components, configuration ...
Note: Adapters are considered part of the hexagon, but the "outer" section in the infrastructure side.
This is the flow of the calls since an entrypoint gets triggered by an actor.
actor -> driver adapter -> (driver port -> app -> driven port) -> driven adapter -> infrastructure`
|________________|____________________________________|___________________|
Outer Hexagon Inner Hexagon Outer Hexagon
Let's imagine we have a REST service:
- An actor calls our app by http
- Our driver adapter gets triggered
- Adapter calls our app through a driver port (inbound boundary)
- App, that implements the driver port through a use-case wants starts the business and interacts with the domain
- Interactions to the outside world are done through driven ports
- Driven adapter gets called, notice that here the relationship of Port and Adapter is inverted, now the adapter implements the port.
- Finally, the infrastructure, maybe a DB, AWS or Queue resource is hit.
To drive all the project we need a real domain where we can see in a simple and pragmatic way how we can apply this super-useful architectural pattern.
In this example we will implement a simple use-case, a transfer between two accounts of the same bank, and here, our user story:
As a customer of the Bank
I want to transfer money to other customer of this bank
So that, I can make an instant transfer
Having said that, our app will be a simple banking app with one use case, we will try to apply the most simple hexagonal approach that could be extrapolated for a bigger and complex application.
Next diagram shows how our components fit in the hexagon:
Trying to stick on the principles of the original idea of Alistair Cockburn and also influenced by Uncle Bob, we have tried to organize the code around these ideas; this is just a personal approach from the original article, so don't take it as a bible ;).
These are the packages the app, hexagonal does not force to have any package structure , it's all about ports and adapters, but we have tried to go-by-the-book and follow Alistair Cockburn first idea:
`-- com
`-- bank
`-- transfers
|-- app // the inner hexagon
| |-- domain // our domain model
| |-- port // boundaries
| | |-- driver // inbound/left boundary to the hexagon (interfaces), hexagon entrypoint
| | `-- driven // outbound/right boundary to the hexagon (interfaces), hexagon calls to the outside
| `-- usecase // implement driver ports, orchestrators of the app exposed use-cases
`-- infrastructure // outside world
`-- config // framework config & wiring
`-- adapter
|-- driver // use/call driver port interfaces
`-- driven // implement driven ports
You can notice that, we have separated the app from infrastructure, this separation comes from the original
diagrams drawn in 2005, where you have the app, the core of
your hexagon, and then the rest, the IT infrastructure, the composite hardware, software, network resources and
services.
Maybe this an approach is a bit verbose in terms of naming and packaging, but it is made for the sake of understanding the pattern.
Modern approaches are based/inspired on this idea, omitting ports and adapters packages/names, using packaging by package-by-feature or package-by-component.
Hexagonal is also usually mixed with other patterns/approaches such as CQRS, EDA or DDD (like Vaughn Vernon does in his samples of DDD).
Modern layering
It is important to mention that a practical approach and almost a convention in all hexagonal projects is to follow the packaging and layering inspired and used in DDD:
- Application: Application Services (the use cases)
- Domain model: domain and ports
- Infrastructure: adapters
We didn't follow these trends because we wanted to follow the original idea for the sake of explain the architectural pattern.
- Language: Kotlin
- JVM: 1.8.0*
- Web server: Ktor
- Testing libraries/frameworks:
./gradlew test./gradlew build
java -jar build/libs/implementing-hexagonal-architecture-all.jar