Hexagonal Architecture Diagram: Ports and Adapters Pattern Explained (2026)
How to draw a hexagonal architecture diagram. Covers the domain core, primary and secondary ports, adapters, and how hexagonal architecture compares to layered, onion, and clean architecture — with prompt templates.
Hexagonal architecture — also called the Ports and Adapters pattern — is a software design approach introduced by Alistair Cockburn that places the application's core business logic at the center and isolates it from external systems (databases, UIs, message queues, third-party APIs) through a consistent layer of ports and adapters. The result is a domain that is independently testable, technology-agnostic, and easy to evolve as external dependencies change.
Hexagonal architecture has seen a major resurgence in 2026 as teams adopt AI-generated code, microservices, and rapid iteration practices that demand clean separation between business logic and infrastructure. A well-drawn hexagonal architecture diagram communicates the core boundaries clearly to the whole team — which logic is domain-owned, which is adapter-owned, and where the system's extension points are.
Hexagonal architecture core concepts
The domain core (the hexagon)
The center of a hexagonal architecture is the application core: all business logic, domain entities, use case orchestration, and domain services. The core has zero knowledge of how it is called or what infrastructure it runs on. It does not import your ORM, your HTTP framework, or your cloud SDK. In your diagram, the hexagon represents this core — everything inside it is pure domain logic.
Ports
Ports are the interfaces that define how the domain core communicates with the outside world. They live at the boundary of the hexagon and come in two types:
- Primary (driving) ports — interfaces through which external actors (users, other services, schedulers) call into the core. Examples:
OrderServiceinterface,PaymentUseCaseinterface. In the diagram, primary ports are on the left side of the hexagon. - Secondary (driven) ports — interfaces through which the core calls out to external infrastructure. Examples:
OrderRepository,EmailSender,PaymentGateway. In the diagram, secondary ports are on the right side of the hexagon.
Adapters
Adapters implement the ports and bridge the gap between the domain core and the real world. There is one adapter per external concern, each translating between the port interface and the specific technology:
- Primary (driving) adapters — call into the primary ports. Examples: REST controller, GraphQL resolver, CLI command handler, gRPC service, Temporal Activity wrapper. These adapt inbound requests into domain use case calls.
- Secondary (driven) adapters — implement the secondary ports. Examples: PostgreSQL repository, Redis cache adapter, Stripe payment adapter, SendGrid email adapter, Kafka producer adapter. These adapt the domain's outbound calls to specific infrastructure.
Example hexagonal architecture diagrams
1. E-commerce order service
2. AI-powered content moderation service
3. Multi-tenant SaaS application
Hexagonal vs. layered vs. clean vs. onion architecture
| Pattern | Core metaphor | Primary benefit | Common usage |
|---|---|---|---|
| Hexagonal (Ports & Adapters) | Inside/outside boundary, symmetrical | Testability, adapter swappability | DDD, microservices, testable services |
| Layered (N-tier) | Horizontal layers (UI → Logic → Data) | Simplicity, familiar structure | CRUD apps, MVC frameworks, monoliths |
| Clean Architecture | Concentric circles, dependency rule | Explicit dependency rule (inward only) | Enterprise apps, Uncle Bob followers |
| Onion Architecture | Concentric rings, domain at center | DDD alignment, infrastructure isolation | .NET enterprise apps, DDD practitioners |
The key practical difference: hexagonal architecture is symmetric (both the UI adapter and the DB adapter are “outside” at the same level), while layered architecture implies a top-to-bottom dependency direction. Clean and Onion architectures are closely related to Hexagonal and share the dependency inversion principle, but emphasize slightly different ring structures. In practice, the choice is often less important than consistently applying the core rule: domain logic does not depend on infrastructure.
Hexagonal architecture with AI-generated code
Hexagonal architecture is especially valuable when using AI coding tools like Claude Code or Cursor. AI tools generate code most reliably at the adapter layer — writing a new PostgreSQL repository implementation, generating a REST controller, or producing a Stripe adapter — because these have clear, well-defined interfaces (the port) that constrain the output. The domain core, with its rich business invariants and complex logic, benefits from human authorship and review. A hexagonal diagram makes this division of labor explicit for the whole team.
Frequently asked questions about hexagonal architecture
What is hexagonal architecture?
Hexagonal architecture (Ports and Adapters) is a software design pattern that isolates the application's business logic (the domain core) from external concerns (databases, UIs, external APIs) via a symmetric layer of ports (interfaces) and adapters (implementations). The domain core has no dependencies on infrastructure; all infrastructure dependencies are inverted so that adapters depend on domain-defined port interfaces, not the other way around.
Why is it called hexagonal architecture?
Alistair Cockburn chose a hexagon shape because a hexagon has six sides, which conveniently illustrates that there can be many ports — more than the two (left and right) implied by a rectangle. The number six is not meaningful; the hexagon is a symbolic choice to show a boundary with multiple potential connection points. In diagrams, the hexagon represents the application core boundary.
What is the difference between a port and an adapter in hexagonal architecture?
A port is an interface (or abstract contract) that defines how the domain core communicates with the outside world. An adapter is the concrete implementation of that interface for a specific technology. For example, EmailSenderPort is the port (interface with a send() method defined in domain terms); SendGridEmailAdapter is the adapter (the concrete class that calls the SendGrid REST API). You can swap the adapter without changing the domain — switch from SendGrid to Resend by writing a new adapter, not touching domain code.
Related guides: Software architecture patterns, Microservice architecture patterns, Event sourcing and CQRS architecture, and C4 model architecture diagrams.
Ready to try it yourself?
Start Creating - Free