hexagonal-architecturelisted

# Hexagonal Architecture — Ports & Adapters A practical playbook for building business-logic-first systems where the domain is shielded from frameworks, transports, and persistence. Pattern by Alistair Cockburn (2005); proven across two decades of Java, .NET, Go, Python, and TypeScript codebases. ## When to Use This Skill Invoke this skill **before** writing the first business-logic file in a new service, **or** when you find yourself: - Writing tests that mock five frameworks just to assert one business rule - Wanting to add a CLI / cron / queue-consumer entry point but every code path threads through HTTP request/response objects - Replacing PostgreSQL with another store and discovering business code imports `sqlalchemy` directly - Asking "where does the *real* logic live?" and finding the answer is "scattered across controllers" - Planning a long-lived system where the current framework will be obsolete in 5 years **Skip** for: throwaway scripts, one-off scrapers, CRUD-only admin tools where the framework IS the application. ## The Three Layers ``` ┌─────────────────────────────────────────────────────────────┐ │ ADAPTERS (infrastructure + delivery) │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ HTTP route │ │ CLI command │ │ Queue worker │ │ ← inbound │ └──────┬──────┘ └──────┬──────┘ └──────┬───────┘ │ │ │ │ │ │ │ ▼ ▼