Microservices Patterns Guide

A reference for the architectural patterns used in this kit and when to

apply them in production.

1. API Gateway

What: A single entry point that routes requests to downstream services

and handles cross-cutting concerns (auth, rate limiting, logging).

When to use: Always. Even with two services, a gateway simplifies

client integration and centralises security enforcement.

Client → API Gateway → User Service
                     → Order Service

Trade-offs:

• Pro: Single TLS termination point, centralised auth
• Con: Single point of failure (mitigate with replicas and health checks)

2. Database per Service

What: Each microservice owns its data store. Services never access

another service's database directly.

When to use: Default choice. Sharing a database couples services at

the schema level, defeating the purpose of microservices.

Implementation:

# user-service owns its own SQLite / Postgres
DATABASE_URL=sqlite:///./users.db

# order-service has its own store
DATABASE_URL=sqlite:///./orders.db

To query data owned by another service, use the service client (HTTP)

or listen for domain events.

3. Domain Events (Event-Driven Communication)

What: Services communicate by publishing and subscribing to events

rather than making synchronous calls.

When to use: When a state change in one service should trigger

behaviour in another without tight coupling.

Order Service  ──publishes──▶  "order.created"
                                    │
User Service  ◀──subscribes────────┘
  (sends confirmation email)

Transport options (swap the EventBus implementation):

4. Circuit Breaker

What: Wraps inter-service HTTP calls. After N consecutive failures,

the circuit "opens" and immediately rejects requests for a recovery

period, preventing cascading failures.

States:

  ┌──────────┐     N failures     ┌──────────┐
  │  CLOSED  │ ─────────────────▶ │   OPEN   │
  │ (normal) │                    │ (reject) │
  └──────────┘                    └────┬─────┘
       ▲                               │ recovery timeout
       │         1 success             │
       └──────────────────── ┌─────────▼──────┐
                             │  HALF-OPEN     │
                             │ (probe 1 req)  │
                             └────────────────┘

Configuration (in ServiceClient):

client = ServiceClient(
    base_url="http://user-service:8001",
    circuit_failure_threshold=5,   # open after 5 failures
    circuit_recovery_timeout=30.0, # try again after 30s
)

5. Correlation IDs (Distributed Tracing)

What: A unique ID assigned to each external request, propagated

through all inter-service calls via the x-correlation-id header.

Why: In production, a single user click can trigger requests across

5+ services. Without a correlation ID, piecing together the log trail

is impossible.

[a1b2c3d4] POST /api/orders          ← gateway
[a1b2c3d4] GET /users/usr_abc123     ← order-service → user-service
[a1b2c3d4] PUBLISH order.created     ← order-service

Implementation: The CorrelationMiddleware in shared/tracing.py

handles ID generation and propagation automatically.

6. Health Checks

What: Each service exposes a /health endpoint. The gateway

aggregates them into a composite health report.

Kubernetes-style probes:

Production config (in docker-compose.prod.yml):

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
  interval: 30s
  timeout: 5s
  retries: 3

7. Retry with Exponential Back-Off

What: On transient failures (network blips, 503s), retry the

request after an exponentially increasing delay.

Attempt 1 → fail → wait 0.5s
Attempt 2 → fail → wait 1.0s
Attempt 3 → fail → give up (or open circuit breaker)

Why: Most transient errors resolve within seconds. Retrying

immediately causes thundering herd problems; back-off spreads the load.

8. Strangler Fig Migration

What: When migrating from a monolith, route traffic through the

gateway. Gradually replace monolith endpoints with microservices.

Gateway
  ├── /api/users   → NEW User Service
  ├── /api/orders  → NEW Order Service
  └── /api/legacy  → OLD Monolith (shrinking)

Steps:

1. Deploy the gateway in front of the monolith.

2. Extract one bounded context at a time.

3. Route new traffic to the microservice; keep the monolith as fallback.

4. Remove the monolith route once fully migrated.

Quick-Reference: When to Split a Service

*By Datanest Digital — Microservices Patterns Guide*