Ports and adapters

What a port actually is

The word “port” in hexagonal architecture is borrowed from hardware: a port is a socket — a defined protocol for connecting. In software, a port is an interface that the application itself defines. This ownership is what distinguishes hexagonal architecture from layered architecture.

In the B2B order platform, the application might define a port like this:

// Defined inside the application — in the domain's own package
interface OrderConfirmationPort {
  confirmOrder(orderId: string, approverId: string): Promise<ConfirmationResult>;
}

This interface is owned by the application. It expresses what the application can do — in domain language, not in HTTP language or CLI language. The application defines the contract; the outside world must conform to it.

This is the inversion that distinguishes hexagonal from layered architecture. In a standard layered stack, the application layer calls OrderRepository, which is an infrastructure class — the application depends on infrastructure. In hexagonal, the application defines IOrderRepository as a port — infrastructure depends on the application’s interface definition. The dependency arrow runs from infrastructure toward the domain, never the other way.

What an adapter actually is

An adapter is any component that translates between the outside world and a port. An adapter either:

• Calls a port (the HTTP controller calls OrderConfirmationPort.confirmOrder when a POST request arrives)
• Implements a port (the PostgresOrderRepository implements IOrderRepository to fulfil the domain’s data needs)

The critical insight is that these two categories are symmetric. The HTTP controller and the PostgreSQL repository are both adapters — one on the left side of the hexagon (calling in), one on the right side (called out). They are structurally equivalent: each one is a translation layer between an external technology and a port interface.

This symmetry is what makes the architecture’s name apt. The hexagon has faces, and each face can have a port. An HTTP adapter plugs into one face; a gRPC adapter could plug into the same face (using the same port). A PostgreSQL adapter plugs into a different face; an in-memory adapter could plug into the same face. The application core does not know or care which adapters are plugged in.

The symmetry: UI and database are both just adapters

This is the most practically useful consequence of hexagonal architecture. The HTTP layer is not privileged — it is just the adapter that translates HTTP requests into port calls. The database is not privileged — it is just the adapter that implements the repository port. Both are external to the application core.

This has an immediate structural consequence: you can swap either side independently. Swap the HTTP adapter for a gRPC adapter — the application core does not change. Swap PostgreSQL for DynamoDB — the application core does not change. Add a CLI adapter alongside the HTTP adapter — the application core does not change. This is exactly what the B2B order platform was missing: if the order confirmation logic had lived behind a single OrderConfirmationPort, the HTTP controller, CLI adapter, and batch job adapter would all have called the same port. One bug fix in one place.

Ports as the application’s API and SPI

There are two categories of port, which map directly to the two sides of the hexagon:

Primary ports (API — Application Programming Interface) define how the outside world drives the application. They are the use cases the application exposes. In the B2B platform: OrderConfirmationPort, InvoiceGenerationPort, BillingApprovalPort. Driving adapters call these ports.

Secondary ports (SPI — Service Provider Interface) define what the application needs from infrastructure. The application calls these ports; infrastructure implements them. In the B2B platform: IOrderRepository, IPaymentGateway, IEmailNotifier, IEventPublisher. These are exactly the dependency-inverted interfaces from unit 02 — DIP applied at the architectural boundary.

The names API and SPI come from the Java ecosystem but the concept is universal. The application defines both sides: what it offers (API/primary ports) and what it requires (SPI/secondary ports). The outside world must conform to both.