hexagonal-architecture

Hexagonal architecture decouples business logic by structuring applications around ports and adapters, keeping core domain rules independent of transport and persistence layers. This separation allows use-case orchestration to remain pure and testable.

Refactoring mixed controller code involves splitting it into inbound and outbound ports with a dedicated use-case boundary. You can migrate slice-by-slice without a big-bang rewrite by moving protocol mapping to edge adapters.

Testing use cases with ports and adapters involves using fakes for unit tests to isolate business logic, while real adapters handle integration and E2E validation. This strategy ensures use-case orchestrators are tested independently of infrastructure.

Hexagonal architecture supports multiple interfaces by placing protocol mapping for HTTP, CLI, or queues at the system boundaries as edge adapters. Inbound ports define what the application offers, allowing various transport layers to connect seamlessly.

Hexagonal architecture may be excessive for simple systems that do not require high testability or multiple transport interfaces. The overhead of defining explicit inbound and outbound port contracts is best suited for scalable, complex use-case boundaries.

A composition root is required to explicitly wire edge adapters for protocol and infrastructure mapping to the application ports. This central wiring ensures domain logic remains independent of how dependencies are injected at runtime.