Hexagonal architecture isn't new. Alistair Cockburn documented it back in 2005. What's changed is what's writing the code today. On my offshore projects in Vietnam, a senior developer working with Claude Code now produces three to four times more lines than two years ago, and without a clear technical boundary, that speed builds coupling at the same pace it builds features.
- 🏗️ Domain protected, business logic depends on no framework or database.
- ⚠️ AI without guardrails, code generated fast by AI worsens coupling with no clear boundary.
- 🔑 Ports and adapters, every input and output passes through an interface defined by the domain.
- 🚀 Field verdict, enforced on my offshore teams, it makes Claude Code more reliable.
I'm not defending hexagonal architecture out of academic purism. I'm defending it because it's become the only safety net that stops quickly generated code from turning your product into intractable technical debt within six months. That's the thesis I want to lay out here, grounded in what I actually see with my clients and in my own teams.
AI made code fast to produce, not less dangerous
A non-engineer can now generate an API endpoint, a SQL query, and a React component in a few minutes using Claude Code or Cursor. What these tools don't generate automatically is the boundary between what belongs to your business logic and what belongs to your infrastructure.
Without that boundary, every direct Prisma call sitting inside a controller, every fetch() dropped in the middle of a business function, quietly piles up. The code works fine in a demo. It becomes unmanageable the moment you want to switch databases, plug in a second frontend, or simply write a test that doesn't depend on a network call.
Vibe coding is great for prototyping and dangerous for building a product without technical oversight. A McKinsey study frequently cited in the industry estimates that technical debt can absorb 20 to 40 percent of a company's IT budget over a system's lifetime, according to McKinsey Digital's research. Code written ten times faster with no architecture doesn't shrink that number. It accelerates it.
Why does vibe coding make invisible coupling worse?
Coupling doesn't break anything the day it's written. It breaks three months later, when switching payment providers forces you to touch forty files instead of two. An AI generating code with no architectural constraint takes the shortest path, not the healthiest one, because that's what the average prompt asks for.
What is hexagonal architecture, in practical terms?
Picture your application as a hexagon. At the center sits the domain: business rules, entities, use cases. Nothing at that center knows PostgreSQL exists, or Stripe, or your frontend framework. Around it sit ports, interfaces defined by the domain itself, describing how it accepts being driven and how it expects its data.
Adapters then plug those ports into the real world: a REST adapter for user input, a PostgreSQL adapter for persistence, a Stripe adapter for payments. The CodelyTV YouTube channel sums up the dependency rule well: infrastructure can know about the domain, never the other way around, and the domain knows only itself.
Alex Hyett, on his channel, traces the term back to its origin: Cockburn noticed that interacting with a database and interacting with an external API always follow the same pattern. Instead of hardcoding that link, you define a contract on the domain side, and any adapter can fulfill it. That inversion is exactly what makes the application's core testable without a database, without a network, without elaborate mocking.
How do ports and adapters actually work?
An inbound port exposes a use case: "create a user." An outbound port describes a need: "persist a user." The domain calls these interfaces without knowing what implements them. Augusto Galego, a senior Brazilian developer, puts it simply in his video: from the business service's point of view, writing to a database or publishing a message to a queue makes no difference at all. Only the contract matters.
Why I'm now enforcing this on my offshore teams
Full disclosure: I run an offshore dev shop in Vietnam, so I clearly have a bias on this topic. That's also exactly why I know its real-world limits, not just the sales pitch you hear in a pre-sales call.
In May 2026, a squad of three Vietnamese developers I oversee migrated a Node backend to a hexagonal architecture in twelve days, then plugged Claude Code into the isolated domain to speed up writing the following use cases. The observed result: the AI's suggestions stayed inside the port it was asked to fill, because the contract forced it to. Without that boundary, the same tool would have suggested importing the Stripe client directly into a commission-calculation function, something a junior developer would have accepted without blinking.
I believe a developer using Claude Code remains an engineer, not a mere prompt operator, as long as the architecture stops them from taking the fastest shortcut. A well-organized senior team, AI-assisted inside a protected domain, produces code that an unstructured team can't catch up to, even with twice the headcount.
What happens when AI writes against a poorly isolated domain?
AI never refuses a bad idea if the surrounding code doesn't structurally forbid it. Without ports or adapters, it mixes business logic and network calls in the same file, because that's the most common pattern in its training data. Hexagonal architecture doesn't make AI smarter. It shrinks the space of mistakes it can make without anyone noticing before production.
Hexagonal, clean, onion: a debate that never really closes
A thread on r/softwarearchitecture, titled "Hexagonal vs Clean vs Onion, which one is truly the most solid?", captures the confusion well. Another developer on the same forum pushes the distinction further in the thread "Layered Architecture != Hexagonal, Onion and Clean Architecture": in their view, classic layered architecture is a macro-architecture that shapes how teams are organized, while hexagonal, onion, and clean mainly describe how to structure the inside of the business layer.
I agree with that framing. These aren't interchangeable competitors, they're variations on the same idea: isolate the business logic, invert dependencies toward that center. The Código Fonte TV channel even points out that the name "hexagonal" comes purely from the diagram Cockburn chose to illustrate it, not from some magic number of six mandatory ports.
"Architecture doesn't protect you against AI. It protects you against developers, human or AI-augmented, who use AI without understanding what they're building."
Vincent Roye, August 2026
| Criterion | Hexagonal | Clean Architecture | Onion | Layered Architecture |
|---|---|---|---|---|
| Framework coupling | Very low | Very low | Low | High |
| Domain testability | High, no heavy mocking | High | High | Depends on the layer |
| Learning curve for junior teams | Medium | High | Medium | Low |
| Resistance to poorly supervised AI code | Strong, explicit contract | Strong | Medium | Weak |
| Migration cost from legacy | Gradual, port by port | High, large rewrite | Gradual | None, it's already the status quo |
SOURCE: r/softwarearchitecture threads, blog.octo.com · UPDATED 08/2026
Do you really have to choose between hexagonal, clean, and onion?
No, and it's a trap to think you have to pick one for good. The OCTO blog, a French reference on the topic, lays out three principles that are enough to get started: explicitly separate user input, business logic, and technical output; point dependencies toward that business logic; isolate boundaries with ports and adapters. These three principles apply whether you call the end result hexagonal, clean, or onion.
The traps that turn hexagonal architecture into overengineering
On an r/androiddev thread, a developer looking for a catalogue of patterns voices a real frustration: too many articles sell hexagonal architecture as a universal solution without ever saying when it costs more than it delivers. They're right to be wary.
On a simple CRUD app with no meaningful business logic, stacking ports and adapters for three entities adds indirection with no measurable payoff. I've seen junior teams spend two weeks building interfaces for a single concrete adapter, which is exactly the opposite of the intended goal.
The rule I apply with my teams is simple: hexagonal architecture is worth it once business logic outweighs plumbing, or once you already know the infrastructure is going to change. A startup that will need to migrate from Firebase to a homegrown backend within eighteen months benefits from isolating its domain from day one. A disposable internal script doesn't need any of this.
The verdict
Hexagonal architecture isn't a box to tick to reassure a client or an investor. It's a choice that decides whether your AI-generated code stays under human control or piles up as invisible debt until the day nobody wants to touch it anymore. I recommend adopting it as soon as a project moves past the prototype stage and its business logic has real value worth protecting.
On the projects I oversee, it's no longer an aesthetic option. It's the condition for senior developers, augmented by Claude Code, to stay more productive and more reliable than a team twice their size without that discipline. For the practical side of implementing this offshore, I go into more detail in our full guide to hexagonal architecture, and if you want to understand where AI genuinely replaces a developer (and where it doesn't), this article picks up the thread directly. On the tooling side of working with AI itself, the AI First blog covers real-world enterprise use cases.
Frequently asked questions
What is hexagonal architecture in one sentence?
It's a way of organizing code that puts business logic at the center and forces every technical dependency (database, API, frameworks) to go through interfaces defined by that center, never the other way around. The domain knows only itself and can be tested without any real infrastructure.
What's the difference between hexagonal architecture and Clean Architecture?
Both share the same principle of inverting dependencies toward the business logic. Clean Architecture, popularized by Robert C. Martin, adds more explicit concentric layers and its own terminology (entities, use cases, interface adapters). In practice, the two are easily interchangeable on a real-world project.
Does hexagonal architecture slow down development when using AI?
It adds a bit of upfront code, mainly the port interfaces. But once the domain is isolated, an assistant like Claude Code produces more relevant suggestions because it's working within a clear contract, with less ambiguity about what belongs to the business logic and what belongs to the infrastructure.
Should you always use a hexagonal architecture?
No. On a disposable script or a CRUD app with no real business logic, the added indirection costs more than it delivers. It's worth it when the domain holds long-term value worth protecting, or when you know a technical component (database, payment provider) will eventually change.
How do you migrate an existing project to a hexagonal architecture?
Gradually, port by port, never as a full rewrite. Start by isolating a use case with high business stakes, define its inbound and outbound ports, plug the existing adapter behind that interface, then repeat on the next component without touching the rest of the system.
Vidéos YouTube
- Hexagonal Architecture: What You Need To Know - Simple Explanation — Alex Hyett
- Learn Hexagonal Architecture in 10 minutes — CodelyTV - Redescubre la programación
- Arquitetura Hexagonal | Explicação de um Dev Sr. — Augusto Galego
- Hexagonal Architecture (Simplified Explanation of Ports & Adapters) // Programmer's Dictionary — Código Fonte TV
Discussions Reddit
- Hexagonal vs Clean vs Onion Architecture — Which Is Truly the Most Solid? — r/softwarearchitecture
- Layered Architecture != Hexagonale, Onion and Clean Architecture — r/softwarearchitecture
- Looking for a pattern catalogue for app architecture — r/androiddev
