hexagonal-architecturelisted

# Hexagonal architecture Also called ports and adapters. The idea is a hard rule: the domain depends on nothing, and everything depends on the domain. When the HTTP handler and the SQL query bleed into the business rules, you cannot test the rules without a server and a database, and you cannot change either without risking the rules. ## Method 1. **Define ports as interfaces the domain owns.** A port is a Python Protocol, a Java interface, a Go interface declared inside the domain package. The domain names the shape it needs, `PaymentGateway.charge(amount)`, and never imports the thing that fulfills it. 2. **Keep the domain import-clean.** No `import requests`, no ORM base class, no framework annotation inside the core. Grep the domain package for your web and database libraries: a single hit is a leak to fix, not to tolerate. 3. **Split ports into driving and driven.** Driving (primary) ports are how the outside calls in: a use-case interface a REST controller invokes. Driven (secondary) ports are how the domain calls out: repositories, gateways, clocks. Naming the two directions keeps the wiring legible. 4. **Put every concrete detail in an adapter.** The REST adapter drives a primary port; the Postgres adapter implements a secondary port; a Stripe adapter implements the payment port. Each adapter is replaceable without the domain noticing. 5. **Wire everything at a composition root.** One place, usually `main`, that constructs adapte