hexagonal-architecture

Define outbound port interfaces in the application layer, write use cases that receive ports via constructor injection, and implement adapters for databases and external APIs. Wire everything in an explicit composition root factory rather than using hidden global singletons.

Inbound ports are contracts describing what the application can do, such as commands and queries called by controllers. Outbound ports are contracts for dependencies the application needs, such as repositories, payment gateways, and event publishers.

Use a strangler approach: pick one vertical slice, extract a use-case boundary with explicit input and output types, wrap existing infrastructure behind outbound ports, and add characterization tests. Migrate slice-by-slice instead of rewriting everything at once.

Yes. In Java and Kotlin, ports are interfaces in application.port packages and use cases are plain classes where Spring annotations are optional. Keep wiring in configuration classes so framework specifics never leak into domain or use-case code.

Unit test use cases with in-memory fakes or stubs implementing the outbound port interfaces, asserting business outcomes and port interactions. Separately run adapter integration tests against real infrastructure to verify queries, serialization, and timeouts.

Avoid it for trivial CRUD scripts or prototypes where the indirection of ports and adapters adds cost without payoff. It pays off when long-term maintainability, multiple delivery interfaces, or infrastructure replaceability actually matter.