Facade

Triggered by

Symptom

Multi-subsystem orchestration scattered across consumers means the agent must reason about subsystem ordering, error handling, and failure recovery at every call site. Verifying 'do all consumers correctly release inventory on payment-fail' requires enumerating every consumer; static analysis cannot prove uniformity.

Goal

One Facade method the agent reads end-to-end to understand the full choreography. Per-consumer reasoning collapses to 'this consumer calls submitOrder(cart, customer)' — the agent does not re-verify orchestration at each consumer site.

Before the pattern

function checkout(cart, customer) {
  if (!inventory.reserve(cart.items)) {
    throw new Error('out of stock');
  }
  const charge = payment.charge(cart.total, customer.cardToken);
  if (!charge.success) {
    inventory.release(cart.items);
    throw new Error('payment failed');
  }
  const shipment = shipping.createShipment(cart.items, customer.address);
  notifications.sendOrderConfirmation(customer.email, shipment.trackingNumber);
  audit.recordPurchase(customer.id, cart.total);
  return { orderId: shipment.trackingNumber, total: cart.total };
}
// Every consumer that calls checkout knows about 5 subsystems
// and the right ordering. Forgetting inventory.release on payment-fail
// silently leaks reserved inventory.

After the pattern

class CheckoutFacade {
  constructor(inventory, payment, shipping, notifications, audit) {
    this.inventory = inventory;
    this.payment = payment;
    this.shipping = shipping;
    this.notifications = notifications;
    this.audit = audit;
  }
  submitOrder(cart, customer) {
    if (!this.inventory.reserve(cart.items)) {
      throw new Error('out of stock');
    }
    const charge = this.payment.charge(cart.total, customer.cardToken);
    if (!charge.success) {
      this.inventory.release(cart.items);
      throw new Error('payment failed');
    }
    const shipment = this.shipping.createShipment(cart.items, customer.address);
    this.notifications.sendOrderConfirmation(customer.email, shipment.trackingNumber);
    this.audit.recordPurchase(customer.id, cart.total);
    return { orderId: shipment.trackingNumber, total: cart.total };
  }
}
// Client: checkout.submitOrder(cart, customer)

Example source: Illustrative example written for this site in the spirit of Design Patterns (Gamma, Helm, Johnson, Vlissides, Addison-Wesley, 1994), chapter 4. The book's running example is a compiler with parser/lexer/codegen subsystems; this JavaScript adaptation uses an e-commerce checkout because the multi-subsystem choreography (inventory + payment + shipping + notifications + audit) makes the encapsulation payoff more visible.

Pressure

Per-consumer orchestration is N consumers × M subsystems × K error-modes = N×M×K cells the agent verifies on every change. Insider Trading is the worst input shape for the agent's verification budget: every consumer must be checked for correctness against every subsystem's contract.

Tradeoff

Facade opacity means runtime errors inside the facade reach the consumer as 'submitOrder failed' with no structural breadcrumb. The agent investigating a regression traces into the facade; stack traces span the facade + subsystem boundary, and the consumer's mental model sits one level removed from the failure.

Relief

Edits scoped to the Facade; consumer code unchanged when subsystems are added or refactored; one set of tests covers orchestration and error recovery exhaustively. The agent's cross-consumer verification budget drops to zero on subsystem changes.

Trap

When the Facade grows to N user tasks (submitOrder + refund + modify + audit + ...), it becomes a god object the agent must read fully before any edit. The pattern's clarity wins were proportional to focused scope; god-facade scope reintroduces the verification problem at a higher level.