patterns – Documents & Office skill for AI agents

MONOPOLY — Design Patterns Deep Dive

When to Use

• Use this skill when the task matches this description: Reference document for monopoly patterns.

Table of Contents

1. CQRS

2. Event Sourcing

3. Saga Pattern

4. Circuit Breaker

5. Bulkhead

6. Strangler Fig

7. Sidecar / Service Mesh

8. Outbox Pattern

9. Consistent Hashing

10. Backpressure

11. Leader Election

12. Two-Phase Commit

---

1. CQRS (Command Query Responsibility Segregation)

What it is: Separate the read model (Query) from the write model (Command) into distinct services, databases, or code paths.

When to use:

• Read load is 10×+ write load (most web apps)
• Read queries are complex aggregations over write data
• Need to optimize read and write paths independently
• Domain model is complex (DDD contexts)

Implementation:

Write Path:  Client → Command API → Write DB (normalized, PostgreSQL)
Read Path:   Client → Query API  → Read DB (denormalized, Redis / Elasticsearch)
Sync:        Write DB → CDC (Debezium) → Message Queue → Read DB updater

Trade-offs:

• ✅ Independent scaling of read and write
• ✅ Optimized schemas for each operation type
• ❌ Eventual consistency between write and read models
• ❌ Increased complexity; two models to maintain

Evidence: Named-company examples require a primary architecture source; none is established by this reference.

---

2. Event Sourcing

What it is: Store state as a sequence of immutable events rather than current state. Rebuild current state by replaying events.

When to use:

• Domain replay/history is required and simpler audit logs do not meet the use case
• Need to replay history for debugging or analytics
• Complex domain with many state transitions
• Need to derive multiple read projections from same data

Implementation:

Event Store: append-only log (Kafka, EventStoreDB)
Snapshots:   periodic snapshots to speed up state rebuild
Projections: consumers build read models from events

Trade-offs:

• ✅ Replayable domain history when event integrity, retention and schema evolution are designed; not automatic regulatory compliance
• ✅ Replay and time-travel debugging
• ❌ Querying current state requires projection maintenance
• ❌ Event schema evolution is hard
• ❌ High storage overhead over time

---

3. Saga Pattern

What it is: Manage distributed transactions across microservices via a sequence of local transactions, each publishing an event. If a step fails, compensating transactions undo previous steps.

Two variants:

• Choreography: Services react to events autonomously (decentralized)
• Orchestration: A central Saga Orchestrator coordinates steps (centralized)

When to use:

• Multi-service workflows where ACID across services is impossible
• Long-running business transactions (order → payment → inventory → shipping)
• Need rollback across service boundaries

Choreography Example:

OrderService creates order →
  [event: OrderCreated] →
    PaymentService charges card →
      [event: PaymentProcessed] →
        InventoryService reserves stock →
          [event: StockReserved] →
            ShippingService books courier

Compensating Transactions (on failure):

ShippingService fails →
  [event: ShippingFailed] →
    InventoryService releases stock →
      PaymentService refunds card →
        OrderService marks order failed

Trade-offs:

• ✅ Local transactions avoid cross-service locking; workflow availability and compensation failures still need handling
• ✅ Scales well across services
• ❌ Hard to debug; distributed trace required
• ❌ Compensating transactions are complex to implement correctly

---

4. Circuit Breaker

What it is: A proxy that monitors calls to a service. If failure rate exceeds threshold, the circuit "opens" and calls fail fast instead of waiting for timeout.

States:

CLOSED  → calls pass through; monitor failure rate
OPEN    → calls fail immediately; no calls to downstream
HALF-OPEN → let a probe call through; if success, close; if fail, stay open

When to use:

• Calling any external service (payment gateway, SMS, email)
• Microservices calling each other
• Preventing timeout cascade when downstream is slow

Implementation tools: Hystrix (deprecated), Resilience4j, Polly (.NET), Envoy proxy

Thresholds (starting point):

• Open after 50% failure rate over 10 requests
• Stay open for 30 seconds
• Half-open: allow 1 probe request

Trade-offs:

• ✅ Prevents cascade failures
• ✅ Gives downstream time to recover
• ❌ Adds latency overhead for monitoring
• ❌ Requires fallback behavior when circuit is open

---

5. Bulkhead

What it is: Isolate components so a failure in one doesn't consume resources of others. Named after the watertight compartments in ship hulls.

Types:

• Thread Pool Bulkhead: Separate thread pools per service call
• Semaphore Bulkhead: Limit concurrent calls per service
• Process Bulkhead: Separate processes/containers per service type

When to use:

• Multiple tenants sharing infrastructure (SaaS)
• One slow service consuming all connection pool slots
• Protecting critical services from being starved by non-critical ones

Example:

Without bulkhead:
  [Recommendation Service hangs] → fills shared thread pool → [Payment Service starves]

With bulkhead:
  [Recommendation Service hangs] → fills its own thread pool (10 threads) → [Payment Service unaffected, has its own 50 threads]

---

6. Strangler Fig Pattern

What it is: Incrementally replace a legacy monolith by routing new functionality to new microservices, while keeping the monolith alive for unchanged features.

Migration steps:

Phase 1: Deploy proxy in front of monolith (no user impact)
Phase 2: Route one feature to new microservice
Phase 3: Verify; deprecate that feature in monolith
Phase 4: Repeat for each feature
Phase 5: Monolith is empty; decommission

When to use:

• Migrating legacy monolith to microservices
• Can't do a big-bang rewrite (too risky)
• Need to ship new features during migration

Trade-offs:

• ✅ Incremental migration can reduce downtime; verify cutover, data compatibility and rollback
• ✅ Incremental risk
• ❌ Dual maintenance burden during migration (monolith + new services)
• ❌ Proxy adds latency; must be managed carefully

---

7. Outbox Pattern

What it is: Solve the dual-write problem (write to DB AND publish to queue atomically) by writing the event to an "outbox" table in the same DB transaction, then having a separate process relay it to the queue.

Problem it solves:

❌ WRONG (dual-write race):
  BEGIN;
  UPDATE orders SET status='paid';
  COMMIT;
  // Crash here → event never published, DB and queue are inconsistent
  publish(PaymentProcessed);

✅ CORRECT (outbox):
  BEGIN;
  UPDATE orders SET status='paid';
  INSERT INTO outbox (event_type, payload) VALUES ('PaymentProcessed', {...});
  COMMIT;
  // Relay process reads outbox and publishes to Kafka
  // At-least-once only with durable outbox, retrying relay and acknowledged
  // broker writes; make consumers idempotent and monitor poison/backlog records

Relay options: Debezium (CDC), polling relay, transaction log tailing

---

8. Consistent Hashing

What it is: A hashing scheme where adding or removing nodes requires only K/N keys to be remapped (K = keys, N = nodes), instead of remapping all keys.

When to use:

• Designing a custom hash-ring cache/router; Redis Cluster itself uses 16,384 hash slots, not this ring formula
• Routing requests to servers in a distributed system
• Partitioning data across database nodes

Virtual nodes: Multiple positions can improve statistical balance; they do not guarantee uniform load under hot keys or skewed object sizes.

---

9. Backpressure

What it is: A mechanism for consumers to signal producers to slow down when they can't keep up, preventing memory exhaustion and cascade failures.

Strategies:

• Drop: Discard overflow messages (acceptable for metrics, logs)
• Buffer: Queue up to a limit, then block or drop
• Block: Producer waits until consumer catches up (simplest, may cause timeout)
• Rate Limit: Throttle producers at ingestion point

When to use:

• Message queue consumers are slower than producers
• Real-time data pipeline ingestion spikes
• API rate limiting for upstream clients

---

10. Leader Election

What it is: In a distributed system, elect a single node to perform a privileged task (e.g., writing to DB, sending scheduled jobs, coordinating work).

An elected leader does not by itself prevent an expired/partitioned leader from writing. Use fencing tokens checked by the resource, idempotent jobs and durable progress; election is not exactly-once execution.

Algorithms:

• Raft: Used by etcd, CockroachDB, Consul. Practical and well-understood.
• ZooKeeper (ZAB): Used by Kafka, HBase. Mature but operationa

… (full content is in the download package)