Facade Pattern

The Problem

Placing an order in an e-commerce platform involves multiple subsystems: checking inventory, processing payment, creating a shipment, and sending a confirmation notification. If the client had to orchestrate calls to each service directly, it would need to understand the correct sequence, handle errors, and coordinate data. This makes the controller bloated and the workflow fragile.

The Solution

The Facade pattern introduces a single OrderFacadeService that encapsulates the entire order placement workflow. The client makes one call to placeOrder(), and the facade coordinates all four subsystems internally in the correct order with proper error handling.

Structure

Subsystem Classes (InventoryService, PaymentService, ShippingService, NotificationService) — Individual services that handle specific concerns.
Facade (OrderFacadeService) — Orchestrates the subsystem classes in the correct sequence, exposing a single placeOrder() method.
Client (FacadeController) — Interacts only with the facade.

Implementation

The facade coordinates a four-step workflow:

Inventory Check — Verifies all items are in stock.
Payment Processing — Charges the customer.
Shipment Creation — Creates a shipping record with carrier and estimated delivery.
Confirmation — Sends an order confirmation email.

import { Injectable } from '@nestjs/common';

export interface StockCheckResult {
  available: boolean;
  unavailableItems: string[];
}

@Injectable()
export class InventoryService {
  checkStock(items: { name: string; quantity: number }[]): StockCheckResult {
    const unavailableItems: string[] = [];

    for (const item of items) {
      // Simulate stock check: items with quantity > 100 are unavailable
      if (item.quantity > 100) {
        unavailableItems.push(item.name);
      }
    }

    return {
      available: unavailableItems.length === 0,
      unavailableItems,
    };
  }
}

import { Injectable } from '@nestjs/common';

export interface PaymentResult {
  success: boolean;
  transactionId: string;
}

@Injectable()
export class PaymentService {
  processPayment(amount: number, method: string): PaymentResult {
    return {
      success: true,
      transactionId: `TXN-${method.toUpperCase()}-${Date.now()}`,
    };
  }
}

import { Injectable } from '@nestjs/common';

export interface ShipmentResult {
  shipmentId: string;
  estimatedDelivery: string;
  carrier: string;
}

@Injectable()
export class ShippingService {
  createShipment(
    items: { name: string; quantity: number }[],
    address: string,
  ): ShipmentResult {
    const deliveryDate = new Date();
    deliveryDate.setDate(deliveryDate.getDate() + 5);

    return {
      shipmentId: `SHIP-${Date.now()}`,
      estimatedDelivery: deliveryDate.toISOString().split('T')[0]!,
      carrier: 'FedEx',
    };
  }
}

import { Injectable } from '@nestjs/common';

export interface NotificationResult {
  sent: boolean;
  messageId: string;
}

@Injectable()
export class NotificationService {
  sendConfirmation(
    email: string,
    orderDetails: { orderId: string; total: number },
  ): NotificationResult {
    return {
      sent: true,
      messageId: `MSG-${Date.now()}`,
    };
  }
}

import { Injectable, BadRequestException } from '@nestjs/common';
import { InventoryService } from './inventory.service';
import { PaymentService } from './payment.service';
import { ShippingService } from './shipping.service';
import { NotificationService } from './notification.service';

export interface PlaceOrderData {
  items: { name: string; quantity: number; price: number }[];
  shippingAddress: string;
  paymentMethod: string;
  customerEmail: string;
}

@Injectable()
export class OrderFacadeService {
  constructor(
    private readonly inventoryService: InventoryService,
    private readonly paymentService: PaymentService,
    private readonly shippingService: ShippingService,
    private readonly notificationService: NotificationService,
  ) {}

  placeOrder(orderData: PlaceOrderData) {
    // Step 1: Check inventory
    const stockResult = this.inventoryService.checkStock(orderData.items);
    if (!stockResult.available) {
      throw new BadRequestException(
        `Items out of stock: ${stockResult.unavailableItems.join(', ')}`,
      );
    }

    // Step 2: Process payment
    const totalAmount = orderData.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0,
    );
    const paymentResult = this.paymentService.processPayment(
      totalAmount,
      orderData.paymentMethod,
    );
    if (!paymentResult.success) {
      throw new BadRequestException('Payment processing failed');
    }

    // Step 3: Create shipment
    const shipmentResult = this.shippingService.createShipment(
      orderData.items,
      orderData.shippingAddress,
    );

    // Step 4: Send confirmation
    const orderId = `ORD-${Date.now()}`;
    const notificationResult = this.notificationService.sendConfirmation(
      orderData.customerEmail,
      { orderId, total: totalAmount },
    );

    return {
      orderId,
      status: 'confirmed',
      inventory: stockResult,
      payment: paymentResult,
      shipping: shipmentResult,
      notification: notificationResult,
      total: parseFloat(totalAmount.toFixed(2)),
    };
  }
}

NestJS Integration

All subsystem services and the facade are registered as @Injectable() providers. The OrderFacadeService receives all four services through constructor injection. The module exports OrderFacadeService so other modules can use the simplified interface without importing individual subsystem services. This aligns naturally with NestJS’s modular architecture, where the facade acts as the module’s public API.

When to Use

You want to provide a simple interface to a complex subsystem.
You want to decouple client code from subsystem internals.
You are orchestrating a multi-step workflow where sequence and error handling should be centralized.
You want to reduce the number of dependencies client code must manage.

When NOT to Use

The subsystem is already simple enough that a facade would be a pass-through.
Clients need fine-grained control over individual subsystem operations.
The facade risks becoming a “God object” — consider splitting into multiple facades.

Adapter

Convert the interface of a class into another interface clients expect.

Mediator

Define an object that encapsulates how a set of objects interact.

Abstract Factory

Provide an interface for creating families of related or dependent objects without specifying their concrete classes.