diegosouzapw Enterprise Architecture Patterns
A comprehensive skill for mastering enterprise architecture patterns, distributed systems design, and scalable application development. This skill covers strategic and tactical patterns for building robust, maintainable, and scalable enterprise systems.
When to Use This Skill
Use this skill when:
- Designing microservices architectures for distributed systems
- Implementing domain-driven design (DDD) in complex business domains
- Building event-driven architectures with event sourcing and CQRS
- Designing saga patterns for distributed transactions
- Implementing API gateways and service mesh architectures
- Scaling applications horizontally and vertically
- Building resilient systems with fault tolerance
- Migrating monoliths to microservices
- Designing multi-tenant SaaS architectures
- Implementing backend-for-frontend (BFF) patterns
- Building real-time systems with event streaming
- Architecting cloud-native applications
Core Architectural Concepts
System Design Fundamentals
Separation of Concerns Divide systems into distinct sections where each section addresses a separate concern, reducing coupling and increasing cohesion.
Modularity Design systems as collections of independent modules that can be developed, tested, and deployed separately.
Abstraction Hide complex implementation details behind simple interfaces, making systems easier to understand and modify.
Scalability Dimensions
- Horizontal scaling: Add more machines/instances
- Vertical scaling: Add more resources to existing machines
- Data scaling: Partition data across multiple stores
- Functional scaling: Decompose by business capability
Consistency Models
- Strong consistency: All nodes see the same data at the same time
- Eventual consistency: All nodes will eventually see the same data
- Causal consistency: Related operations see consistent state
- Read-your-writes consistency: Users see their own updates immediately
CAP Theorem In distributed systems, you can only guarantee two of three properties:
- Consistency: All nodes see the same data
- Availability: Every request receives a response
- Partition tolerance: System continues despite network failures
Distributed Computing Fallacies
- The network is reliable
- Latency is zero
- Bandwidth is infinite
- The network is secure
- Topology doesn't change
- There is one administrator
- Transport cost is zero
- The network is homogeneous
Domain-Driven Design (DDD)
Strategic Design Patterns
Bounded Context
A bounded context is an explicit boundary within which a domain model is consistent and valid. It defines the scope where particular terms, definitions, and rules apply.
Key Principles:
- Each bounded context has its own ubiquitous language
- Models within a context are consistent
- Cross-context integration requires translation
- Contexts align with business capabilities
Implementation:
// Example: E-commerce system with multiple bounded contexts
// Sales Context
namespace Sales {
class Customer {
customerId: string;
email: string;
orderHistory: Order[];
placeOrder(order: Order): void {
// Sales-specific logic
}
}
}
// Billing Context
namespace Billing {
class Customer {
customerId: string;
paymentMethods: PaymentMethod[];
invoices: Invoice[];
processPayment(invoice: Invoice): void {
// Billing-specific logic
}
}
}
// Different models for Customer in different contexts
Context Mapping Patterns:
Shared Kernel: Two contexts share a subset of the domain model
- Use when: Teams are closely coordinated
- Risk: Changes affect multiple contexts
Customer-Supplier: Downstream context depends on upstream
- Use when: Clear dependency direction exists
- Pattern: Upstream provides defined API
Conformist: Downstream conforms to upstream model
- Use when: Upstream is external/unchangeable
- Pattern: Adapt to external API
Anti-Corruption Layer: Translate between contexts
- Use when: Protecting from legacy or external systems
- Pattern: Adapter/facade to translate models
Separate Ways: Contexts are completely independent
- Use when: No integration needed
- Pattern: Duplicate functionality if necessary
Open Host Service: Well-defined protocol for integration
- Use when: Multiple consumers need access
- Pattern: REST API, GraphQL, gRPC
Published Language: Shared, well-documented language
- Use when: Industry standards exist
- Pattern: XML schemas, JSON schemas, OpenAPI
Ubiquitous Language
A shared vocabulary between developers and domain experts used consistently in code, documentation, and conversations.
Building Ubiquitous Language:
// Bad: Generic technical terms
class DataProcessor {
processData(data: any): void {
// Unclear what this does in business terms
}
}
// Good: Business domain terms
class OrderFulfillment {
fulfillOrder(order: Order): void {
this.pickItems(order.items);
this.packForShipment(order);
this.scheduleDelivery(order);
}
private pickItems(items: OrderItem[]): void {
// Business logic using domain language
}
}
Tactical Design Patterns
Entities
Objects with unique identity that persist over time, tracking continuity and lifecycle.
Characteristics:
- Unique identifier (ID)
- Mutable state
- Lifecycle (created, modified, deleted)
- Equality based on identity, not attributes
Implementation:
class Order {
private readonly orderId: string;
private orderItems: OrderItem[];
private status: OrderStatus;
private orderDate: Date;
private customerId: string;
constructor(orderId: string, customerId: string) {
this.orderId = orderId;
this.customerId = customerId;
this.orderItems = [];
this.status = OrderStatus.Draft;
this.orderDate = new Date();
}
// Business behavior
addItem(product: Product, quantity: number): void {
if (this.status !== OrderStatus.Draft) {
throw new Error("Cannot modify confirmed order");
}
this.orderItems.push(new OrderItem(product, quantity));
}
confirm(): void {
if (this.orderItems.length === 0) {
throw new Error("Cannot confirm empty order");
}
this.status = OrderStatus.Confirmed;
}
// Identity-based equality
equals(other: Order): boolean {
return this.orderId === other.orderId;
}
}
Value Objects
Immutable objects defined by their attributes rather than identity, representing descriptive aspects of the domain.
Characteristics:
- No unique identifier
- Immutable (cannot change state)
- Equality based on all attributes
- Often passed by value
- Can be shared safely
Implementation:
class Money {
readonly amount: number;
readonly currency: string;
constructor(amount: number, currency: string) {
if (amount < 0) {
throw new Error("Amount cannot be negative");
}
this.amount = amount;
this.currency = currency;
}
// Operations return new instances
add(other: Money): Money {
if (this.currency !== other.currency) {
throw new Error("Cannot add different currencies");
}
return new Money(this.amount + other.amount, this.currency);
}
multiply(factor: number): Money {
return new Money(this.amount * factor, this.currency);
}
// Value-based equality
equals(other: Money): boolean {
return this.amount === other.amount &&
this.currency === other.currency;
}
}
class Address {
readonly street: string;
readonly city: string;
readonly state: string;
readonly zipCode: string;
readonly country: string;
constructor(
street: string,
city: string,
state: string,
zipCode: string,
country: string
) {
this.street = street;
this.city = city;
this.state = state;
this.zipCode = zipCode;
this.country = country;
}
equals(other: Address): boolean {
return this.street === other.street &&
this.city === other.city &&
this.state === other.state &&
this.zipCode === other.zipCode &&
this.country === other.country;
}
}
Aggregates
Clusters of entities and value objects with clear consistency boundaries, accessed through a single root entity.
Key Principles:
- One aggregate = one transaction boundary
- External references only to aggregate root
- Root enforces all invariants
- Small aggregates perform better
- Eventual consistency between aggregates
Design Rules:
- Model true invariants in consistency boundaries
- Design small aggregates
- Reference other aggregates by identity only
- Update other aggregates using eventual consistency
- Use repositories to retrieve aggregates
Implementation:
// Aggregate Root
class Order {
private readonly orderId: string;
private readonly customerId: string; // Reference by ID only
private orderItems: OrderItem[] = [];
private shippingAddress: Address;
private status: OrderStatus;
private totalAmount: Money;
constructor(orderId: string, customerId: string, shippingAddress: Address) {
this.orderId = orderId;
this.customerId = customerId;
this.shippingAddress = shippingAddress;
this.status = OrderStatus.Draft;
this.totalAmount = new Money(0, "USD");
}
// Public methods enforce invariants
addItem(product: Product, quantity: number): void {
if (this.status !== OrderStatus.Draft) {
throw new Error("Cannot modify confirmed order");
}
if (quantity <= 0) {
throw new Error("Quantity must be positive");
}
const existingItem = this.findItem(product.id);
if (existingItem) {
existingItem.increaseQuantity(quantity);
} else {
this.orderItems.push(new OrderItem(product, quantity));
}
this.recalculateTotal();
}
removeItem(productId: string): void {
if (this.status !== OrderStatus.Draft) {
throw new Error("Cannot modify confirmed order");
}
this.orderItems = this.orderItems.filter(
item => item.productId !== productId
);
this.recalculateTotal();
}
confirm(): void {
if (this.orderItems.length === 0) {
throw new Error("Cannot confirm empty order");
}
if (!this.shippingAddress) {
throw new Error("Shipping address required");
}
this.status = OrderStatus.Confirmed;
}
private recalculateTotal(): void {
this.totalAmount = this.orderItems.reduce(
(total, item) => total.add(item.subtotal),
new Money(0, "USD")
);
}
private findItem(productId: string): OrderItem | undefined {
return this.orderItems.find(item => item.productId === productId);
}
// Getters for read-only access
get id(): string { return this.orderId; }
get total(): Money { return this.totalAmount; }
get items(): readonly OrderItem[] { return this.orderItems; }
}
// Entity within aggregate
class OrderItem {
readonly productId: string;
readonly productName: string;
readonly unitPrice: Money;
private quantity: number;
constructor(product: Product, quantity: number) {
this.productId = product.id;
this.productName = product.name;
this.unitPrice = product.price;
this.quantity = quantity;
}
increaseQuantity(amount: number): void {
this.quantity += amount;
}
get subtotal(): Money {
return this.unitPrice.multiply(this.quantity);
}
}
Domain Events
Events that represent something significant that happened in the domain, enabling loose coupling and eventual consistency.
Characteristics:
- Past tense naming (OrderPlaced, PaymentProcessed)
- Immutable
- Include all necessary information
- Timestamped
- Often include aggregate ID
Implementation:
interface DomainEvent {
eventId: string;
occurredAt: Date;
aggregateId: string;
eventType: string;
}
class OrderPlacedEvent implements DomainEvent {
readonly eventId: string;
readonly occurredAt: Date;
readonly aggregateId: string;
readonly eventType = "OrderPlaced";
readonly orderId: string;
readonly customerId: string;
readonly totalAmount: Money;
readonly items: OrderItemDto[];
constructor(order: Order) {
this.eventId = generateId();
this.occurredAt = new Date();
this.aggregateId = order.id;
this.orderId = order.id;
this.customerId = order.customerId;
this.totalAmount = order.total;
this.items = order.items.map(item => ({
productId: item.productId,
quantity: item.quantity,
price: item.unitPrice
}));
}
}
// Domain event publisher
class DomainEventPublisher {
private handlers: Map<string, Function[]> = new Map();
subscribe(eventType: string, handler: Function): void {
if (!this.handlers.has(eventType)) {
this.handlers.set(eventType, []);
}
this.handlers.get(eventType)!.push(handler);
}
async publish(event: DomainEvent): Promise<void> {
const handlers = this.handlers.get(event.eventType) || [];
await Promise.all(handlers.map(handler => handler(event)));
}
}
// Usage
class OrderService {
constructor(
private orderRepository: OrderRepository,
private eventPublisher: DomainEventPublisher
) {}
async placeOrder(order: Order): Promise<void> {
order.confirm();
await this.orderRepository.save(order);
const event = new OrderPlacedEvent(order);
await this.eventPublisher.publish(event);
}
}
Repositories
Abstraction for accessing aggregates, providing collection-like interface while hiding persistence details.
Principles:
- One repository per aggregate root
- Collection-oriented interface
- Hide database implementation
- Return fully-formed aggregates
- Support querying by ID and business criteria
Implementation:
interface OrderRepository {
save(order: Order): Promise<void>;
findById(orderId: string): Promise<Order | null>;
findByCustomer(customerId: string): Promise<Order[]>;
findByStatus(status: OrderStatus): Promise<Order[]>;
delete(orderId: string): Promise<void>;
}
class OrderRepositoryImpl implements OrderRepository {
constructor(private db: Database) {}
async save(order: Order): Promise<void> {
const data = this.toDataModel(order);
await this.db.orders.upsert(data);
}
async findById(orderId: string): Promise<Order | null> {
const data = await this.db.orders.findOne({ id: orderId });
if (!data) return null;
return this.toDomainModel(data);
}
async findByCustomer(customerId: string): Promise<Order[]> {
const results = await this.db.orders.find({ customerId });
return results.map(data => this.toDomainModel(data));
}
async findByStatus(status: OrderStatus): Promise<Order[]> {
const results = await this.db.orders.find({ status });
return results.map(data => this.toDomainModel(data));
}
async delete(orderId: string): Promise<void> {
await this.db.orders.delete({ id: orderId });
}
private toDataModel(order: Order): any {
// Convert domain model to database model
return {
id: order.id,
customerId: order.customerId,
items: order.items.map(item => ({
productId: item.productId,
quantity: item.quantity,
price: item.unitPrice.amount
})),
total: order.total.amount,
status: order.status
};
}
private toDomainModel(data: any): Order {
// Reconstruct domain model from database data
const order = new Order(data.id, data.customerId, data.shippingAddress);
// Restore items and state
return order;
}
}
Domain Services
Operations that don't naturally belong to any entity or value object, encapsulating domain logic that involves multiple aggregates.
When to Use:
- Logic spans multiple aggregates
- Operation is a significant domain concept
- Behavior doesn't fit naturally in entity or value object
Implementation:
class PricingService {
calculateOrderTotal(
items: OrderItem[],
customer: Customer,
promotions: Promotion[]
): Money {
let total = items.reduce(
(sum, item) => sum.add(item.subtotal),
new Money(0, "USD")
);
// Apply customer discount
if (customer.isPremium) {
total = total.multiply(0.9); // 10% discount
}
// Apply promotions
for (const promo of promotions) {
total = promo.apply(total);
}
return total;
}
}
class TransferService {
transfer(
fromAccount: Account,
toAccount: Account,
amount: Money
): void {
if (!fromAccount.canWithdraw(amount)) {
throw new Error("Insufficient funds");
}
fromAccount.withdraw(amount);
toAccount.deposit(amount);
}
}
Event Sourcing
Event sourcing persists the state of a system as a sequence of events rather than storing current state. The current state is derived by replaying events.
Core Concepts
Event Store Append-only log of all events that have occurred in the system.
Event Stream Sequence of events for a specific aggregate, ordered by time.
Projection Read model built by processing events, optimized for queries.
Snapshot Cached state at a point in time to avoid replaying all events.
Implementation
// Event interface
interface Event {
eventId: string;
eventType: string;
aggregateId: string;
aggregateType: string;
version: number;
timestamp: Date;
data: any;
metadata?: any;
}
// Account aggregate with event sourcing
class Account {
private accountId: string;
private balance: number = 0;
private isActive: boolean = true;
private version: number = 0;
private uncommittedEvents: Event[] = [];
constructor(accountId: string) {
this.accountId = accountId;
}
// Command handlers
open(initialBalance: number): void {
if (this.version > 0) {
throw new Error("Account already opened");
}
this.applyEvent({
eventType: "AccountOpened",
data: { accountId: this.accountId, initialBalance }
});
}
deposit(amount: number): void {
if (!this.isActive) {
throw new Error("Account is closed");
}
if (amount <= 0) {
throw new Error("Amount must be positive");
}
this.applyEvent({
eventType: "MoneyDeposited",
data: { amount }
});
}
withdraw(amount: number): void {
if (!this.isActive) {
throw new Error("Account is closed");
}
if (amount <= 0) {
throw new Error("Amount must be positive");
}
if (this.balance < amount) {
throw new Error("Insufficient funds");
}
this.applyEvent({
eventType: "MoneyWithdrawn",
data: { amount }
});
}
close(): void {
if (!this.isActive) {
throw new Error("Account already closed");
}
if (this.balance > 0) {
throw new Error("Cannot close account with positive balance");
}
this.applyEvent({
eventType: "AccountClosed",
data: {}
});
}
// Event application
private applyEvent(eventData: Partial<Event>): void {
const event: Event = {
eventId: generateId(),
eventType: eventData.eventType!,
aggregateId: this.accountId,
aggregateType: "Account",
version: this.version + 1,
timestamp: new Date(),
data: eventData.data,
metadata: eventData.metadata
};
this.apply(event);
this.uncommittedEvents.push(event);
}
// Event handlers (state mutations)
private apply(event: Event): void {
switch (event.eventType) {
case "AccountOpened":
this.balance = event.data.initialBalance;
this.isActive = true;
break;
case "MoneyDeposited":
this.balance += event.data.amount;
break;
case "MoneyWithdrawn":
this.balance -= event.data.amount;
break;
case "AccountClosed":
this.isActive = false;
break;
default:
throw new Error(`Unknown event type: ${event.eventType}`);
}
this.version = event.version;
}
// Replay events to rebuild state
static fromEvents(events: Event[]): Account {
if (events.length === 0) {
throw new Error("Cannot create account from empty event stream");
}
const account = new Account(events[0].aggregateId);
events.forEach(event => account.apply(event));
return account;
}
getUncommittedEvents(): Event[] {
return this.uncommittedEvents;
}
markEventsAsCommitted(): void {
this.uncommittedEvents = [];
}
}
// Event store interface
interface EventStore {
append(events: Event[]): Promise<void>;
getEvents(aggregateId: string, fromVersion?: number): Promise<Event[]>;
getAllEvents(fromTimestamp?: Date): Promise<Event[]>;
}
// Event store implementation
class InMemoryEventStore implements EventStore {
private events: Map<string, Event[]> = new Map();
private allEvents: Event[] = [];
async append(events: Event[]): Promise<void> {
for (const event of events) {
// Store in aggregate stream
if (!this.events.has(event.aggregateId)) {
this.events.set(event.aggregateId, []);
}
this.events.get(event.aggregateId)!.push(event);
// Store in global stream
this.allEvents.push(event);
}
}
async getEvents(
aggregateId: string,
fromVersion: number = 0
): Promise<Event[]> {
const events = this.events.get(aggregateId) || [];
return events.filter(e => e.version > fromVersion);
}
async getAllEvents(fromTimestamp?: Date): Promise<Event[]> {
if (!fromTimestamp) {
return this.allEvents;
}
return this.allEvents.filter(e => e.timestamp >= fromTimestamp);
}
}
// Repository with event sourcing
class EventSourcedAccountRepository {
constructor(private eventStore: EventStore) {}
async save(account: Account): Promise<void> {
const events = account.getUncommittedEvents();
if (events.length > 0) {
await this.eventStore.append(events);
account.markEventsAsCommitted();
}
}
async findById(accountId: string): Promise<Account | null> {
const events = await this.eventStore.getEvents(accountId);
if (events.length === 0) {
return null;
}
return Account.fromEvents(events);
}
}
Snapshots
Optimize performance by periodically saving aggregate state:
interface Snapshot {
aggregateId: string;
version: number;
timestamp: Date;
state: any;
}
class SnapshotStore {
private snapshots: Map<string, Snapshot> = new Map();
async save(snapshot: Snapshot): Promise<void> {
this.snapshots.set(snapshot.aggregateId, snapshot);
}
async getLatest(aggregateId: string): Promise<Snapshot | null> {
return this.snapshots.get(aggregateId) || null;
}
}
class EventSourcedAccountRepositoryWithSnapshots {
constructor(
private eventStore: EventStore,
private snapshotStore: SnapshotStore,
private snapshotInterval: number = 100
) {}
async save(account: Account): Promise<void> {
const events = account.getUncommittedEvents();
await this.eventStore.append(events);
account.markEventsAsCommitted();
// Create snapshot every N events
if (account.version % this.snapshotInterval === 0) {
await this.snapshotStore.save({
aggregateId: account.id,
version: account.version,
timestamp: new Date(),
state: account.toSnapshot()
});
}
}
async findById(accountId: string): Promise<Account | null> {
// Try to load from snapshot
const snapshot = await this.snapshotStore.getLatest(accountId);
let account: Account;
let fromVersion = 0;
if (snapshot) {
account = Account.fromSnapshot(snapshot.state);
fromVersion = snapshot.version;
} else {
account = new Account(accountId);
}
// Apply events after snapshot
const events = await this.eventStore.getEvents(accountId, fromVersion);
events.forEach(event => account.apply(event));
return account;
}
}
CQRS (Command Query Responsibility Segregation)
Separate read and write operations into different models, optimizing each for its specific use case.
Architecture
Commands → Command Handlers → Aggregates → Events → Event Store
↓
Event Bus
↓
Projections → Read Models → Queries
Implementation
// Commands (write operations)
interface Command {
commandId: string;
timestamp: Date;
}
class CreateAccountCommand implements Command {
commandId: string;
timestamp: Date;
accountId: string;
initialBalance: number;
constructor(accountId: string, initialBalance: number) {
this.commandId = generateId();
this.timestamp = new Date();
this.accountId = accountId;
this.initialBalance = initialBalance;
}
}
class DepositMoneyCommand implements Command {
commandId: string;
timestamp: Date;
accountId: string;
amount: number;
constructor(accountId: string, amount: number) {
this.commandId = generateId();
this.timestamp = new Date();
this.accountId = accountId;
this.amount = amount;
}
}
// Command handlers
class AccountCommandHandler {
constructor(
private repository: EventSourcedAccountRepository,
private eventBus: EventBus
) {}
async handle(command: Command): Promise<void> {
if (command instanceof CreateAccountCommand) {
await this.handleCreateAccount(command);
} else if (command instanceof DepositMoneyCommand) {
await this.handleDepositMoney(command);
}
}
private async handleCreateAccount(
command: CreateAccountCommand
): Promise<void> {
const account = new Account(command.accountId);
account.open(command.initialBalance);
await this.repository.save(account);
// Publish events
const events = account.getUncommittedEvents();
await this.eventBus.publish(events);
}
private async handleDepositMoney(
command: DepositMoneyCommand
): Promise<void> {
const account = await this.repository.findById(command.accountId);
if (!account) {
throw new Error("Account not found");
}
account.deposit(command.amount);
await this.repository.save(account);
const events = account.getUncommittedEvents();
await this.eventBus.publish(events);
}
}
// Read models (optimized for queries)
interface AccountReadModel {
accountId: string;
balance: number;
status: string;
lastActivity: Date;
transactionCount: number;
}
interface AccountSummaryReadModel {
accountId: string;
balance: number;
status: string;
}
// Projections (build read models from events)
class AccountProjection {
constructor(private db: ReadDatabase) {}
async handleEvent(event: Event): Promise<void> {
switch (event.eventType) {
case "AccountOpened":
await this.handleAccountOpened(event);
break;
case "MoneyDeposited":
await this.handleMoneyDeposited(event);
break;
case "MoneyWithdrawn":
await this.handleMoneyWithdrawn(event);
break;
case "AccountClosed":
await this.handleAccountClosed(event);
break;
}
}
private async handleAccountOpened(event: Event): Promise<void> {
await this.db.accounts.insert({
accountId: event.aggregateId,
balance: event.data.initialBalance,
status: "Active",
lastActivity: event.timestamp,
transactionCount: 0
});
}
private async handleMoneyDeposited(event: Event): Promise<void> {
await this.db.accounts.update(
{ accountId: event.aggregateId },
{
$inc: { balance: event.data.amount, transactionCount: 1 },
$set: { lastActivity: event.timestamp }
}
);
}
private async handleMoneyWithdrawn(event: Event): Promise<void> {
await this.db.accounts.update(
{ accountId: event.aggregateId },
{
$inc: { balance: -event.data.amount, transactionCount: 1 },
$set: { lastActivity: event.timestamp }
}
);
}
private async handleAccountClosed(event: Event): Promise<void> {
await this.db.accounts.update(
{ accountId: event.aggregateId },
{
$set: {
status: "Closed",
lastActivity: event.timestamp
}
}
);
}
}
// Query service (read-only)
class AccountQueryService {
constructor(private db: ReadDatabase) {}
async getAccount(accountId: string): Promise<AccountReadModel | null> {
return await this.db.accounts.findOne({ accountId });
}
async getAccountsByStatus(status: string): Promise<AccountSummaryReadModel[]> {
return await this.db.accounts.find(
{ status },
{ projection: { accountId: 1, balance: 1, status: 1 } }
);
}
async getHighBalanceAccounts(
minBalance: number
): Promise<AccountSummaryReadModel[]> {
return await this.db.accounts.find(
{ balance: { $gte: minBalance } },
{ projection: { accountId: 1, balance: 1, status: 1 } }
);
}
}
// Event bus for publishing events
class EventBus {
private subscribers: Map<string, Function[]> = new Map();
subscribe(eventType: string, handler: Function): void {
if (!this.subscribers.has(eventType)) {
this.subscribers.set(eventType, []);
}
this.subscribers.get(eventType)!.push(handler);
}
subscribeToAll(handler: Function): void {
this.subscribe("*", handler);
}
async publish(events: Event[]): Promise<void> {
for (const event of events) {
// Call specific handlers
const handlers = this.subscribers.get(event.eventType) || [];
await Promise.all(handlers.map(h => h(event)));
// Call wildcard handlers
const allHandlers = this.subscribers.get("*") || [];
await Promise.all(allHandlers.map(h => h(event)));
}
}
}
Saga Pattern
Manage distributed transactions across multiple services using a sequence of local transactions coordinated by a saga.
Orchestration-Based Saga
A central orchestrator coordinates all saga participants.
// Saga state
enum SagaStatus {
Started = "Started",
Completed = "Completed",
Compensating = "Compensating",
Compensated = "Compensated",
Failed = "Failed"
}
interface SagaStep {
name: string;
action: () => Promise<void>;
compensation: () => Promise<void>;
}
class OrderSaga {
private sagaId: string;
private status: SagaStatus;
private completedSteps: string[] = [];
private currentStep: number = 0;
private steps: SagaStep[] = [
{
name: "CreateOrder",
action: async () => await this.createOrder(),
compensation: async () => await this.cancelOrder()
},
{
name: "ReserveInventory",
action: async () => await this.reserveInventory(),
compensation: async () => await this.releaseInventory()
},
{
name: "ProcessPayment",
action: async () => await this.processPayment(),
compensation: async () => await this.refundPayment()
},
{
name: "ArrangeShipment",
action: async () => await this.arrangeShipment(),
compensation: async () => await this.cancelShipment()
}
];
constructor(
private orderId: string,
private customerId: string,
private items: OrderItem[]
) {
this.sagaId = generateId();
this.status = SagaStatus.Started;
}
async execute(): Promise<void> {
try {
// Execute each step
for (let i = 0; i < this.steps.length; i++) {
this.currentStep = i;
const step = this.steps[i];
console.log(`Executing step: ${step.name}`);
await step.action();
this.completedSteps.push(step.name);
}
this.status = SagaStatus.Completed;
console.log("Saga completed successfully");
} catch (error) {
console.error(`Saga failed at step ${this.currentStep}:`, error);
await this.compensate();
}
}
private async compensate(): Promise<void> {
this.status = SagaStatus.Compensating;
console.log("Starting compensation");
// Compensate in reverse order
for (let i = this.completedSteps.length - 1; i >= 0; i--) {
const stepName = this.completedSteps[i];
const step = this.steps.find(s => s.name === stepName);
if (step) {
try {
console.log(`Compensating step: ${step.name}`);
await step.compensation();
} catch (error) {
console.error(`Compensation failed for ${step.name}:`, error);
// Log for manual intervention
}
}
}
this.status = SagaStatus.Compensated;
console.log("Compensation completed");
}
// Step implementations
private async createOrder(): Promise<void> {
await orderService.create({
orderId: this.orderId,
customerId: this.customerId,
items: this.items
});
}
private async cancelOrder(): Promise<void> {
await orderService.cancel(this.orderId);
}
private async reserveInventory(): Promise<void> {
await inventoryService.reserve(this.orderId, this.items);
}
private async releaseInventory(): Promise<void> {
await inventoryService.release(this.orderId);
}
private async processPayment(): Promise<void> {
const total = this.calculateTotal();
await paymentService.charge(this.customerId, total);
}
private async refundPayment(): Promise<void> {
const total = this.calculateTotal();
await paymentService.refund(this.customerId, total);
}
private async arrangeShipment(): Promise<void> {
await shippingService.createShipment(this.orderId);
}
private async cancelShipment(): Promise<void> {
await shippingService.cancelShipment(this.orderId);
}
private calculateTotal(): Money {
return this.items.reduce(
(sum, item) => sum.add(item.price.multiply(item.quantity)),
new Money(0, "USD")
);
}
}
// Orchestrator service
class SagaOrchestrator {
private activeSagas: Map<string, OrderSaga> = new Map();
async startOrderSaga(
orderId: string,
customerId: string,
items: OrderItem[]
): Promise<void> {
const saga = new OrderSaga(orderId, customerId, items);
this.activeSagas.set(saga.sagaId, saga);
try {
await saga.execute();
} finally {
this.activeSagas.delete(saga.sagaId);
}
}
getSagaStatus(sagaId: string): SagaStatus | null {
const saga = this.activeSagas.get(sagaId);
return saga ? saga.status : null;
}
}
Choreography-Based Saga
Services coordinate through events without central orchestrator.
// Event-driven saga with choreography
class OrderCreatedEvent {
constructor(
public orderId: string,
public customerId: string,
public items: OrderItem[]
) {}
}
class InventoryReservedEvent {
constructor(
public orderId: string,
public reservationId: string
) {}
}
class PaymentProcessedEvent {
constructor(
public orderId: string,
public paymentId: string
) {}
}
class ShipmentArrangedEvent {
constructor(
public orderId: string,
public shipmentId: string
) {}
}
// Compensation events
class InventoryReservationFailedEvent {
constructor(
public orderId: string,
public reason: string
) {}
}
class PaymentFailedEvent {
constructor(
public orderId: string,
public reason: string
) {}
}
// Order service
class OrderService {
constructor(private eventBus: EventBus) {
// Subscribe to compensation events
eventBus.subscribe("InventoryReservationFailed",
this.handleInventoryReservationFailed.bind(this));
eventBus.subscribe("PaymentFailed",
this.handlePaymentFailed.bind(this));
}
async createOrder(order: CreateOrderRequest): Promise<void> {
// Create order in pending state
await this.repository.save({
...order,
status: "Pending"
});
// Publish event to trigger next step
await this.eventBus.publish(
new OrderCreatedEvent(order.orderId, order.customerId, order.items)
);
}
private async handleInventoryReservationFailed(
event: InventoryReservationFailedEvent
): Promise<void> {
await this.repository.updateStatus(event.orderId, "Cancelled");
console.log(`Order ${event.orderId} cancelled: ${event.reason}`);
}
private async handlePaymentFailed(event: PaymentFailedEvent): Promise<void> {
await this.repository.updateStatus(event.orderId, "PaymentFailed");
// Trigger inventory release
await this.eventBus.publish(
new ReleaseInventoryCommand(event.orderId)
);
}
}
// Inventory service
class InventoryService {
constructor(private eventBus: EventBus) {
eventBus.subscribe("OrderCreated",
this.handleOrderCreated.bind(this));
eventBus.subscribe("ReleaseInventory",
this.handleReleaseInventory.bind(this));
}
private async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
try {
// Reserve inventory
const reservationId = await this.reserveItems(event.items);
// Publish success event
await this.eventBus.publish(
new InventoryReservedEvent(event.orderId, reservationId)
);
} catch (error) {
// Publish failure event
await this.eventBus.publish(
new InventoryReservationFailedEvent(
event.orderId,
error.message
)
);
}
}
private async handleReleaseInventory(
command: ReleaseInventoryCommand
): Promise<void> {
await this.releaseReservation(command.orderId);
}
}
// Payment service
class PaymentService {
constructor(private eventBus: EventBus) {
eventBus.subscribe("InventoryReserved",
this.handleInventoryReserved.bind(this));
eventBus.subscribe("RefundPayment",
this.handleRefundPayment.bind(this));
}
private async handleInventoryReserved(
event: InventoryReservedEvent
): Promise<void> {
try {
// Process payment
const paymentId = await this.chargeCustomer(event.orderId);
// Publish success event
await this.eventBus.publish(
new PaymentProcessedEvent(event.orderId, paymentId)
);
} catch (error) {
// Publish failure event
await this.eventBus.publish(
new PaymentFailedEvent(event.orderId, error.message)
);
}
}
private async handleRefundPayment(
command: RefundPaymentCommand
): Promise<void> {
await this.refund(command.orderId);
}
}
API Gateway Pattern
Single entry point for clients, routing requests to appropriate microservices and handling cross-cutting concerns.
Implementation
class APIGateway {
constructor(
private router: Router,
private authService: AuthService,
private rateLimiter: RateLimiter,
private circuitBreaker: CircuitBreaker,
private loadBalancer: LoadBalancer
) {
this.setupRoutes();
}
private setupRoutes(): void {
// User service routes
this.router.get("/api/users/:id",
this.authenticate.bind(this),
this.rateLimit.bind(this),
this.getUserHandler.bind(this)
);
// Order service routes
this.router.post("/api/orders",
this.authenticate.bind(this),
this.rateLimit.bind(this),
this.createOrderHandler.bind(this)
);
// Product service routes
this.router.get("/api/products",
this.rateLimit.bind(this),
this.getProductsHandler.bind(this)
);
}
// Middleware: Authentication
private async authenticate(
req: Request,
res: Response,
next: NextFunction
): Promise<void> {
try {
const token = req.headers.authorization?.replace("Bearer ", "");
if (!token) {
res.status(401).json({ error: "Unauthorized" });
return;
}
const user = await this.authService.validateToken(token);
req.user = user;
next();
} catch (error) {
re
…(truncated)