Hexagonal Architecture, also known as Ports and Adapters pattern, is a software design approach that creates loosely coupled, testable, and maintainable applications. If you've ever struggled with tangled dependencies or found it difficult to swap out frameworks, this architecture might be your solution.
What is Hexagonal Architecture?
Hexagonal Architecture separates your application into distinct layers, with your business logic at the center, completely isolated from external concerns like databases, APIs, or user interfaces. The "hexagon" shape is symbolic—it represents that your core application can have multiple sides, each connecting to different external systems through well-defined interfaces.
Created by Alistair Cockburn in 2005, this pattern solves a common problem: applications become tightly coupled to their frameworks, databases, and external services, making them rigid and difficult to test or modify.
The Core Concepts
The Domain (Inside the Hexagon)
The innermost layer contains your business logic and domain models. This is the heart of your application—the rules, calculations, and workflows that define what your application does. This layer knows nothing about databases, web frameworks, or external APIs.
Ports (The Interfaces)
Ports are the entry and exit points of your application. They're simply interfaces that define how the outside world can interact with your domain. There are two types: primary ports (driving ports) that allow external actors to use your application, and secondary ports (driven ports) that your application uses to interact with external systems.
Adapters (The Connectors)
Adapters are concrete implementations that connect the real world to your ports. A REST controller is an adapter that translates HTTP requests into calls to your domain. A database repository is an adapter that translates your domain's storage needs into actual database operations.
How Hexagonal Architecture Works
Imagine you're building an e-commerce application. Your domain contains business rules like "calculate order total," "apply discount codes," and "validate inventory." This logic shouldn't care whether orders come from a web browser, mobile app, or API.
Primary Adapters (Driving)
When a user places an order through your web interface, a REST controller adapter receives the HTTP request, translates it into a domain command, and passes it through a primary port to your domain logic. The domain processes the order without knowing anything about HTTP or JSON.
Secondary Adapters (Driven)
When your domain needs to check inventory, it calls a secondary port interface like InventoryRepository. An adapter implementing this interface translates the call into actual database queries. Your domain doesn't know if inventory data comes from PostgreSQL, MongoDB, or an external API—it just uses the port interface.
This separation means you can swap MySQL for PostgreSQL, replace your REST API with GraphQL, or add a mobile app interface without touching your business logic.
Key Benefits
Testability
Since your domain logic doesn't depend on external systems, you can test it in isolation using mock implementations of your ports. No need to spin up databases or external services for unit tests. Testing becomes faster and more reliable.
Flexibility
Want to try a different database? Switch from REST to GraphQL? Add a CLI interface? Just create new adapters without modifying your core business logic. This flexibility is invaluable as requirements evolve.
Technology Independence
Your business logic isn't locked into any framework or technology. If a better framework emerges, you can migrate without rewriting your domain. This protects your investment in the most valuable part of your codebase.
Clear Boundaries
The architecture enforces clear separation of concerns. Developers immediately understand where different types of code belong. Business logic stays in the domain, infrastructure code stays in adapters.
Practical Implementation Example
Let's look at a simple order processing flow:
Your domain defines a port interface:
OrderService (port) - with method processOrder()
The domain implements the business logic without external dependencies. It also defines what it needs from the outside:
PaymentGateway (port) - with method charge()
OrderRepository (port) - with method save()
Adapters provide concrete implementations:
- RestOrderController implements the primary adapter to receive web requests
- StripePaymentAdapter implements PaymentGateway for Stripe integration
- PostgresOrderRepository implements OrderRepository for database storage
When a request comes in, it flows: REST Controller → OrderService (domain) → Payment and Repository adapters. The domain orchestrates the business logic while adapters handle technical details.
When to Use Hexagonal Architecture
This architecture shines in applications where business logic complexity justifies the additional structure. It's ideal for long-lived applications that need to evolve, systems requiring multiple interfaces (web, mobile, API, CLI), or projects where technology decisions might change.
For simple CRUD applications or prototypes, hexagonal architecture might be overkill. The added abstraction layers can feel like unnecessary ceremony when your application logic is straightforward.
Getting Started
Start by identifying your core business logic and separating it from infrastructure concerns. Define port interfaces for external interactions. Create adapters to connect real implementations to your ports. Remember, you don't need to implement everything perfectly from day one—apply the pattern where it adds value and refactor gradually.
The key insight of Hexagonal Architecture is simple: keep your business logic pure and isolated, and connect to the outside world through well-defined interfaces. This seemingly simple principle leads to applications that are easier to test, maintain, and evolve over time.
Top comments (0)