port-adapter-designer

Hexagonal architecture decouples core logic from external systems using ports—trait abstractions defining what your domain needs—and adapters implementing those traits for specific technologies like PostgreSQL or HTTP clients. This separation enables testing with mock adapters and swapping implementations without changing core code.

Ports are domain-typed traits defining boundaries between your core logic and external systems; adapters are concrete implementations of those ports for specific technologies. Repository ports abstract database access, service ports handle external APIs, and notification ports manage outbound communication, each with sync and async variants supporting dependency injection and testing.

Define trait boundaries for each integration point: repository ports for data access, external service ports for API calls, notification ports for outbound events. Implement concrete adapters—PostgreSQL repositories, HTTP client services, in-memory implementations—behind those traits, mapping external errors to domain types and ensuring Send + Sync safety for async-first designs.

Yes; ports are async-by-default, with trait methods supporting async operations natively. Adapters like HTTP clients and database drivers work seamlessly with async runtimes, and in-memory test implementations maintain the same async interface, enabling consistent testing across sync and asynchronous integration boundaries.

Ports and adapters isolate core domain logic from framework and library details, making code testable by swapping real adapters for mocks, maintainable by centralizing integration points, and flexible by supporting multiple implementations—PostgreSQL, file systems, or in-memory stores—without touching business logic.

Map external system errors to domain-typed errors at adapter boundaries, translating database or HTTP failures into application-specific result types. This preserves domain semantics, enables meaningful error recovery in core logic, and prevents framework-specific error types from leaking into business code.