Driving and driven sides

The two sides of the hexagon

Cockburn’s original description placed adapters on two distinct sides, and the asymmetry matters:

The driving side (left / primary) — actors that initiate interaction with the application. A driving adapter calls a primary port to make the application do something. The HTTP controller sends a POST and calls confirmOrder. The CLI sends a command and calls confirmOrder. An automated test calls confirmOrder. Each driving adapter translates its own input format into a port method call.

The driven side (right / secondary) — infrastructure that the application activates to do its work. A driven adapter implements a secondary port. The application calls IOrderRepository.save(order) — the Postgres adapter responds. The application calls IPaymentGateway.charge(amount) — the Stripe adapter responds. The application calls IEmailNotifier.send(message) — the SendGrid adapter responds.

The critical asymmetry: the driving side calls the application; the driven side is called by the application. Both sides are mediated by ports. But the direction of initiation is opposite.

The domain at the center

The domain sits at the center of the hexagon, surrounded on both sides by ports it owns. This is the structural consequence of applying the Dependency Inversion Principle (unit 02) at the architectural level: the high-level policy (domain) owns the abstractions; the low-level mechanisms (adapters) depend on those abstractions to plug in.

In the B2B platform, the domain defines:

// Primary ports (what the domain offers)
interface OrderConfirmationPort {
  confirmOrder(orderId: string, approverId: string): Promise<ConfirmationResult>;
}
interface InvoiceGenerationPort {
  generateInvoice(orderId: string): Promise<InvoiceId>;
}

// Secondary ports (what the domain requires)
interface IOrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}
interface IPaymentGateway {
  charge(customerId: string, amount: Money): Promise<ChargeResult>;
}
interface IEmailNotifier {
  send(recipient: Email, subject: string, body: string): Promise<void>;
}

All of these interfaces live in the domain package. None of them import HTTP, Stripe, Postgres, or SendGrid. The domain has zero knowledge of the outside world’s technology choices. It only knows what it needs (secondary ports) and what it provides (primary ports).

Mapping HTTP, CLI, and test-harness to the same primary port

One of the most valuable properties of the driving side is that it normalizes all entry points to the same port interface. The confirmation use case is defined once on the primary port. Any technology that can construct the required domain parameters can call it.

// HTTP driving adapter
class HttpOrderController {
  constructor(private port: OrderConfirmationPort) {}

  async post(req: Request): Promise<Response> {
    const result = await this.port.confirmOrder(
      req.params.orderId,
      req.body.approverId
    );
    return result.success
      ? Response.json({ status: 'confirmed' }, { status: 200 })
      : Response.json({ error: result.reason }, { status: 422 });
  }
}

// CLI driving adapter
class CliOrderConfirmCommand {
  constructor(private port: OrderConfirmationPort) {}

  async run(args: string[]): Promise<void> {
    const [orderId, approverId] = args;
    const result = await this.port.confirmOrder(orderId, approverId);
    console.log(result.success ? 'Confirmed' : `Failed: ${result.reason}`);
  }
}

// Test driving adapter — no framework needed, just the port
async function confirmOrderViaPort(
  port: OrderConfirmationPort,
  orderId: string,
  approverId: string
): Promise<ConfirmationResult> {
  return port.confirmOrder(orderId, approverId);
}

The confirmation logic executes identically regardless of whether the caller is an HTTP request, a CLI command, or a test. The test driving adapter is the simplest possible: just a direct call. No HTTP client, no port number, no server startup. This is available specifically because the primary port is owned by the domain and speaks domain language.

The driven side: secondary ports invert the infrastructure dependency

The driven side is where DIP from unit 02 becomes concrete. The domain defines what it needs — IPaymentGateway, IOrderRepository — in its own package, in domain language. The Stripe adapter implements IPaymentGateway; it depends on the domain’s interface definition. The Postgres adapter implements IOrderRepository; it depends on the domain’s interface definition.

The direction of source-code dependency on the driven side is the same as on the driving side: always inward, toward the domain.

// Secondary port — defined in domain package
// domain/ports/IPaymentGateway.ts
interface IPaymentGateway {
  charge(customerId: CustomerId, amount: Money): Promise<ChargeResult>;
  refund(chargeId: ChargeId, amount: Money): Promise<RefundResult>;
}

// Driven adapter — defined in infrastructure package
// infra/payment/StripePaymentAdapter.ts
import { IPaymentGateway, ChargeResult, RefundResult } from '../../domain/ports/IPaymentGateway';
import Stripe from 'stripe';

class StripePaymentAdapter implements IPaymentGateway {
  private client = new Stripe(process.env.STRIPE_KEY!);

  async charge(customerId: CustomerId, amount: Money): Promise<ChargeResult> {
    const intent = await this.client.paymentIntents.create({
      amount: amount.inCents(),
      currency: amount.currency,
      customer: customerId.value,
    });
    return ChargeResult.fromStripeIntent(intent);
  }

  async refund(chargeId: ChargeId, amount: Money): Promise<RefundResult> {
    const refund = await this.client.refunds.create({
      payment_intent: chargeId.value,
      amount: amount.inCents(),
    });
    return RefundResult.fromStripeRefund(refund);
  }
}

The StripePaymentAdapter imports from the domain (IPaymentGateway). The domain does not import from StripePaymentAdapter. The stripe npm package is a detail of the adapter — the domain has no transitive dependency on it. This is the fix for the opening story: moving the Stripe call behind a secondary port means the domain can be tested without Stripe, and switching payment processors means writing a new adapter without touching the domain.