microservices-design

Microservices Design

Service Boundaries

Define services around business capabilities, not technical layers. Each service owns its data store and exposes a clear API contract.

order-service/       -> owns orders table, publishes OrderCreated events
inventory-service/   -> owns inventory table, subscribes to OrderCreated
payment-service/     -> owns payments table, handles payment processing
notification-service -> stateless, subscribes to events, sends emails/SMS

Event-Driven Communication

interface DomainEvent {
  eventId: string;
  eventType: string;
  aggregateId: string;
  timestamp: string;
  version: number;
  payload: Record<string, unknown>;
}

const orderCreatedEvent: DomainEvent = {
  eventId: crypto.randomUUID(),
  eventType: "order.created",
  aggregateId: orderId,
  timestamp: new Date().toISOString(),
  version: 1,
  payload: { customerId, items, totalAmount },
};

await broker.publish("orders", orderCreatedEvent);

async function handleOrderCreated(event: DomainEvent) {
  const { items } = event.payload as OrderPayload;

  for (const item of items) {
    await db.inventory.update({
      where: { productId: item.productId },
      data: { quantity: { decrement: item.quantity } },
    });
  }

  await markEventProcessed(event.eventId);
}

Use idempotency keys (eventId) to handle duplicate deliveries safely.

Saga Pattern (Orchestration)

class OrderSaga {
  private steps: SagaStep[] = [
    {
      name: "reserveInventory",
      execute: (ctx) => inventoryService.reserve(ctx.items),
      compensate: (ctx) => inventoryService.release(ctx.items),
    },
    {
      name: "processPayment",
      execute: (ctx) => paymentService.charge(ctx.customerId, ctx.amount),
      compensate: (ctx) => paymentService.refund(ctx.paymentId),
    },
    {
      name: "confirmOrder",
      execute: (ctx) => orderService.confirm(ctx.orderId),
      compensate: (ctx) => orderService.cancel(ctx.orderId),
    },
  ];

  async run(context: SagaContext): Promise<void> {
    const completed: SagaStep[] = [];

    for (const step of this.steps) {
      try {
        const result = await step.execute(context);
        Object.assign(context, result);
        completed.push(step);
      } catch (error) {
        for (const s of completed.reverse()) {
          await s.compensate(context);
        }
        throw new SagaFailedError(step.name, error);
      }
    }
  }
}