You are looking for an offshore vendor and every single one promises "clean code." The problem is that nobody defines "clean" the same way. I have seen projects delivered by consulting firms that passed unit tests, yet had business logic glued directly to Spring Boot, MySQL, and Kafka to the point where switching databases took three sprints. Hexagonal architecture is the filter that separates structured teams from teams that wing it.
When I manage a team in Vietnam on a SaaS project, the first question I ask is not "what framework?" but "how do you isolate the domain?" The answer reveals more than any portfolio.
- 🏗️ Isolated domain: business logic depends on neither the framework nor the database.
- ⚡ Tests 3x faster: the core is tested without infrastructure, in seconds.
- 🎯 Change without breakage: swapping MySQL for MongoDB touches one adapter, not the business logic.
- ✅ Selection criterion: a vendor who applies this pattern ships with less technical debt.
What is hexagonal architecture (and why that name)?
Hexagonal architecture was formalized by Alistair Cockburn in 2005. Its other name, "Ports and Adapters," better describes the actual mechanism. The term "hexagonal" simply comes from the diagram used to represent it: a hexagon at the center (the business logic), surrounded by connectors to the outside world. Cockburn himself noted that the number of sides carries no technical significance, according to the dedicated page on Wikipedia.
Why separate the domain from everything else?
The core principle fits in one sentence: dependencies always point toward the center, never outward. Your business logic (price calculation, order validation, workflow orchestration) has no idea whether it is running inside a REST controller, a Kafka handler, or a JUnit test. It says "I want to save this order" through a port (an interface). The adapter (JPA, MongoDB, in-memory) handles the concrete implementation.
This inversion of dependencies, known as the Dependency Inversion Principle (the D in SOLID), creates a clean boundary. On one side, stable business rules. On the other, infrastructure that changes according to needs, cost constraints, or client decisions.
The practical result: when a client asks to migrate from PostgreSQL to DynamoDB (it happens more often than you would think on high-growth SaaS projects), the team replaces one adapter. Not the business service. Not the domain tests. Not the use cases.
How do ports and adapters work?
Input ports define what the application knows how to do: create an order, cancel a payment, generate an invoice. These are interfaces that expose business use cases.
Input adapters translate external requests into those ports. A REST controller, a Kafka consumer, a gRPC endpoint: they all call the same port. The domain sees no difference.
On the output side, output ports declare what the application needs: persist data, send an email, publish an event. Output adapters implement those interfaces: a JPA repository, an SMTP client, a Kafka producer.
The domain knows only abstractions. Technical details are interchangeable. This is what makes the architecture framework-agnostic, a considerable advantage when you work with a structured offshore team.
Hexagonal vs layered vs Clean Architecture: the real differences
Most articles on the subject list generic "benefits." The on-the-ground reality is more interesting, because all three architectures (classic layers, hexagonal, Clean Architecture) start from the same observation but diverge in execution.
What are the concrete advantages over layered architecture?
The layered architecture (Controller → Service → Repository) that every Spring Boot developer learns first has a structural flaw: dependencies flow downward, and business logic ends up depending on infrastructure. Your service imports JPA annotations, your business entity extends a Spring class, your unit tests need a live database to run.
According to OCTO Technology's guide on the subject, hexagonal architecture reverses this flow: the domain depends on nothing; everything else depends on it. Core tests execute in milliseconds, with no Docker, no database, no complex mocking.
On projects I manage, this difference produces a measurable ratio: integration tests on the JPA adapter run in 8 to 12 seconds; domain tests run in under 500 ms. When your CI pipeline drops from 4 minutes to 45 seconds on the business logic layer, the team pushes code more often and with more confidence.
How does hexagonal differ from Clean Architecture and DDD?
Uncle Bob's Clean Architecture (Robert C. Martin) and hexagonal architecture converge on one point: isolating business logic at the center. The difference lies in the level of prescription. Clean Architecture mandates four concentric layers (Entities, Use Cases, Interface Adapters, Frameworks and Drivers) with strict traversal rules. Hexagonal is simpler: two zones (inside and outside) connected by ports.
Domain-Driven Design (DDD), for its part, is not an architecture. It is a method for modeling business logic (aggregates, value objects, bounded contexts) that pairs very well with hexagonal. As Yield Studio notes in its guide, the two concepts reinforce each other without being necessarily tied together.
In practice, I recommend starting with pure hexagonal (ports and adapters) and adding DDD patterns (aggregates, typed repositories) only when business complexity justifies it. On a CRUD app with 5 entities, DDD is over-engineering. On a pricing engine with 20 business rules, it is indispensable.
| Criterion | Layered architecture | Hexagonal architecture | Clean Architecture |
|---|---|---|---|
| Domain isolation | Low (framework annotations in the service) | Strong (ports and adapters) | Very strong (4 prescribed layers) |
| Core testability | Slow tests (database required) | Fast tests (in-memory adapters) | Fast tests (same principle) |
| Learning curve | 1 day | 1 to 2 weeks | 2 to 4 weeks |
| Suitable for a simple CRUD | Yes | Often excessive | Excessive |
| Suitable for a complex SaaS | Risky over time | Yes | Yes |
SOURCE: GoLive Software field synthesis, updated 06/2026
How to implement hexagonal architecture in practice
The theory is compelling. Implementation is where most teams fall apart. Here are the concrete points that make the difference between hexagonal architecture on a slide deck and hexagonal architecture in production.
What package structure should you adopt?
The most common package structure separates three root folders: domain/, application/, and infrastructure/. The domain folder contains business entities, value objects, and ports (interfaces). The application folder contains the services that orchestrate use cases. The infrastructure folder contains the adapters (REST controllers, JPA repositories, HTTP clients).
The golden rule: no import from infrastructure in domain or application. If your IDE shows an import of org.springframework inside the domain package, the architecture is broken. According to Numendo's practical guide, this dependency discipline is the only thing that truly matters.
How do you handle testing with this architecture?
Tests split naturally into two families. Domain tests use in-memory adapters (a simple HashMap implementing the persistence port). They cover all business logic, run extremely fast, and require no infrastructure whatsoever.
Integration tests verify that concrete adapters actually work: the JPA repository persists to the database, the HTTP client calls the right endpoint, the Kafka producer publishes to the right topic. These tests are slower, but their scope is limited.
On a recent project delivered by our Vietnam team for a logistics management SaaS, this separation produced a result I rarely see from other vendors: 92% domain coverage, executed in 3 seconds. Integration tests ran in 25 seconds via Testcontainers. The full pipeline completed in under 2 minutes.
That is not a minor detail. A slow pipeline pushes developers to skip tests or push less frequently. A fast pipeline creates a virtuous cycle of quality. It is an argument I make when evaluating the selection criteria between agencies and consulting firms: the speed of the technical feedback loop is a maturity signal that is invisible in quotes.
Should hexagonal architecture be applied to every project?
No. And that is a point many articles sidestep. For a simple CRUD application (an admin back-office with 5 screens), classic layered architecture is faster to set up and perfectly adequate. Hexagonal makes sense when business logic is complex, when you anticipate infrastructure changes, or when multiple teams are working on the same domain.
According to a 2024 Gartner study, 64% of software projects that exceed 18 months of development undergo at least one major infrastructure change (cloud migration, database switch, replacement of a third-party service). On that type of project, hexagonal pays back its initial investment at the first technical pivot.
"Quality comes from architecture, technical choices, tests, and execution discipline, not from headcount."
Vincent Roye, June 2026
How to verify that a vendor actually masters hexagonal architecture
You are about to sign with a consulting firm or an offshore agency, and the salesperson swears the team "does hexagonal." Here are the five questions that separate real practitioners from slide-deck vendors.
What questions should you ask before signing?
Question 1: "Show me an import graph from your last project." If the domain package imports Spring, Hibernate, or any framework, the answer is clear. A serious vendor can produce that graph in 5 minutes with a tool like ArchUnit or jdeps.
Question 2: "How long do your domain tests take to run?" Expected answer: a few seconds. If the answer is "we need Docker to run the tests," the adapters are mixed in with the business logic.
Question 3: "If I ask you to swap PostgreSQL for MongoDB tomorrow, which files change?" Expected answer: only the persistence adapters. If the answer starts with "we refactor the services," the architecture is layered in disguise.
Question 4: "Where does the business logic live in your directory tree?" Expected answer: a domain/ folder (or core/, hexagon/) with zero dependencies on infrastructure. If the vendor shows you Spring services annotated with @Service that contain calculation rules, that is a red flag.
Question 5: "Are your domain entities the same as your JPA entities?" Expected answer: no. The domain model and the persistence model must be distinct. Using the same class for both creates invisible coupling that explodes at the first schema change.
These five questions take 15 minutes on a technical call. They save you months of technical debt. It is an investment I recommend systematically, on the same level as a technical audit of existing code.
My verdict: what I apply at GoLive Software
I apply hexagonal architecture to every SaaS project my Vietnam team delivers, except for pure CRUD back-offices where it would be over-engineering. This is not a theoretical choice; it is an economic one.
On our projects, the Ports and Adapters pattern combined with senior Vietnamese developers and AI tools like Claude Code produces a concrete result. The domain is testable in isolation, adapters are interchangeable, and when a client changes their mind about infrastructure (and they always do), the team pivots in days, not weeks.
I believe the real difference between an offshore vendor that ships quality and one that accumulates technical debt comes down to these architecture choices. Not the framework. Not the language. The discipline of separating business logic from infrastructure. Hexagonal architecture is not a trend; it is the baseline for any project that needs to survive beyond 18 months.
If you are evaluating a vendor, ask the five questions above. If you are looking for a team that applies this standard in production, estimate your project with GoLive Software.
Frequently asked questions
What is hexagonal architecture in one sentence?
A software architecture pattern that places business logic at the center and connects it to the outside world (databases, APIs, interfaces) through ports (interfaces) and adapters (implementations). Invented by Alistair Cockburn in 2005, it is also known as "Ports and Adapters." Its goal: make the application core completely independent of the technology stack.
Is hexagonal architecture suitable for a small project?
For a simple CRUD with little business logic, classic layered architecture is faster to set up and fully adequate. Hexagonal comes into its own when business logic is rich (calculation rules, workflows, cross-entity validation) or when you anticipate infrastructure changes. The initial overhead pays for itself at the first technical pivot.
What is the difference between hexagonal architecture and Clean Architecture?
Both isolate the domain at the center. Clean Architecture (Robert C. Martin) prescribes four concentric layers with strict traversal rules. Hexagonal is more pragmatic: two zones (inside and outside) connected by ports and adapters. In practice, teams often blend both approaches depending on project complexity.
How do you test an application built on hexagonal architecture?
Domain tests use in-memory adapters (a simple HashMap as a fake repository) and run in seconds, with no Docker or database. Integration tests verify the concrete adapters (JPA, Kafka, HTTP) using tools like Testcontainers. This separation produces a fast CI pipeline and high business-layer coverage.
How can I tell if my vendor is truly applying hexagonal architecture?
Ask for the import graph of the domain package: no framework imports should appear there. Ask how long the domain tests take to run (expected answer: a few seconds). Ask which files would change if the database were swapped out (expected answer: only the adapters). These three checks take 15 minutes and reveal the team's actual level.
Vidéos YouTube
- Architettura esagonale spiegata in 10 minuti — codippa
- What is Hexagonal Architecture? — 4SoftwareDevelopers
- Hexagonal Architecture: Make your code independent — Del Código a la Arquitectura
- Hexagonal vs Clean vs Onion Architecture... It Doesn't Matter — CodeOpinion
Articles & ressources
- Architecture hexagonale — fr.wikipedia.org
- Architecture Hexagonale : trois principes et un exemple d'implémentation — blog.octo.com
- Le Guide Ultime pour Maîtriser l'Architecture Hexagonale — scalastic.io
- L'Architecture Hexagonale : principes, avantages et implémentation — numendo.com
- Architecture Hexagonale : Guide Complet — yieldstudio.fr
