Most applications start clean. Then business logic bleeds into the database layer, UI code wraps around domain rules, and swapping a single dependency means rewriting half the codebase.
That’s the exact problem hexagonal architecture was built to solve. Also called the ports and adapters pattern, it isolates your application core from every external system it touches.
So what is hexagonal architecture, and why are companies like Netflix and PayPal using it to structure their services? This guide covers how ports and adapters work, how hexagonal architecture compares to clean and onion architecture, what a real project structure looks like, and where the pattern actually pays off versus where it adds unnecessary overhead.
What is Hexagonal Architecture
Hexagonal architecture is a software design pattern that separates an application’s core business logic from its external dependencies. Databases, user interfaces, APIs, message queues. None of them touch the core directly.
Alistair Cockburn created the concept in the mid-1990s, initially posting about it on the Portland Pattern Repository wiki. He formally renamed it “Ports and Adapters” in 2005, though the original name stuck. In April 2024, Cockburn published a full book on the subject with co-author Juan Manuel Garrido de Paz.
The “hexagonal” shape is symbolic. It doesn’t mean there are six sides or six ports. Cockburn chose the hexagon because it provided enough visual space to represent multiple interfaces between the application and the outside world.
Here’s the basic idea: your application talks to external systems through ports (interfaces it defines) and adapters (implementations that connect those interfaces to real technology). The core doesn’t know what’s driving it or what it’s driving.
This separation solves a specific problem that plagues traditional layered architecture. In many applications, business logic gets contaminated by database code, UI concerns, or framework-specific details. Hexagonal architecture prevents this by design.
Netflix adopted hexagonal architecture across its studio engineering teams. According to the Netflix Technology Blog, the pattern allowed them to swap data sources with a one-line configuration change, without touching any business logic. They migrated an entire service from one persistence layer to another in a fraction of the time a traditional architecture would require.
A 2024 vFunction study found that 44% of organizations struggle with monolithic complexity caused by unclear domain boundaries and decreasing modularity. Hexagonal architecture directly addresses this. It forces clean separation from day one.
How Ports and Adapters Work
Ports and adapters are the two structural building blocks that give hexagonal architecture its power. Without understanding them, the rest of the pattern doesn’t click.
Ports are interfaces defined by the application core. They describe what the application needs or offers. No implementation details, no framework references. Just contracts.
Adapters are concrete implementations that plug into those ports. They handle the messy reality of databases, HTTP requests, third-party APIs, and file systems. You can swap one adapter for another without changing a single line inside the core.
| Concept | Role | Example |
|---|---|---|
| Port (Driving) | Receives input from outside | UserService interface |
| Port (Driven) | Reaches outward from core | UserRepository interface |
| Adapter (Driving) | Translates external requests | REST controller, CLI handler |
| Adapter (Driven) | Connects to infrastructure | PostgreSQL repository, S3 client |
What Are Driving Ports and Adapters
Driving ports (also called primary ports) define how external actors interact with the application. A RESTful API controller is a classic driving adapter. So is a GraphQL API resolver or a command-line interface.
The driving adapter receives a request and translates it into something the application core understands. The core never knows whether the request came from HTTP, gRPC, or a test harness.
AWS Prescriptive Guidance recommends hexagonal architecture for Lambda functions specifically because it lets you decouple the transport layer from the domain model. The business logic runs the same regardless of what triggers it.
What Are Driven Ports and Adapters
Driven ports (secondary ports) work in the opposite direction. The application core says “I need to store this data” or “I need to send this notification.” It defines the interface. The driven adapter provides the actual implementation.
Database repositories, email services, message queue publishers, third-party API clients. All driven adapters.
Netflix’s engineering team built driven adapters for SQL databases, Elasticsearch, and REST APIs. When a downstream service didn’t yet support bulk fetch, they wrote a temporary adapter that sent concurrent individual calls. Once the bulk API shipped, they swapped in a new adapter. Zero changes to the business logic.
The Application Core in Hexagonal Architecture
Everything inside the hexagon is the application core. This is where business rules live, where domain models exist, and where use cases get orchestrated. Nothing else belongs here.
No framework imports. No database annotations. No HTTP response objects. If you see @Entity from JPA or HttpServletRequest inside your core, you’ve already broken the pattern.
The dependency rule: dependencies always point inward. The core depends on nothing external. Everything external depends on the core.
Use cases sit inside this layer and orchestrate domain objects. They call port interfaces when they need data from outside or need to push data out. The use case doesn’t know or care whether the repository interface connects to PostgreSQL, MongoDB, or an in-memory HashMap.
McKinsey found that technical debt can consume up to 40% of a company’s entire technology estate. A huge chunk of that debt comes from business logic getting entangled with infrastructure code. Hexagonal architecture’s strict boundary enforcement directly reduces this kind of architectural debt.
The testability advantage starts here too. Because the core has no external dependencies, you can run the entire use case suite with plain unit tests. No database containers, no mock servers, no flaky integration pipelines. The software architect who enforces this boundary gives their team a faster feedback loop from day one.
Hexagonal Architecture vs Layered Architecture
Layered architecture organizes code in a top-down stack. Presentation talks to business logic. Business logic talks to data access. Each layer can only communicate with the one directly below it.
It’s simple. And for years it worked fine.
But the dependency direction is wrong. In layered architecture, the business layer typically depends on the data access layer. That means your core logic is coupled to your persistence technology. Want to swap PostgreSQL for DynamoDB? Good luck. You’re changing code across multiple layers.
Hexagonal architecture flips this. The core defines interfaces that the infrastructure layer implements. Dependencies point inward, not downward.
| Aspect | Layered Architecture | Hexagonal Architecture |
|---|---|---|
| Dependency flow | Top-down (UI to DB) | Outside-in (infra to core) |
| Business logic isolation | Partial (often leaks) | Complete (by design) |
| Swapping a database | Changes across layers | One new adapter |
| Test complexity | Requires mocking layers | Core tests need no mocks |
| Setup overhead | Low | Moderate |
The IcePanel 2025 State of Software Architecture report found that microservices (60%) and event-driven (55%) remain the most common architecture patterns. Both benefit heavily from hexagonal principles inside individual services.
Look, layered architecture still makes sense for straightforward CRUD apps or projects with a short expected lifespan. A rapid app development project that ships in two weeks and gets thrown away in three months doesn’t need hexagonal structure. But anything that’s going to live for years and evolve with the business? The investment pays off.
PayPal uses hexagonal architecture to separate transaction processing logic from its APIs and user interfaces. Their business logic stays clean regardless of how many front-end channels or API integrations they add.
Hexagonal Architecture vs Clean Architecture vs Onion Architecture
These three patterns confuse people constantly. And honestly, they should, because they share the same fundamental idea: protect the core from infrastructure.
The differences are real, though. They’re just more about structure and prescriptiveness than philosophy.
How Clean Architecture Differs
Robert C. Martin proposed Clean Architecture in 2012. It adds explicit concentric rings: entities at the center, then use cases, then interface adapters, then frameworks and drivers on the outside.
Clean Architecture is more prescriptive. It tells you exactly what belongs in each ring and enforces strict layer boundaries. Hexagonal architecture just says “core inside, infrastructure outside, communicate through ports.”
According to the Stripe Developer Report (2024), developers waste 23-42% of their working time managing technical debt. Both patterns aim to reduce this, but Clean Architecture gives you more specific guardrails to follow.
How Onion Architecture Differs
Onion Architecture, proposed by Jeffrey Palermo in 2008, decomposes the application core into concentric layers using inversion of control. Domain model at the center, domain services around it, application services around that.
It’s more granular about what goes inside the core compared to hexagonal architecture. But the outer boundary looks the same: infrastructure stays outside, and dependencies always point inward.
Quick comparison:
- Hexagonal: Least prescriptive. Focuses on ports/adapters boundary. Doesn’t dictate internal core organization.
- Onion: Moderately prescriptive. Adds internal layering to the core with concentric rings.
- Clean: Most prescriptive. Defines specific layers, dependency rules, and what goes where.
All three are valid approaches to the same problem. I’ve seen teams pick hexagonal architecture specifically because it gives them breathing room. Less structure to argue about in code reviews, more focus on the one thing that matters: keeping the core isolated.
For teams already practicing domain-driven design, any of the three works. The bounded context maps naturally to a hexagon (or an onion, or a clean architecture ring). Your choice comes down to how much internal structure your team needs to stay disciplined.
Implementing Hexagonal Architecture in Practice
Theory is one thing. Actually structuring a project around hexagonal architecture is where most teams stumble. Took me a while to get comfortable with it too, honestly.
The pattern itself is not prescriptive about folder structure. But after enough projects, certain conventions emerge.
Project Folder Structure
Most implementations in Java (Spring Boot), Kotlin, or TypeScript (NestJS) settle on something like this:
/domainholds entities, value objects, and domain services. Zero external imports./applicationholds use cases and port interfaces. Depends only on domain./infrastructureholds driven adapter implementations (database repos, API clients)./adapters(or merged into infrastructure) holds driving adapters like REST controllers.
The Gartner Peer Community survey on microservices found that 74% of organizations already use microservices architecture. Each microservice is a natural fit for its own hexagonal structure. You get clear domain boundaries per service.
One common mistake: putting domain logic inside adapters. I’ve seen developers stick business validation in a REST controller because it was “quick.” That quick shortcut will cost you later when you need to trigger the same logic from an event consumer or a CLI tool.
Wiring Ports to Adapters with Dependency Injection
Dependency injection is the mechanism that makes hexagonal architecture work at runtime. The application core defines port interfaces. The DI container wires the correct adapter implementation to each port when the app starts up.
In Spring Boot, this looks like @Service and @Repository annotations with interface-based injection. In NestJS, you use providers and module configuration. The core never instantiates its own dependencies.
This wiring is also where you swap adapters. Need to run tests against an in-memory database instead of PostgreSQL? Configure a different adapter. Moving from REST to gRPC for a downstream service? New adapter, same port. The codebase stays clean.
AWS published prescriptive guidance specifically for building hexagonal architectures on their platform. Their approach uses Lambda functions where the domain model class has zero knowledge of external components. The infrastructure code (DynamoDB access, for example) lives entirely in adapter classes that implement repository interfaces.
A well-structured software development plan should specify these boundaries upfront. Teams that define their port interfaces before writing adapter code tend to make fewer architectural mistakes. It forces you to think about what the core actually needs rather than jumping straight to implementation details.
Testing Benefits of Hexagonal Architecture
The core can be tested with plain unit tests. No database spinning up, no HTTP server running, no Docker containers needed. Just the business logic, a fake adapter, and assertions.
This is the single biggest practical advantage of hexagonal architecture. And teams feel it immediately.
Because driven port interfaces are defined by the application (not by frameworks), they’re trivial to stub or replace with in-memory implementations. Your test suite doesn’t depend on PostgreSQL being available. It doesn’t care about network latency to a third-party API. It runs in milliseconds.
The 2026 State of Testing report from PractiTest found that Test Coverage (56.4%) and Automation Coverage (40.1%) remain the dominant QA metrics. Hexagonal architecture directly supports both by making the core testable without external dependencies.
Integration tests target individual adapters in isolation. You test the PostgreSQL adapter against a real database. You test the REST adapter against actual HTTP calls. But you test them separately from the business logic. Each test has one job.
Netflix built their testing strategy around this separation. They wrote fast unit tests for all business logic (interactors and entities), then added targeted integration tests for each data source adapter. The result was a test suite they described as “reliable and super fast,” which they considered a prerequisite for development speed.
| Test Type | What It Covers | Hexagonal Advantage |
|---|---|---|
| Unit tests | Use cases, domain logic | No mocks for infrastructure needed |
| Integration tests | Individual adapters | Isolated from business logic |
| End-to-end tests | Full request flow | Fewer needed (core already tested) |
The real-world impact is faster CI pipelines. Organizations that target 70-90% code coverage for business logic (a common benchmark per Virtuoso QA) can actually hit those numbers without slow, flaky integration suites dragging everything down.
Teams practicing test-driven development find hexagonal architecture especially natural. You write the port interface first, then the test, then the use case. The adapter comes last. Your tests never touch infrastructure until you’re ready to verify the wiring.
When Hexagonal Architecture is Worth the Overhead
Not every project needs this.
A simple CRUD service with five endpoints and one database table? Hexagonal architecture adds files, interfaces, and indirection that will never pay for themselves. You’ll spend more time wiring adapters than writing actual logic.
But the calculus changes fast when certain conditions show up.
Strong fit:
- Long-lived applications expected to survive multiple technology cycles
- Multiple integration points (databases, APIs, message queues, file systems)
- Teams that rotate members frequently and need clear boundaries
- Systems where software scalability is a primary concern
Poor fit:
- Prototypes and throwaway scripts
- Small internal tools with a single developer
- Projects with a lifespan under six months
A 2024 vFunction study found that 77% of organizations have launched enterprise-wide initiatives to address technical debt. The upfront cost of hexagonal architecture, more files, more interfaces, more indirection, is precisely the kind of investment that prevents that debt from accumulating.
Gartner projects that 80% of technical debt will be architectural by 2026. Not code-level. Not process-level. Architectural. That’s the category hexagonal architecture directly prevents.
The cost pays back the first time a major integration swap happens. Or the first time a new developer joins and can understand the software system because the boundaries are explicit. Or when a QA engineer can write tests without needing to understand infrastructure details.
Team familiarity matters too. Adopting hexagonal architecture without buy-in creates friction instead of clarity. If half the team keeps putting database annotations in the domain layer, the pattern collapses. A shared design document that explains the boundaries and rules goes a long way.
Common Mistakes When Adopting Hexagonal Architecture
The pattern itself is simple. The mistakes teams make implementing it are predictable.
Letting Framework Annotations Leak Into the Domain
This is the most common violation. A developer uses JPA’s @Entity annotation on a domain object because it’s convenient. Now the domain depends on a persistence framework. The entire point of hexagonal architecture is gone.
Keep domain objects as plain classes. Map them to persistence-specific objects in the adapter layer. Yes, it means a mapping step. That mapping is the price of isolation, and it’s worth it.
Stripe’s Developer Report (2024) found developers waste 23-42% of working time on technical debt. Framework leakage into the domain is exactly the kind of shortcut that compounds into architectural debt over months.
Creating Pass-Through Ports
The trap: adding an interface that does nothing but forward calls to the adapter without adding any real abstraction.
If your port interface is a mirror image of a specific database’s API, you haven’t abstracted anything. The port should express what the application needs, not how the infrastructure works. A method called findActiveUsersByRegion() is a good port. A method called executeSQLQuery(String sql) is not.
Over-Engineering Adapters for Systems That Won’t Change
Some teams build elaborate adapter abstractions for a database they’ve used for ten years and will use for ten more. Your mileage may vary, but if you’re certain a dependency won’t change, a simpler adapter is fine.
The software development principles behind hexagonal architecture are about managing change. If there’s no change to manage, a lighter touch works.
Ignoring the Pattern at the Boundaries
Event consumers, scheduled jobs, CLI commands. These entry points often get built without proper driving adapters because “they’re internal.” But they’re still external triggers interacting with the application core.
Every entry point deserves a driving adapter. Every external system the core talks to deserves a driven adapter. The software development process should account for these boundaries in the planning phase, not as an afterthought during code refactoring.
Hexagonal Architecture in Domain-Driven Design
Hexagonal architecture and DDD show up together so often that people sometimes think they’re the same thing. They’re not. But they reinforce each other in ways that are hard to ignore.
DDD gives you the modeling methodology for what goes inside the hexagon. Aggregates, value objects, domain events, repositories. These are the building blocks of your application core. Hexagonal architecture tells you how to protect that core from everything outside it.
A 2023 systematic literature review by Ozkan et al. found that bounded contexts and entities/value objects were the most widely utilized DDD patterns across microservices, enterprise systems, and web applications. Both map directly to hexagonal architecture’s internal structure.
How Bounded Contexts Map to Hexagons
Each bounded context gets its own hexagon. Its own ports. Its own adapters. Its own domain model with its own ubiquitous language.
AWS Prescriptive Guidance recommends this approach for all enterprise back-end development projects regardless of complexity. Their reasoning: hexagonal architecture forces you to solve the business problem first, while traditional layered approaches shift focus toward technical concerns.
When two bounded contexts need to communicate, they do it through their respective adapters. The anti-corruption layer from DDD maps directly to an adapter that translates between different domain languages.
Using Hexagonal Architecture Without DDD (and Vice Versa)
Hexagonal without DDD: You get clean separation between core and infrastructure, but your internal domain model might lack structure. Fine for simpler applications.
DDD without hexagonal: You get a well-modeled domain, but without strict port/adapter boundaries, infrastructure concerns still leak in. Still valuable, but you lose the isolation guarantees.
The combination works best for complex software development projects where business rules are the main source of complexity. Eric Evans, who wrote the original DDD book, explicitly emphasized that the domain model should have no knowledge of persistence or UI, which is exactly what hexagonal architecture enforces structurally.
McKinsey reports that companies adopting modular architectures with clear domain boundaries see 30-50% improvements in operational performance. Hexagonal architecture with DDD is one of the most concrete ways to achieve that modularity at the code level.
A software modeling approach that combines both gives teams a shared vocabulary (from DDD) and a shared structural contract (from hexagonal architecture). New developers join and know where business logic lives, where infrastructure lives, and how they communicate. That clarity compounds over years.
FAQ on What Is Hexagonal Architecture
What is hexagonal architecture in simple terms?
Hexagonal architecture is a software design pattern that isolates core business logic from external systems like databases and APIs. It uses ports (interfaces) and adapters (implementations) to keep the application core independent and testable.
Who created hexagonal architecture?
Alistair Cockburn introduced the concept in the mid-1990s on the Portland Pattern Repository wiki. He formally renamed it “Ports and Adapters” in 2005. In 2024, he published a full book on the subject with Juan Manuel Garrido de Paz.
Why is it called hexagonal?
The hexagon shape is purely symbolic. Cockburn chose it to represent multiple faces where external systems connect. There’s no requirement for six ports or six sides. It just provided enough visual space for diagramming different interfaces.
What is the difference between hexagonal architecture and layered architecture?
Layered architecture uses top-down dependencies where business logic depends on the data layer. Hexagonal architecture flips this. Dependencies point inward toward the core. Swapping infrastructure requires changing one adapter, not rewriting across layers.
How does hexagonal architecture compare to clean architecture?
Both protect core logic from infrastructure. Clean architecture adds explicit concentric rings with strict layer rules, making it more prescriptive. Hexagonal architecture focuses only on the ports and adapters boundary without dictating internal core organization.
What are ports and adapters?
Ports are interfaces defined by the application core describing what it needs or offers. Adapters are concrete implementations that connect those ports to real technology, like a REST controller or a database repository. The core never references adapters directly.
Does hexagonal architecture work with microservices?
Yes. Each microservice maps naturally to its own hexagon with dedicated ports and adapters. Netflix uses this approach across its studio engineering services. It gives each service clear domain boundaries and makes infrastructure swaps straightforward.
When should you avoid hexagonal architecture?
Simple CRUD apps, short-lived prototypes, and small scripts don’t benefit from the extra abstraction. The overhead of defining ports, adapters, and mapping layers only pays off when applications are complex, long-lived, or have multiple integration points.
How does hexagonal architecture improve testing?
The core can be tested with plain unit tests using fake adapters. No database or HTTP server required. Integration tests target individual adapters separately. This produces faster CI pipelines and fewer flaky tests across the software testing lifecycle.
Can you use hexagonal architecture with domain-driven design?
Absolutely. DDD provides the modeling tools (aggregates, value objects, domain events) for what lives inside the hexagon. Hexagonal architecture provides the structural boundary that protects the domain model from infrastructure concerns. They complement each other well.
Conclusion
Understanding what is hexagonal architecture comes down to one idea: protect your domain model from everything external. Ports define the contracts. Adapters handle the messy reality of databases, APIs, and frameworks. The core stays clean.
The pattern isn’t free. More interfaces, more files, more upfront thinking. But for long-lived systems with multiple integration points, that cost prevents the kind of architectural technical debt that cripples teams later.
Whether you pair it with event-driven architecture, apply it inside individual modular software architecture boundaries, or use it alongside CQRS and aggregate roots, hexagonal architecture gives your team a structural contract that scales.
Start with the dependency rule. Dependencies point inward. Build from there.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.
- CSS Cheat Sheet - May 18, 2026
- How to Set Up VSCode for Python Development - May 16, 2026
- How Using One Platform Can Simplify Order Fulfillment - May 15, 2026
