hexagonal-archlisted

# Hexagonal Architecture — Ports & Adapters The pattern, distilled: **the domain core knows nothing about the world**. Everything that touches the outside (HTTP, DB, queue, cron, third-party API) is an adapter. Adapters depend on the domain; the domain never depends on adapters. Pairs with [ddd-architect](../ddd-architect/SKILL.md) — DDD answers "what's in the domain"; hexagonal answers "where does the domain live and what touches it". ## 1. The pattern Three layers, named by their role rather than their location: - **Domain core** — entities, value objects, aggregates, domain services, business policies. Plain language types and functions. No imports from any framework, database driver, or HTTP library. - **Ports** — interfaces declared *by the domain* describing what it needs from the outside (`UserRepo`, `EmailSender`, `PaymentGateway`). The names are domain-meaningful, not technology-meaningful (`UserRepo`, not `PostgresClient`). - **Adapters** — concrete implementations of ports. Live outside the domain. One adapter per concrete technology: `PostgresUserRepo`, `SmtpEmailSender`, `StripePaymentGateway`. Also one per testing strategy: `InMemoryUserRepo`, `FakeEmailSender`. The diagram is conventionally a hexagon (the "hex" in hexagonal) — the shape doesn't matter; the direction of arrows does. ## 2. Dependency direction — always inward This is the single non-negotiable rule. ``` HTTP handler → application service → domain service → aggregate