hexagonal-architecture

Define port interfaces in the domain layer named by business purpose, then create driven adapters that implement them for specific technologies like databases or payment gateways. Driving adapters such as route handlers stay thin: parse input, wire adapters, call the use case, and translate the result.

Test use cases by injecting in-memory fakes that implement the real port interfaces and maintain state. Fakes break at compile time when interfaces change and verify behavior rather than call sequences, unlike mocks.

Writes should go through repositories to enforce aggregate boundaries, but reads that JOIN across aggregates can use query functions living in the adapter layer. This CQRS-lite approach returns read-optimized DTOs while domain pure functions transform the data.

Authentication lives in driving adapters since it is protocol-specific, while authorization rules belong in the domain. Logging is an adapter concern on both sides; domain code never imports a logger and instead returns results that adapters inspect.

Do not apply it to projects without an explicit ports/adapters structure or to simple CRUD endpoints with no business logic, where the pattern adds overhead without benefit. Stable code that rarely changes is also a low-priority migration candidate.

Use the strangler fig approach: pick one tangled route handler, extract the business rule into a pure domain function, define a port interface, wrap existing database access in an adapter, and thin out the handler. Migrate one boundary at a time and prove each with a fake-based use case test.