Facade — System Design

TL;DR

A Facade is a single, simplified interface that hides a tangled subsystem behind it. The client calls `OrderService.placeOrder(...)`; behind that one call the facade orchestrates inventory, payment, fulfillment, notifications, and analytics. The complexity doesn't go away — but the client never has to see it. The whole concept of an API gateway is the Facade pattern at scale.

When to use

Whenever you have a subsystem with many moving parts that callers shouldn't (or can't) understand. Use it to onboard new services, simplify cross-team APIs, or wall off legacy code so the rest of the system doesn't depend on its internals.

Try it

A canonical example

You’re building checkout. The “place order” operation actually involves:

Reserving inventory in the warehouse service.
Authorizing the payment via the payment gateway.
Creating the order record in the database.
Scheduling fulfillment in the logistics service.
Firing the OrderPlaced event for downstream consumers.
Sending a confirmation email/SMS.

You don’t want every caller (mobile app, web app, partner API, CSV import) to coordinate all six. You expose a single facade method:

class OrderFacade {
  async placeOrder(cart: Cart, payment: PaymentMethod, customer: Customer): Promise<OrderId> {
    const reservation = await this.inventory.reserve(cart);
    try {
      const charge = await this.payments.authorize(payment, cart.total);
      const order = await this.orders.create(cart, charge.id, customer);
      await this.logistics.schedule(order);
      await this.eventBus.publish(new OrderPlaced(order));
      await this.notifier.send(customer, `Order ${order.id} confirmed`);
      return order.id;
    } catch (err) {
      await this.inventory.release(reservation);
      throw err;
    }
  }
}

Facade vs Adapter

The API gateway is just a Facade at scale

Trade-offs

Pros: Massive reduction in caller complexity; safe place for cross-cutting concerns (auth, retries, tracing); enables refactoring of internals.

In real systems

API gateways (Kong, Apigee, AWS API Gateway, Azure API Management) — facades for whole microservice fleets.
GraphQL — a facade where the client describes the shape; one query replaces many REST calls.
SDKs — every cloud SDK (AWS.S3, azure-storage-blob) is a facade over the raw HTTP API.
Service meshes — sidecars facade away retries, mTLS, telemetry — the app code stays simple.