Hexagonal Architecture: Isolating Business Logic with the Ports and Adapters Pattern

The Problem That Hexagonal Architecture Solves

Every software system has a heart — the business logic that makes it worth building in the first place. This is the code that calculates discounts, validates orders, enforces pricing rules, or determines whether a loan application should be approved. It represents genuine knowledge about the problem the software is trying to solve.

The trouble is that most systems don't protect this heart very well.

Over time, business logic tends to become entangled with the technical plumbing required to run it. The rules for processing an order end up scattered across database queries, HTTP handlers, and framework-specific code. The logic for approving a customer's account becomes inseparable from the way data happens to be stored. What started as a clear business rule is now woven so tightly into the infrastructure that it can't be understood, tested, or changed without disturbing everything around it.

This creates a cascade of problems. Replacing the database becomes a project that touches core logic. Upgrading the web framework means unravelling business rules. Writing an automated test requires spinning up servers, connecting to external services, and managing test data — all just to verify whether a single business rule is correct.

Hexagonal Architecture, also known as the Ports and Adapters pattern, is a response to exactly this problem. Introduced by software architect Alistair Cockburn in the early 2000s, it provides a way to structure applications so that the business logic sits at the centre, protected from the infrastructure surrounding it. Technologies come and go; the business logic endures.

How Hexagonal Architecture Differs from Layered Architecture

At first glance, hexagonal architecture can appear similar to the more familiar layered architecture. Both approaches aim to separate concerns and organise code into distinct regions with different responsibilities. However, the similarities mask a fundamental difference in how dependencies flow between these regions.

Layered architecture organises code into horizontal tiers — typically presentation, application, domain, and infrastructure layers. Each layer may only depend on the layer directly beneath it. The presentation layer depends on the application layer, which depends on the domain layer, which depends on the infrastructure layer. This arrangement creates a one-way dependency chain from the top of the stack to the bottom.

The problem with this arrangement is that the most important part of the system — the domain logic — ends up at the bottom of the dependency chain, depending directly on infrastructure concerns. The domain layer imports database libraries, calls out to infrastructure services, and becomes entangled with the very technologies it should be insulated from. When dependencies flow from domain to infrastructure, the domain cannot be understood or tested without also bringing in the database, the framework, and everything else it depends on.

Hexagonal architecture inverts this relationship entirely. Instead of the domain depending on infrastructure, infrastructure depends on the domain. The core defines interfaces — ports — that describe what it needs from the outside world. Infrastructure components — adapters — then implement these interfaces to fulfil the core's requirements. The domain no longer knows anything about databases, APIs, or frameworks. It only knows about its own interfaces.

To understand this difference concretely, consider how each architecture would handle data persistence.

In a layered architecture, a domain service that needs to retrieve a customer might directly call a repository implementation that knows about the database. The domain service imports the repository class, which in turn imports the ORM library and database connection classes. The domain is now coupled to the database technology.

In a hexagonal architecture, the same domain service would depend on a CustomerRepository interface defined within the core. The interface belongs to the domain — it expresses what the domain needs in the domain's own language. The actual database implementation lives in an adapter outside the core, implementing that interface. The domain never knows which database technology is being used, or even whether a database is being used at all. It simply calls its own interface, and the adapter handles the rest.

This inversion of dependencies is the defining characteristic that sets hexagonal architecture apart from traditional layering. The layers still exist conceptually — you still have a core and surrounding infrastructure — but the direction of dependency has been reversed.

A Common Point of Confusion

If you're thinking, "Wait — if ,in my layered implementation, I program to interfaces and keep my domain model separate, haven't I already achieved hexagonal architecture?" — you're asking exactly the right question, and you're not alone in this confusion.

The distinction is subtle but crucial. What you're describing is well-structured layered architecture with dependency inversion, which is a significant improvement over traditional layering. You have the right instincts — separating concerns, depending on abstractions, protecting your domain. These practices already give you many benefits.

Hexagonal architecture goes one step further. It inverts not just individual dependencies but the entire relationship between your code and the outside world. In your approach, the domain defines interfaces (good!), but those interfaces often still carry the fingerprints of infrastructure thinking — repository patterns, framework annotations, utility imports. The domain still knows, at some level, that it's being persisted or exposed via HTTP.

In true hexagonal architecture, the core defines ports that express what the business needs in its own language — ForPersistingOrders rather than OrderRepository, ForNotifyingCustomers rather than EmailService. The core contains zero imports from frameworks, databases, or external libraries. It has no idea that HTTP, SQL, or message queues even exist. All of that lives in adapters outside the core, whose sole job is translation.

Think of it this way: your approach makes the domain aware of abstractions; hexagonal architecture makes the domain aware only of itself. The difference is one of degree and discipline, but it's the difference between a house with good insulation and a house with its own independent power supply. Both keep you warm, but one can function completely off-grid.

In essence, hexagonal architecture is layered architecture with additional implementation constraints around the use of interfaces and the domain layer — constraints designed to ensure that the core never needs to know about anything external. Both approaches organise code into concentric regions of responsibility. Both separate business logic from technical concerns. Both can (and should) use interfaces to define boundaries.

The difference lies in the strictness of the rules and the direction of knowledge. In layered architecture, the domain may still be aware of the infrastructure layer above it through interfaces, but it often retains indirect dependencies — framework annotations, utility imports, or assumptions about how dependencies will be provided. The domain knows it's part of a larger technical system.

Hexagonal architecture imposes an additional discipline: the core must have zero knowledge of anything outside itself. It defines ports in its own language, for its own purposes, and expects the outside world to conform to it — not the other way around. Every framework, every database, every external API becomes a pluggable adapter that exists solely to serve the core's needs.

So, hexagonal architecture is layered architecture with the training wheels tightened. Same essential insight, but enforced with religious fervour until the core achieves complete technological agnosticism.

What Problem Does Hexagonal Architecture Solve That Layered Architecture Doesn't?

Layered architecture successfully separates concerns at a high level, but it fails to protect the domain from infrastructure dependencies. This failure manifests in several specific problems that hexagonal architecture directly addresses.

Testing isolation is the most immediate and painful problem. In a layered system, testing a domain service typically requires instantiating real repositories, which require real database connections, which require the database server to be running. Tests become slow, brittle, and difficult to set up. They often fail for reasons unrelated to the business logic being tested — a network timeout, a missing database migration, or incorrect connection credentials. Developers respond by writing fewer tests, or by testing only through the presentation layer with all the complexity that entails.

Hexagonal architecture solves this by ensuring the domain depends only on interfaces. For testing, these interfaces can be implemented with lightweight, in-memory fakes that run in milliseconds with no external dependencies. Every business rule can be tested thoroughly, including error conditions and edge cases that would be nearly impossible to reproduce with a real database. Tests become fast, reliable, and focused on what matters.

Technology replacement is another area where layered architecture falls short. Because the domain depends directly on infrastructure implementations, changing a technology means modifying the domain code. Replacing a SQL database with a document store, or swapping one payment provider for another, requires rewriting not just the data access code but potentially the domain logic that calls it. The domain is held hostage to infrastructure decisions made years earlier.

Hexagonal architecture confines technology to adapters. The domain defines what it needs — save this order, charge this payment, send this notification — and adapters implement those needs using whatever technology is appropriate. Replacing a database means writing a new adapter that implements the same repository interfaces. The domain never changes. This not only makes replacements safer but also enables gradual migrations where both old and new adapters run simultaneously while traffic is slowly shifted.

Domain expressiveness suffers in layered systems because the domain must accommodate infrastructure concerns. ORM frameworks impose constraints on object structures — requiring parameterless constructors, public getters and setters, or specific annotations. Database schemas influence domain model design. The domain becomes distorted to serve the technology rather than express the business.

Hexagonal architecture creates space for the domain to be designed purely for business expression. The domain model can use value objects, enforce invariants in constructors, encapsulate behaviour, and structure itself according to business concepts rather than database tables. Infrastructure adapters then handle the translation between this rich domain model and the persistence mechanism. The domain is no longer forced to conform to the technology's expectations.

Multiple entry points are awkward to support in layered architecture. If a system needs both a REST API and a message queue consumer, each entry point often duplicates the wiring of domain dependencies and external service calls. Alternatively, developers create shared infrastructure code that still couples the domain to specific technologies.

Hexagonal architecture treats every entry point as just another input adapter. The REST controller and the message queue consumer both call the same input ports — the same use cases defined in the core. Neither knows about the other, and both translate between their specific protocol and the domain's language. Adding a new entry point simply means writing a new adapter.

The Three Zones of a Hexagonal System

To make this concrete, it helps to think of a hexagonal application as having three distinct zones, each with a clearly defined purpose.

The Core Application

The core is everything that represents what your system actually does. It contains the domain models that describe the concepts your business works with — things like orders, customers, accounts, or products. It contains the rules that govern how those concepts behave — an order must have at least one item, a discount cannot exceed a certain percentage, a payment must be authorised before an order is confirmed. And it contains the use cases that describe the operations the system can perform — placing an order, cancelling a booking, approving a loan application.

The core knows about the domain. It does not know about databases, REST APIs, web frameworks, or any specific technology. If you look at the core and see imports from an HTTP library or an ORM framework, that is a sign that the boundary has been violated.

A well-designed core can be read and understood by someone who knows nothing about the technical stack. The business rules are clearly visible, expressed in the language of the domain rather than the language of infrastructure.

Ports

Ports are the defined entry and exit points through which the core communicates with the outside world. They are interfaces — contracts that describe what communication is possible, without specifying how that communication will be carried out.

There are two kinds of ports, and understanding the distinction is essential.

Input ports represent things the outside world can ask the core to do. They describe the operations the application exposes — the use cases that external actors can trigger. A web request, a command-line instruction, a message arriving on a queue, a scheduled job running in the background — all of these ultimately end up calling an input port. The input port itself is expressed in domain terms. It describes a business operation, not an HTTP endpoint.

Output ports represent things the core needs from the outside world in order to do its job. When the core needs to persist data, look up information, send a notification, or process a payment, it expresses that need as an output port. The interface describes what the core requires — save this order, charge this amount, send this notification — without specifying what technology will fulfil the request.

The key point is that ports belong to the core. They are defined by the core to describe its own needs and capabilities. Nothing about a port is specific to the technology that will eventually implement or call it.

Adapters

Adapters are where the real world connects to the core. They implement the contracts defined by ports, translating between the core's domain language and the language of the specific technology being used.

Input adapters receive requests from external systems and translate them into calls to the core's input ports. A REST controller receives an HTTP request, extracts the relevant data, and calls the appropriate use case. A message queue consumer reads a message off a queue and triggers the corresponding operation in the core. A command-line interface parses user input and invokes a use case. In every case, the adapter's job is translation — receiving something from the outside world and passing it to the core in a form the core understands.

Output adapters implement the output ports the core depends on. A database adapter implements the data access interfaces, performing the actual SQL queries or document store operations. A payment adapter implements the payment interface by calling out to a payment provider's API. A notification adapter implements the notification interface by sending emails through an SMTP server or a third-party service.

Adapters contain all the technology-specific code. They know about HTTP status codes, SQL syntax, API authentication headers, and message formats. The core knows none of this.

A Concrete Example: How Ports and Adapters Work Together

To see how these pieces fit together, consider a concrete example: a system for processing orders.

When a customer places an order through a web interface, an HTTP request arrives at the REST controller — an input adapter. The controller parses the request, validates its format, and calls the place order use case — an input port.

The use case, implemented inside the core, applies the business rules: checking inventory, calculating totals, enforcing constraints. To complete the operation, it needs to save the order and process a payment. It does this by calling the output ports it depends on — the OrderRepository interface and the PaymentGateway interface.

These calls travel out to the relevant output adapters. The PostgresOrderRepository handles the actual database interaction, translating domain objects into SQL queries and result sets back into domain objects. The StripePaymentGateway makes the actual API call to the payment provider, translating domain payment details into the format Stripe expects and handling the response.

The result of the payment and the saved order travel back through the core, and the use case returns a result to the controller. The controller translates this result into an HTTP response with the appropriate status code and body.

Throughout this flow, the core never touches a database connection, never constructs an HTTP request, never knows which payment provider is being used. It operates entirely within its own domain, communicating with the outside world only through its defined ports.

This example also illustrates the distinction between input and output adapters. The REST controller is an input adapter — it brings requests into the core. The database and payment implementations are output adapters — they carry requests out of the core to external systems.

The Dependency Inversion Principle

The mechanism that makes this possible is the Dependency Inversion Principle — one of the foundational principles of object-oriented design.

In many systems, higher-level modules (like business logic) depend on lower-level modules (like database access). Change the database, and you potentially need to change the business logic. The dependency flows from the thing that matters toward the thing that should be replaceable.

Dependency inversion flips this. Instead of the core depending on a concrete database implementation, the core defines an interface that describes what it needs. The database implementation then depends on that interface. The core is the source of truth; the infrastructure conforms to it.

This is not just a theoretical distinction. It is what allows a production system to run against a real PostgreSQL database while tests run against an in-memory fake. Both the real database adapter and the in-memory fake implement the same interface, defined by the core. The core doesn't know the difference. This is the inversion: the infrastructure accommodates the core, not the other way around.

Why Testability Improves Dramatically

One of the most immediate and tangible benefits of hexagonal architecture is the impact on testing. This deserves careful attention because it often becomes the most compelling practical argument for the pattern.

In a tightly coupled system, testing business logic is hard. Any test that exercises a use case ends up pulling in everything the use case depends on: the database, the network, external APIs, message queues. Running a simple unit test requires standing up infrastructure. Tests are slow, fragile, and expensive to maintain. When a test fails because a network connection timed out, you learn nothing about whether your business rule is correct.

In a hexagonal system, the core depends only on interfaces. This means that for any test of the core's behaviour, you can substitute lightweight, in-memory implementations of the output ports. Instead of connecting to a real database, the test uses a fake repository that stores data in a simple map. Instead of calling a real payment gateway, it uses a fake that records what was called and returns a predefined result.

Technology Becomes Replaceable

A consequence of the architecture that becomes important over the long lifetime of a system is the ease with which technologies can be changed.

Software systems tend to outlive the technologies they were built with. A database platform that seemed the right choice in 2015 might be a liability by 2025. A web framework that was the industry standard when the system was built might be unmaintained ten years later. A payment provider might change its API, or be replaced by a competitor with better terms.

In a tightly coupled system, changing any of these things is a significant undertaking. The business logic is so entangled with the infrastructure that pulling out one technology means rewriting large sections of code that have nothing to do with what changed.

In a hexagonal system, replacing a technology is a matter of writing a new adapter. The new adapter implements the same interface as the old one. The core doesn't change. The input ports don't change. Other adapters don't change. Only the specific adapter being replaced is rewritten.

This also enables gradual migration. During a database migration, you can run both a legacy adapter and a new one simultaneously, directing traffic between them. When the migration is complete, the legacy adapter is removed. The core and everything else remains untouched.

Supporting Multiple Entry Points

Another significant advantage of the architecture is the ease with which multiple entry points can coexist.

Many systems need to be accessible in more than one way. A platform might need a REST API for web clients, a GraphQL API for mobile applications, an internal RPC interface for other services, and a message queue consumer for asynchronous processing. In a traditional system, supporting all of these often means duplicating logic across multiple controllers or duplicating the wiring of database connections and external service calls.

In a hexagonal system, each access method is simply a different input adapter calling the same input ports. The core is written once. The business rules are defined once. Each new way of accessing the system is just a new translation layer, responsible only for receiving input in its specific format and passing it to the core in domain terms.

This also applies to deployment targets. If a system needs to run in different environments — different cloud providers, on-premises deployments, different regional configurations — environment-specific output adapters can be written for each target without touching the core.

Hexagonal Architecture Within a Single Tier

A question that often arises is whether hexagonal architecture applies within a single tier of a distributed system, or whether it spans multiple tiers. The answer clarifies an important aspect of the pattern.

Hexagonal architecture is primarily concerned with the internal structure of a single deployable unit — what might traditionally be called an application tier or service. It organises the code within that unit into core and adapters, with dependencies pointing inward toward the domain. A single microservice, a monolithic web application, or a desktop application can all be built using hexagonal principles within their own process boundaries.

However, this does not mean the pattern is confined to a single tier in a distributed sense. When a system is composed of multiple services communicating over a network, each service can independently adopt hexagonal architecture internally. Moreover, the communication between services can itself be structured using ports and adapters. Service A calls Service B through an output port, with an HTTP client adapter implementing that port. Service B receives the call through an input adapter that translates the HTTP request into a core operation. The pattern thus applies both within each service and to the interactions between them.

The key insight is that hexagonal architecture operates at the level of dependency management, not at the level of physical deployment boundaries. It can be applied wherever you need to protect core logic from the details of how it communicates with the outside world — whether that outside world is a database running on the same machine, another service across a network, or a user interface in a different process entirely.

Alignment with Domain-Driven Design

Hexagonal architecture and Domain-Driven Design are natural partners. DDD is an approach to software development that emphasises building systems around a rich, expressive model of the business domain. The domain model should capture genuine business knowledge, not just data structures.

The problem DDD practitioners often encounter is that technical concerns — database schemas, ORM mappings, API contracts — exert pressure on the domain model, distorting it in ways that serve infrastructure rather than the domain. A rich domain object that should encapsulate behaviour and enforce invariants gets flattened into a database-friendly structure with getters and setters.

Hexagonal architecture creates the space for DDD to work. By protecting the core from infrastructure concerns, the domain model can be designed to express business knowledge rather than technical constraints. The core is free to use whatever structure best represents the domain. Infrastructure adapts to the domain, rather than the domain adapting to infrastructure.

Comparison with Related Architectural Styles

Hexagonal architecture is one of a family of related patterns that share the same fundamental concern: separating core logic from infrastructure through careful management of dependencies.

Clean Architecture, associated with Robert Martin, expresses essentially the same ideas using a different visual metaphor — concentric circles rather than a hexagon. The terminology differs slightly, but the core principle is identical: dependencies point inward, the domain is at the centre, and infrastructure conforms to the domain's needs.

Onion Architecture, introduced by Jeffrey Palermo, is another variation on the same theme, also using concentric circles as its organising metaphor. Like clean architecture, it emphasises that domain logic sits at the centre and that all dependencies point inward.

Microservices architecture operates at a different level of abstraction, concerned with how a system is divided into independently deployable services. It doesn't prescribe how any individual service should be internally structured. Hexagonal architecture and microservices are complementary — each service in a microservices system can be built using hexagonal architecture to protect its internal business logic.

Challenges and Trade-offs

Hexagonal architecture is not universally the right choice, and it comes with genuine costs that should be understood honestly.

The most immediate cost is the additional structure it requires. You are introducing interfaces where you might otherwise write direct method calls. You are creating adapter classes that translate between representations. For a small system or a simple CRUD application with minimal business logic, this overhead can easily outweigh the benefits. The pattern adds the most value when business logic is complex, rules are likely to evolve, and the system is expected to be maintained over a long period.

Maintaining the architecture requires sustained discipline. Without active attention, the boundaries tend to erode. A developer under time pressure adds a direct database import to a core class. Business logic migrates into a controller because it was convenient. Over time, the pattern quietly disappears while the codebase retains the appearance of structure. The benefits erode along with the discipline. This means the pattern requires ongoing investment in code reviews and architectural awareness.

The pattern also has a learning curve. Developers unfamiliar with dependency inversion, or accustomed to thinking of applications as a database with logic layered on top, may find the concepts initially counterintuitive. Teams adopting the pattern should budget time for this adjustment.

There is also a risk of over-engineering. Not every interface needs multiple implementations, and not every boundary justifies a port. The goal is to invert dependencies in the places where it matters — where infrastructure is likely to change, where testing is important, where business logic is complex. Applying it indiscriminately creates unnecessary abstractions without corresponding benefits.

Common Pitfalls

Teams new to the pattern tend to make the same mistakes, and being aware of them in advance reduces the risk of replicating them.

The most common problem is allowing infrastructure concerns to leak into the core. This happens incrementally — a framework annotation here, a database type there, an HTTP exception class imported for convenience. Each individual violation seems minor, but together they slowly reconstruct the coupling the pattern was designed to prevent. The remedy is vigilance: the core should have no dependencies on external libraries beyond standard language utilities.

A related problem is the reverse: allowing business logic to migrate into adapters. Validation logic accumulates in controllers. Calculation rules end up in database query methods. The core becomes a thin shell with no real behaviour. Adapters should contain only translation logic. Any decision-making or computation belongs in the core.

Over-fragmenting ports into very small, single-method interfaces can make the architecture feel fragmented and hard to navigate. Related operations belong together in a single interface. A repository interface with several methods — save, find, delete — is cleaner than three separate single-method interfaces.

Finally, some teams implement the structural aspects of the pattern — creating the interfaces, the adapter classes, the package structure — while neglecting the domain model itself. The result is a well-structured system with an anaemic core: objects that are essentially data containers with no behaviour, no enforced invariants, no expressive domain logic. The architecture creates the conditions for a rich domain model, but it doesn't automatically produce one. That requires deliberate attention to the domain itself.

When to Use Hexagonal Architecture

The pattern is best suited to systems where the business logic is complex, valuable, and expected to evolve over time. If the core business rules are sophisticated, if they represent genuine domain knowledge that took years to accumulate, if they need to be understood clearly and tested rigorously, hexagonal architecture provides a structure that protects and reveals that logic.

It is particularly well suited to systems with long operational lifespans, where infrastructure technologies will likely change several times before the system is decommissioned. Financial systems, enterprise business platforms, and systems built to comply with complex regulatory requirements are natural candidates.

It is less well suited to simple data management systems with minimal business logic, to short-lived applications, or to early-stage prototypes where the goal is speed of exploration rather than long-term maintainability.

The Enduring Value of Clean Boundaries

Hexagonal architecture is ultimately about a single conviction: the business logic of an application is its most valuable and most durable part, and it deserves to be protected.

By placing the core at the centre and making everything else conform to it, the architecture ensures that the part of the system that represents genuine knowledge about the domain can be understood in isolation, tested without infrastructure, and changed without fear of unintended consequences. Technologies that were once central can be replaced without rewriting what matters.

The hexagon in the name is incidental. There is nothing magical about six sides. The pattern could be drawn as a circle, an onion, or a set of concentric rectangles. What matters is the principle: dependencies point inward, the domain is sovereign, and infrastructure is a replaceable detail.

For systems built to last, where business rules are complex and infrastructure will inevitably evolve, that principle represents a worthwhile and enduring investment.

Key Takeaways

1. Hexagonal Architecture separates core business logic from external systems so that the two can evolve independently.
2. Unlike layered architecture, where the domain depends on infrastructure, hexagonal architecture inverts dependencies so that infrastructure depends on the domain.
3. The core contains domain models, business rules, and use cases. It defines what the system does and why it exists.
4. Ports are interfaces defined by the core. Input ports expose the application's capabilities to the outside world. Output ports describe what the core needs from the outside world.
5. Adapters implement ports using real technologies. Input adapters translate external requests into core operations. Output adapters fulfil the core's needs using databases, APIs, or other services.
6. Dependencies always point inward. The core depends on nothing external. Everything external depends on the core.
7. Testability improves significantly because the core can be tested in complete isolation using lightweight, in-memory substitutes for output ports.
8. Technologies become replaceable because changing infrastructure means writing a new adapter, not touching core logic.
9. The pattern can be applied within a single deployable unit, but also shapes how services communicate in distributed systems.
10. The pattern aligns naturally with Domain-Driven Design by creating the space for a rich, expressive domain model free from infrastructure pressure.
11. Common pitfalls include infrastructure leaking into the core, business logic migrating into adapters, and over-fragmenting ports into too-small interfaces.
12. The pattern adds most value for complex, long-lived systems with genuine business logic. For simple CRUD applications, the overhead may outweigh the benefits.
13. Maintaining the architecture requires sustained discipline, active code review, and a shared team understanding of the boundaries.