hexagonal-architecture

Define port interfaces in application/ports, implement use cases with constructor injection of those ports, and place concrete adapters in adapters/inbound and adapters/outbound. Wire everything in an explicit composition root factory module without hidden globals.

Use the strangler approach: pick one vertical slice, extract a use case boundary with explicit input/output types, wrap existing infrastructure behind outbound ports, and keep old adapters delegating to the new use case. Add characterization tests before extraction and migrate slice-by-slice.

Inbound ports are contracts describing what the application can do, such as command and query interfaces called by controllers. Outbound ports are contracts for dependencies the application needs, like repositories, payment gateways, and event publishers, implemented by infrastructure adapters.

Yes, the same boundary rules apply across ecosystems. In Java use packages like application.port.in and adapter.out with Spring config wiring, while in Go define small interfaces owned by the consuming application package and wire constructors in main.go.

Avoid it for simple CRUD scripts or prototypes where the overhead of ports, adapters, and composition roots outweighs maintainability benefits. It pays off when you need multiple interfaces, replaceable infrastructure, or long-term testability of business rules.

Unit test use cases with in-memory fakes or stubs for outbound ports, asserting business outcomes and port interactions. Separately run adapter integration tests against real infrastructure and contract test suites shared across adapter implementations.