The Hexagonal (Ports & Adapters) Paradigm
When To Use
- Isolating business logic from external dependencies
- Systems needing swappable adapters for testing
When NOT To Use
- Small scripts or utilities without external dependencies
- Prototypes where port/adapter abstraction adds overhead
When to Employ This Paradigm
- When you anticipate frequent changes to databases, frameworks, or user interfaces and need the core domain logic to remain stable.
- When testing the core application requires mocking complex or slow infrastructure components.
- When the development team needs to provide clear inbound and outbound interfaces for third-party integrations.
Adoption Steps
- Define Domain Ports: Identify all interactions with the core domain. Define inbound "driver ports" for actors that initiate actions (e.g., UI, CLI, automated jobs) and outbound "driven ports" for services the application consumes (e.g., database, message bus, external APIs). Express these ports as formal interfaces.
- Implement Adapters at the Edge: For each external technology, create an "adapter" that implements a port's interface. Keep the core domain entirely ignorant of the specific frameworks or libraries used in the adapters.
- Aggregate Use Cases: Organize the application's functionality into services that are built around business capabilities. These services orchestrate calls to the domain through the defined ports.
- Implement Contract Testing: validate that each adapter correctly honors the expectations of the port it implements. Use contract tests or consumer-driven contract tests to validate this behavior.
- Enforce Dependency Rules: The most critical rule is that only adapters may have dependencies on external frameworks. Enforce this with automated architecture tests or static analysis rules.
Key Deliverables
- An Architecture Decision Record (ADR) that formally names the ports, their corresponding adapters, and the dependency policies.
- A set of port interface definitions, stored with the core domain module.
- A suite of contract tests for each adapter, alongside unit tests for the domain and application services.
- Architectural diagrams showing the inbound and outbound data flows, for use by operations teams and architecture reviewers.
Risks & Mitigations
- Port/Interface Bloat:
- Mitigation: An excessive number of ports can increase maintenance overhead. Group related operations into more cohesive, higher-level ports, often organized around domain aggregates.
- Leaky Abstractions:
- Mitigation: If a port's interface exposes details about the transport layer (e.g., HTTP headers), it is a "leaky abstraction." Refactor these interfaces to use domain-centric Data Transfer Objects (DTOs) instead.
- Adapter Drift:
- Mitigation: An adapter can become out-of-sync with the external technology it represents (e.g., database schema changes). Schedule regular, automated validation of adapters, such as verifying that SQL migrations still align with the expectations of the persistence port.
Concrete Components
These vocabulary items name the concrete tools and abstractions
that show up when the paradigm is implemented. They are not
required dependencies and they are not part of the skill's
tools: frontmatter (which is reserved for Claude Code tool
restrictions). Use this list to disambiguate during architecture
discussions.
boundary-validator— checks every adapter conforms to the port contractadapter-generator— scaffolds primary and secondary adapters from a port speccontract-tester— validates each adapter against its port via shared contract tests