So You Think You’re Doing Hexagonal Architecture?

When the repo looks nothing like you expected.

📅 Join me for Acceptance Testing (Live Training) on Wed 25th Feb (17:00 - 19:00 CET) (100% discount for Optivem Journal members)

---

I’ve lost count of how many times I’ve heard this:

“Yeah, this project uses Hexagonal Architecture.”

Then I open the repo.

And immediately feel confused.

Controllers mixed with use cases.
Repositories sitting next to domain objects.
Tests that need half the infrastructure just to run.

I stare at the screen and think: What is going on here?

The problem usually isn’t the architecture.

It’s the folder structure.

The One Mental Model That Finally Clicked for Me

I stopped thinking in terms of “layers”.

Instead, I started asking one simple question:

Is this part of my application’s core—or just a way to talk to the outside world?

Everything in the heart goes into the App folder.
Everything else—adapters, controllers, integrations—lives outside.

Suddenly, the structure made sense.

How I Actually Organize Things

📁 App (Hexagon)
 ├── 📁 Driving Ports
 │    └── 📁 DTOs
 └── 📁 Core
 │    ├── 📁 Application
 │    └── 📁 Domain
 └── 📁 Driven Ports

📁 Driving Adapters

📁 Driven Adapters
 ├── 📁 Real Driven Adapters
 └── 📁 Fake Driven Adapters

Inside a Shipping App—Pro Example

Let’s walk through a shipment.