Hexagonal Architecture - Internal World (The "inside")
Our system core logic shouldn’t be affected by anything external
🚀 Join the ATDD Accelerator waitlist
🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.
Hexagon
The “internal world” is the application itself – its domain logic, the rules that define what the system does and how it behaves.
We want to keep the “internal world” uncontaminated, we don’t want it to be affected by the “external” world (external technologies).
We can think of this as a capsule, called a “Hexagon”. It that defines a clear boundary between the inside and the outside.
Keep your core independent from frameworks, databases, UIs, or any other external systems. This gives you flexibility to change your database, UI, or external APIs without rewriting your business logic.
Driver Ports (User-side API)
On one side of the hexagon, we have Driver Ports — the user-facing entry points into the system.
Our application exists so that it helps clients to run some use cases. Clients could be:
Human users interacting via a UI
Other systems making API calls
Test harnesses simulating real-world behavior
etc…
Driver Ports define what the system can do, not how it does it. Think of them like the “steering wheel” - they let you control the application, but not open the hood.
We want to expose ONLY the use cases to the clients (and NOT expose the internals of the application!).
The Hexagon provides some kind of user-facing API (”driver” ports), so that our clients can execute the use cases.
Driven Ports (Server-side API)
On the opposite side, we have Driven Ports — these are the interfaces that the application needs the outside world to implement.
The application might need to:
Save data to a database
Send an email notification
Publish an event to a message broker
Call an external payment service
etc…
We don’t want to directly be aware of external tech nor directly talk to those external systems, so we need some kind of server-side API.
The internal world should never know which specific technology is used.
