hexagonal-architecture

Define port interfaces in application/ports, write use cases that receive ports via constructor injection, and implement adapters under adapters/inbound and adapters/outbound. Wire everything in an explicit composition root factory instead of hidden global singletons.

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

Inbound ports are contracts describing what the application can do, called by inbound adapters like HTTP controllers or CLI handlers. Outbound ports are contracts for dependencies the application needs, such as repositories, payment gateways, and clocks, implemented by outbound adapters.

Yes, the same boundary rules apply across Java with Spring, Kotlin with Koin or Dagger, and Go with small interfaces and explicit constructors. Framework annotations stay optional and wiring lives in a dedicated configuration or main package, never in domain classes.

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