Hexagonal / Ports & Adapters

## What a port is Hexagonal Architecture, introduced by **Alistair Cockburn** in 2005, organizes an application around a central "application core" — the business logic and use cases — that is completely isolated from the technical details of how it's invoked or what it depends on. The mechanism for that isolation is the **port**: an interface, defined and owned by the core, that describes a capability in terms the business understands, with zero mention of any specific technology (no SQL, no HTTP, no message broker library). ## The two directions Ports split into two kinds based on the direction of the call. - **A driving port** (also called a primary or "left-side" port) is a contract the core exposes outward so something in the outside world can trigger it — think `PlaceOrderUseCase` with a method `placeOrder(command): OrderResult`. Adapters like a REST controller, a CLI command handler, or a Kafka consumer sit on the "driving" side; they translate an external request format into a call against this port, and the core's implementation of that port runs the actual business logic. - **A driven port** (secondary, "right-side" port) runs in the opposite direction: it's a contract the core defines because it needs something FROM the outside world — for example, an `OrderRepository` interface with `save(order)` and `findById(id)`, or a `PaymentGateway` interface with `charge(amount, method)`. The core calls methods on this interface, but the core does not implement it; a driven adapter — a JPA repository implementation, a Stripe API client — does, and is plugged in at the boundary. ## Why this exists The problem being solved is that in naive designs, business logic ends up directly calling framework and infrastructure code (a service class instantiating a `JdbcTemplate`, or calling `HttpServletRequest` directly), which means changing the database vendor, the web framework, or adding a second delivery mechanism forces changes deep inside the business logic. By making the core define its own contracts and never import a concrete infrastructure class, hexagonal architecture forces all dependency arrows to point **INTO** the core, regardless of whether the interaction is "driving" (core is called) or "driven" (core does the calling). This is what Cockburn meant by treating all technology adjacencies symmetrically — a UI and a database are both "just adapters" from the core's point of view, even though a UI drives the app and a database is driven by it. ## The trade-off The trade-off is **indirection and volume**: every capability the core needs gets an interface plus at least one concrete adapter, and every entry point gets an interface plus at least one adapter that calls it. For a small CRUD service with one UI and one database, this can roughly double the number of types for no immediate payoff — you're paying an abstraction tax before you have a second implementation to justify it. The benefit shows up when you actually need multiple adapters on either side, e.g.: - exposing the same `PlaceOrder` use case via both a REST API and an internal gRPC service — two driving adapters sharing one driving port and one core implementation; - swapping a real payment gateway for a test double or a different vendor — two driven adapters implementing one driven port — without touching business logic. ## Failure modes Failure modes show up when the port/adapter boundary is drawn in name only. 1. **A common one is a port interface that leaks adapter-specific concerns** — an `OrderRepository` port with a method like `findByJpqlQuery(String)` or `save()` returning a JPA entity — which means the "port" is really just the adapter's own interface relabeled, and swapping persistence technology still requires touching the core. 2. **Another is direction confusion**: teams sometimes have the core depend on a driving port's adapter (e.g., the core reaching back into a web-layer DTO), which reintroduces the exact coupling ports exist to prevent. 3. **A third is port explosion**: defining a separate driven port per external call site rather than per cohesive capability, which turns the core into an interface-heavy maze that's harder to navigate than the framework code it replaced. ## Putting it together A concrete illustration: an e-commerce checkout use case exposed both through a synchronous REST API and an asynchronous "abandoned cart" background job — both are driving adapters calling the same driving port (`CheckoutUseCase`). That use case, in turn, depends on driven ports for: - `InventoryPort` (checking stock) - `PaymentPort` (charging a card) - `OrderRepositoryPort` (persisting the order) In production these are backed by a real inventory microservice client, a Stripe adapter, and a Postgres repository, while in tests they're backed by in-memory fakes, letting the entire checkout business rule set be tested with no HTTP server, no real database, and no network call to Stripe — which is the testability payoff hexagonal design is chiefly valued for.