Published: 08.01.2026
From the book Architecture for Flow: Adaptive Systems with Domain-Driven Design, Wardley Mapping, and Team Topologies by Susanne Kaiser Addison-Wesley, September 2025.
Ports and Adapters (also known as hexagonal) is an architectural pattern where the core application logic talks to the outside world only through abstract ports, and concrete adapters implement those ports to integrate with real technologies like databases, message queues, or UIs.
Ports
- A port is an interface or abstraction defined by the application core that describes what it needs or offers (e.g. “load user”, “save order”) without mentioning any specific technology.
- Ports can be inbound (how external clients call the core) or outbound (how the core calls external systems), and they keep the domain logic independent of frameworks, databases, and protocols.
Adapters
- An adapter is concrete code that implements a port and knows how to translate between the core’s model and a specific technology, such as HTTP, SQL, files, or an external API.
- The same port can have multiple adapters (for example, REST and GraphQL on the input side, or SQL and DynamoDB on the output side), which can be swapped without changing the core logic.
The Ports and Adapters architecture divides software components into an inner core and an outer layer. Ports and adapters serve as the connection points, linking external actors to the inner core (driving or primary) and enabling the inner core to interact with external systems (driven or secondary). This architectural pattern isolates the business logic from environmental concerns. As a result, changes to external components do not affect the core business logic; only the corresponding adapters in the outer layer need to be modified.
Picture source: https://www.youtube.com/watch?v=bDWApqAUjEI&t=322s
Below is a further detailed figure and an example how Ports and Adapters can be applied to a single bounded context with Domain-driven Design tactical design patterns. Source of this information is ‘Architecture for Flow: Adaptive Systems with Domain-Driven Design, Wardley Mapping and Team Topologies‘ by Susanne Kaiser.
Ports and Adapters Architecture (click to enlarge) | Ports and Adapters (Hexagonal Architecture), introduced by Alistair Cockburn, isolates business logic from external systems by using ports as boundaries and adapters to connect actors such as UIs, databases, or message brokers. This separation decouples the core application from its environment, enabling changes to external components without affecting business logic and improving testability. The pattern fits well with DDD tactical design, especially within a single bounded context. Business logic resides at the center, often implemented as a domain model, while repositories act as driven ports for persistence and application services as driving ports for external clients. |
This figure presents a simplified example of the CfPManagement bounded context implemented using DDD tactical patterns and the Ports and Adapters architecture (click to enlarge) | CfPManagement exposes a public RESTful API over HTTP, implemented with Java and Spring Boot. The CfpRestAPI acts as a driving adapter, exposing REST endpoints to external clients. It delegates requests to the CfpManagement driving port, which is implemented by the CfpApplicationService. The application service coordinates transactions, security, and interactions with the domain model and repository. The core domain is modeled as a CfPaggregate consisting of a CfpEntity as the aggregate root and immutable value objects. All state-changing operations (define, open, reschedule, close) enforce business rules, ensuring the aggregate remains consistent at all times. Persistence is handled via the CfpRepository driven port. Its MongoDB-based implementation, MongoDBCfpRepository, acts as a driven adapter and uses a MongoDB client to store and retrieve aggregate state. Mapping between the domain model and MongoDB DTOs occurs in the outer layer, keeping the domain free from infrastructure concerns and allowing independent evolution. |
Ports and Adapters fits well with tactical design, but it is not the only suitable architectural pattern. It is particularly effective for complex, evolving domains with high uncertainty where flexibility is essential; for simple applications or short-lived prototypes, however, the additional complexity is often unnecessary.
Pros and Cons of Ports and Adapters
Pros | Cons |
Testability: If you have ever tried writing unit tests for application after it has already been written without testing in mind you will know how much of a pain it is. When a component is tightly coupled to others it can be impossible to test in isolation. With hexagonal architecture, this isn’t going to be an issue as everything is using abstractions by design. Maintainability: As your application is completely decoupled from the technologies that you are using it becomes a lot easier to maintain. If you need to switch out the database for a different one you only need to change the adapter being used and not the application itself. Flexibility: As with maintainability, it gives you a lot more flexibility with how your application is structured. If you wanted to add in some additional data processing before data is saved you can do this in the adapter or even connect it to another hexagon to do the processing. | Complexity in code: The hexagonal architecture does mean you are going to need to write more code in order to decouple everything. Instead of having your code call the database directly you now need a port and adapter. Complex when running locally: Depending on how far you take this approach if you end up with multiple components running in isolation you may need to do a bit more work when running your application locally. Anyone who has worked on a micro-service architecture will know the pain of having to spin up 20 docker containers to run the application on your machine. Performance considerations: There are potential performance issues if you take this pattern to the extreme. If all communication is happening over API you might introduce additional latency to your application which could become a problem when your application needs to scale. |
Data fidelity
In the Ports and Adapters architecture, domain logic sits at the center and is surrounded by ports and adapters that connect it to the surrounding ecosystem. Although the pattern predates microservices, it shares several similarities with them. One key difference lies in data ownership: while hexagonal architecture treats the database as just another pluggable adapter, insights from Domain-Driven Design suggest that data schemas and transactional boundaries should be part of the inner core, as they are in microservices.