Optivem Journal

Optivem Journal

Hexagonal Architecture

Hexagonal Architecture - Internal World (The "inside")

Our system core logic shouldn’t be affected by anything external

Valentina Jemuović's avatar
Valentina Jemuović
Oct 09, 2025
∙ Paid
3
1
Share

🚀 Join the ATDD Accelerator waitlist


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.

Real-life Example: Ordering System

This post is for paid subscribers

Already a paid subscriber? Sign in
© 2025 Valentina Jemuović, Optivem
Privacy ∙ Terms ∙ Collection notice
Start writingGet the app
Substack is the home for great culture