hexagonal-architecturelisted

# Hexagonal Architecture (TypeScript / Node) Hexagonal architecture (Ports and Adapters) keeps business logic independent from frameworks, transport, and persistence. The core depends on abstract ports; adapters implement those ports at the edges. ## When to Use - New features where long-term maintainability and testability matter. - Refactoring layered/framework-heavy code where domain logic is mixed with I/O. - Supporting multiple interfaces for the same use case (HTTP, CLI, queue workers, cron jobs). - Replacing infrastructure (DB, external APIs, message bus) without rewriting business rules. ## Core Concepts - **Domain model** — business rules and entities/value objects. No framework imports. - **Use cases (application layer)** — orchestrate domain behavior and workflow steps. - **Inbound ports** — contracts describing what the application can do (commands/queries/use-case interfaces). - **Outbound ports** — contracts for dependencies the app needs (repositories, gateways, event publishers, clock, UUID). - **Adapters** — infrastructure and delivery implementations of ports (HTTP controllers, DB repositories, queue consumers, SDK wrappers). - **Composition root** — single wiring location where concrete adapters are bound to use cases. Outbound port interfaces usually live in the application layer (or domain only when the abstraction is truly domain-level); infrastructure adapters implement them. Dependency direction is always inward: - Adapters → application/domain