hexagonal-architecture

Define driving ports as interfaces named for the business capability, implement them with use case factories that take driven ports as parameters, and write thin adapters that translate between domain types and technology types. Wire everything at a composition root near the executable entrypoint.

Name ports by business purpose, not technology: use intention names like ForPlacingOrders for driving ports and role nouns like OrderRepository or PaymentGateway for driven ports. Avoid I prefixes, Port or Impl suffixes, and any name that breaks when an adapter is swapped.

Use in-memory fakes that implement the real port interface and maintain state. Fakes break at compile time when the interface changes and test behavior rather than call sequences, while mocks couple tests to incidental call order.

Do not apply it to projects that have not explicitly opted in, to simple CRUD endpoints with no business rules, or to stable code that rarely changes. The skill explicitly warns against inferring hexagonal architecture from a generic adapter, interface, or test seam.

Use the strangler fig approach: extract one tangled feature at a time by pulling business rules into pure domain functions, defining an application-owned port, wrapping existing database access in an adapter, and proving the boundary with a fake-based use case test before migrating further.

Authentication, technical telemetry, transactions, and error formatting live in adapters. Authorization rules live in the domain, and business-significant observations go through a severity-free driven probe port or domain events, never a raw logger in domain code.