Ports and adapters

A port is an interface the domain owns; the domain declares what it needs, never what provides it. The domain says “to do my job I need to charge a payment” — and writes the interface for exactly that, in domain language, living in domain code:

// domain/ports/PaymentPort.ts — owned by the domain, names a domain need
export interface PaymentPort {
  charge(amountCents: number, idempotencyKey: string): Promise<ChargeResult>;
}
export type ChargeResult = { ok: true; receiptId: string } | { ok: false; reason: string };

Notice what is absent: no Stripe, no HTTP, no API key, no SDK type. The port speaks the domain’s vocabulary (amountCents, idempotencyKey, ChargeResult), not the vendor’s. This is the inversion: the high-level policy (the domain) defines the abstraction, and the low-level detail (Stripe) will be forced to conform to it — not the other way around. The port is the contract the domain is willing to depend on.

An adapter is an implementation living in infrastructure; it implements the domain’s port and absorbs the vendor. Stripe’s existence is now a fact confined to one file at the edge:

// infrastructure/StripeAdapter.ts — implements the DOMAIN's port
import Stripe from "stripe";
import type { PaymentPort, ChargeResult } from "../domain/ports/PaymentPort";

export class StripeAdapter implements PaymentPort {
  constructor(private stripe: Stripe) {}

  async charge(amountCents: number, idempotencyKey: string): Promise<ChargeResult> {
    try {
      const intent = await this.stripe.paymentIntents.create(
        { amount: amountCents, currency: "usd", confirm: true },
        { idempotencyKey },
      );
      return { ok: true, receiptId: intent.id };
    } catch (e) {
      return { ok: false, reason: stripeReason(e) }; // translate vendor errors to domain terms
    }
  }
}

The adapter’s whole job is translation: domain language in, vendor calls out, vendor errors mapped back to ChargeResult. The domain depends on PaymentPort; StripeAdapter depends on PaymentPort too (it implements it) and on Stripe. The arrow from infrastructure points into the domain. Stripe is now a leaf, not a root — replaceable by writing a second adapter, with nothing in the domain to touch.

The domain uses the port and stays ignorant of the implementation — the dependency is injected at the edge. The use case is written entirely against the port:

// domain/PlaceOrder.ts — pure policy, zero vendor knowledge
export class PlaceOrder {
  constructor(private payments: PaymentPort) {} // depends on the port, not Stripe

  async run(order: Order): Promise<OrderResult> {
    if (order.totalCents <= 0) return { status: "rejected", reason: "empty order" };
    const charge = await this.payments.charge(order.totalCents, order.id);
    if (!charge.ok) return { status: "declined", reason: charge.reason };
    return { status: "placed", receiptId: charge.receiptId };
  }
}

PlaceOrder is the stable center. It can be read, reasoned about, and changed without ever opening Stripe’s docs. The wiring — “in production, PaymentPort is a StripeAdapter” — happens once, in a composition root at the outermost edge:

// main.ts — the only place that knows both sides
const placeOrder = new PlaceOrder(new StripeAdapter(stripe));

That single line is where the abstract meets the concrete. Everything inward of it is vendor-agnostic by construction.

The payoff is concrete: an in-memory adapter makes the domain testable with no network, no keys, no flakiness. Because the domain depends only on PaymentPort, any implementation works — including a fake that records calls in a list:

// test/InMemoryPayment.ts — a second adapter, for tests
class InMemoryPayment implements PaymentPort {
  public charged: { amountCents: number; key: string }[] = [];
  constructor(private decline = false) {}
  async charge(amountCents: number, key: string): Promise<ChargeResult> {
    this.charged.push({ amountCents, key });
    return this.decline
      ? { ok: false, reason: "card_declined" }
      : { ok: true, receiptId: "rcpt_test" };
  }
}

test("declined payment yields a declined order", async () => {
  const payments = new InMemoryPayment(true);
  const result = await new PlaceOrder(payments).run(makeOrder({ totalCents: 5000 }));
  expect(result.status).toBe("declined");
  expect(payments.charged).toHaveLength(1); // we asserted the side effect without a network
});

These tests run in milliseconds, deterministically, with no secrets. The same seam that lets you swap Stripe for Adyen in production lets you swap it for a fake in tests — test doubles are just another adapter. This is the everyday dividend of pointing dependencies inward, and it is the most honest evidence that the boundary is real: if the domain were welded to Stripe, this test could not exist.