Facade Design Pattern

public final class OrderFacade {

    private final InventoryService inventory;
    private final PricingEngine pricing;
    private final PaymentGateway payments;
    private final WarehouseClient warehouse;
    private final Notifier notifier;

    // Constructor omitted — five fields, injected.

    /** The whole point: one method shaped like the thing the caller wanted. */
    public Order placeOrder(Cart cart, Card card) {
        Reservation reservation = inventory.reserve(cart.lines());
        try {
            Quote quote = pricing.quote(cart, cart.customer());
            Receipt receipt = payments.charge(quote.total(), card);

            Order order = Order.of(cart, quote, receipt);
            warehouse.dispatch(order);
            notifier.orderPlaced(order);
            return order;

        } catch (PaymentDeclined | WarehouseUnavailable e) {
            // The compensating action belongs here too. This is exactly the line
            // every hand-rolled copy of the sequence forgets.
            inventory.release(reservation);
            throw e;
        }
    }
}

// The controller shrinks to one line and one import:
//
//     @PostMapping("/orders")
//     Order create(@RequestBody Cart cart, Card card) {
//         return orders.placeOrder(cart, card);
//     }
//
// Note what the facade does NOT do: no pricing rules, no retry policy, no tax
// logic. It sequences, it compensates, it stops. The moment business rules move
// in, you have a god object wearing a pattern's name.

"""orders/__init__.py — in Python the facade is usually the MODULE, not a class.

Callers write `from shop import orders; orders.place_order(cart, card)`. The five
subsystem modules are imported here and nowhere else, which is the same
dependency win a facade class buys you in Java, with no class to instantiate.
"""

from shop import inventory, notifier, payments, pricing, warehouse

__all__ = ["place_order", "cancel_order", "track_order"]


def place_order(cart: Cart, card: Card) -> Order:
    reservation = inventory.reserve(cart.lines)
    try:
        quote = pricing.quote(cart, cart.customer)
        receipt = payments.charge(quote.total, card)

        order = Order.of(cart, quote, receipt)
        warehouse.dispatch(order)
        notifier.order_placed(order)
        return order

    except (PaymentDeclined, WarehouseUnavailable):
        inventory.release(reservation)
        raise


# `__all__` is doing real facade work here: it declares the small public surface
# and keeps the five subsystem names out of `from orders import *`. If you need
# dependency injection for tests, take a class instead — but for most Python
# codebases the module IS the pattern, already built into the language.

// order_facade.h — note how few headers this exposes. In C++ a facade buys you
// something the other languages don't care about: COMPILE TIME. Callers include
// one small header instead of five heavy subsystem ones.

#include <memory>

class Cart;
class Card;
class Order;

class OrderFacade {
public:
    OrderFacade();
    ~OrderFacade();                       // out-of-line: Impl is incomplete here

    Order placeOrder(const Cart& cart, const Card& card);
    void  cancelOrder(OrderId id);

private:
    struct Impl;                          // pimpl — the subsystem types live in the .cpp
    std::unique_ptr<Impl> impl_;
};

// ── order_facade.cpp ────────────────────────────────────────────────────────
#include "order_facade.h"
#include "inventory_service.h"
#include "pricing_engine.h"
#include "payment_gateway.h"
#include "warehouse_client.h"
#include "notifier.h"

struct OrderFacade::Impl {
    InventoryService inventory;
    PricingEngine    pricing;
    PaymentGateway   payments;
    WarehouseClient  warehouse;
    Notifier         notifier;
};

Order OrderFacade::placeOrder(const Cart& cart, const Card& card) {
    auto reservation = impl_->inventory.reserve(cart.lines());
    try {
        auto quote   = impl_->pricing.quote(cart, cart.customer());
        auto receipt = impl_->payments.charge(quote.total(), card);

        Order order{cart, quote, receipt};
        impl_->warehouse.dispatch(order);
        impl_->notifier.orderPlaced(order);
        return order;
    } catch (...) {
        impl_->inventory.release(reservation);   // compensate, then rethrow
        throw;
    }
}

public interface IOrderService
{
    Task<Order> PlaceOrderAsync(Cart cart, Card card, CancellationToken ct = default);
}

// The facade takes an interface of its own, purely so controllers can be tested
// against a fake. The pattern doesn't require it; testability does.
public sealed class OrderFacade(
    IInventoryService inventory,
    IPricingEngine pricing,
    IPaymentGateway payments,
    IWarehouseClient warehouse,
    INotifier notifier) : IOrderService
{
    public async Task<Order> PlaceOrderAsync(Cart cart, Card card, CancellationToken ct = default)
    {
        var reservation = await inventory.ReserveAsync(cart.Lines, ct);
        try
        {
            var quote   = await pricing.QuoteAsync(cart, cart.Customer, ct);
            var receipt = await payments.ChargeAsync(quote.Total, card, ct);

            var order = Order.Of(cart, quote, receipt);
            await warehouse.DispatchAsync(order, ct);
            await notifier.OrderPlacedAsync(order, ct);
            return order;
        }
        catch (Exception) when (await Compensate(reservation, ct))
        {
            throw;   // filter returns false; it ran the roll-back on the way past
        }
    }
}

// A facade is a natural fit for one DI registration that hides five:
//     services.AddScoped<IOrderService, OrderFacade>();
//
// Worth naming the boundary: MediatR handlers are often described as facades.
// They aren't — a Mediator's participants talk THROUGH it to each other, while a
// facade's subsystem doesn't know it exists.

// orders.js — the module's exports are the facade. The five subsystem modules
// are imported here and, ideally, nowhere else in the app.

import * as inventory from './inventory.js'
import * as pricing from './pricing.js'
import * as payments from './payments.js'
import * as warehouse from './warehouse.js'
import * as notifier from './notifier.js'

export async function placeOrder(cart, card) {
  const reservation = await inventory.reserve(cart.lines)
  try {
    const quote = await pricing.quote(cart, cart.customer)
    const receipt = await payments.charge(quote.total, card)

    const order = { ...cart, quote, receipt, id: receipt.reference }
    await warehouse.dispatch(order)
    await notifier.orderPlaced(order)
    return order
  } catch (err) {
    await inventory.release(reservation)
    throw err
  }
}

export async function cancelOrder(orderId) { /* refund, then release */ }

// The `index.js` barrel file every JavaScript project grows is this pattern,
// usually by accident: one import path, a curated surface, the internals free to
// move. It stops being a facade and becomes dead weight when it re-exports
// everything — a facade is defined by what it leaves out.

// Package orders is the facade. In Go the unit of encapsulation is the package,
// so the exported functions ARE the simplified interface and the subsystem
// clients stay unexported.
package orders

type Service struct {
	inventory *inventory.Client
	pricing   *pricing.Engine
	payments  payments.Gateway
	warehouse *warehouse.Client
	notifier  notifier.Sink
}

func (s *Service) Place(ctx context.Context, cart Cart, card Card) (Order, error) {
	res, err := s.inventory.Reserve(ctx, cart.Lines)
	if err != nil {
		return Order{}, fmt.Errorf("reserve: %w", err)
	}

	// No exceptions, so the compensating action is a defer with a named return —
	// the Go idiom for "undo this unless everything worked".
	var order Order
	defer func() {
		if err != nil {
			s.inventory.Release(ctx, res)
		}
	}()

	quote, err := s.pricing.Quote(ctx, cart)
	if err != nil {
		return Order{}, fmt.Errorf("quote: %w", err)
	}
	receipt, err := s.payments.Charge(ctx, quote.Total, card)
	if err != nil {
		return Order{}, fmt.Errorf("charge: %w", err)
	}

	order = New(cart, quote, receipt)
	if err = s.warehouse.Dispatch(ctx, order); err != nil {
		return Order{}, fmt.Errorf("dispatch: %w", err)
	}
	s.notifier.OrderPlaced(ctx, order)
	return order, nil
}

// The interface is the facade's contract, and keeping it small is the design work.
interface OrderService {
  placeOrder(cart: Cart, card: Card): Promise<Order>
  cancelOrder(orderId: OrderId): Promise<void>
  trackOrder(orderId: OrderId): Promise<Tracking>
}

export class OrderFacade implements OrderService {
  constructor(
    private readonly inventory: InventoryService,
    private readonly pricing: PricingEngine,
    private readonly payments: PaymentGateway,
    private readonly warehouse: WarehouseClient,
    private readonly notifier: Notifier,
  ) {}

  async placeOrder(cart: Cart, card: Card): Promise<Order> {
    const reservation = await this.inventory.reserve(cart.lines)
    try {
      const quote = await this.pricing.quote(cart, cart.customer)
      const receipt = await this.payments.charge(quote.total, card)

      const order = Order.of(cart, quote, receipt)
      await this.warehouse.dispatch(order)
      await this.notifier.orderPlaced(order)
      return order
    } catch (err) {
      await this.inventory.release(reservation)
      throw err
    }
  }
}

// A typed facade gives you a cheap architectural test: the day someone adds a
// sixth subsystem call to a controller, it won't type-check against
// OrderService, and the review catches it instead of production.