# Hexagonal Architecture > Applies hexagonal (ports & adapters) architecture. Use when designing application structure, separating domain from infrastructure, creating testable boundaries, or when user mentions ports, adapters, hexagonal, or clean architecture. Use when this capability is needed. - Skill: `tomevault-io/hexagonal-architecture` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hexagonal-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hexagonal-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hexagonal-architecture --- # Hexagonal Architecture ## The Core Decision Rule To decide if something belongs inside or outside the hexagon, ask: > "Does it do I/O or run out-of-process?" - **No** → Inside the hexagon (domain or application layer) - **Yes** → Outside (adapter) **Critical:** Consider ALL dependencies. A component's dependencies disqualify it even if the component itself doesn't do I/O. If it depends on Spring, a database driver, or any framework—it's outside. ## Layer Responsibilities **Common misconception:** The hexagon is NOT just the domain. The hexagon contains both domain AND application layers. Adapters sit outside. ``` ┌─────────────────────────────────────────┐ │ ADAPTERS (outside) │ │ Web, CLI, Database, External APIs │ │ ┌───────────────────────────────────┐ │ │ │ APPLICATION SERVICES │ │ │ │ ┌─────────────────────────────┐ │ │ │ │ │ DOMAIN │ │ │ │ │ └─────────────────────────────┘ │ │ │ └───────────────────────────────────┘ │ └─────────────────────────────────────────┘ Dependencies flow INWARD only ``` **Domain** — Business constraints (what CAN happen). Contains Entities, Value Objects, Domain Services. **Application** — Orchestration (HOW things happen). Contains Use Cases, Application Services. **Adapters** — Translation to/from external world. Contains Controllers, Repositories, API clients. **Domain defines ports (interfaces). Adapters implement them.** ## Naming Conventions - Display/response: `*View` or `*Response` → `MemberView`, `OrderResponse` - Incoming request: `*Request` → `CreateMemberRequest` - Database entity: `*Dbo` → `MemberDbo` - Domain → DTO: `static from(domain)` → `MemberView.from(member)` - DTO → Domain: `as*()` method → `request.asMember()` ## Anti-Patterns ### Brittle Interfaces ``` register(username, password) // Breaks when email required ``` Use wrapper objects that can evolve without breaking signatures. ### Domain Scope Pollution Third-party types (`GoogleUser`, `StripePayment`) leaking into domain. Keep external types in adapters; map to domain types at the boundary. ### Use-Case Interdependencies Use cases calling other use cases creates coupling. Each use case should be self-contained, orchestrating domain objects directly. ### Anemic Domain Entities as data bags with logic scattered in services. Business rules belong IN entities and value objects. ### Premature Database Design Designing schema before domain model. Domain model comes first; database adapter maps to it. ### Over-Complicated Adapters Adapters adding logic beyond translation. Adapters should be thin—just implement the port interface. ## Testing Strategy - **Domain**: Unit tests, no doubles needed (pure logic) - **Application**: Unit tests with port doubles (fake repositories, stub notifiers) - **Adapters**: Integration tests against real infrastructure (real database, real HTTP) Ports give clean seams for test doubles. Test the domain exhaustively with fast unit tests; test adapters against real infrastructure sparingly. ## When NOT to Use - Small/simple projects, especially CRUD-based apps (overhead not worth it) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lexler) — claim your Tome and manage your conversions.