┌─────────────────────────────────────┐
│         Presentation Layer          │
├─────────────────────────────────────┤
│         Application Layer           │
├─────────────────────────────────────┤
│           Domain Layer              │
├─────────────────────────────────────┤
│        Infrastructure Layer         │
└─────────────────────────────────────┘

                 ┌─────────┐
         ┌──────│   API   │──────┐
         │      └─────────┘      │
    ┌────▼────┐           ┌──────▼──────┐
    │   CLI   │           │  Database   │
    └────┬────┘           └──────┬──────┘
         │      ┌─────────┐      │
         └──────│  Core   │──────┘
                │ Domain  │
         ┌──────│         │──────┐
         │      └─────────┘      │
    ┌────▼────┐           ┌──────▼──────┐
    │  Queue  │           │  External   │
    └─────────┘           │   Service   │
                          └─────────────┘

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Service A  │────▶│   Event     │────▶│  Service B  │
└─────────────┘     │    Bus      │     └─────────────┘
                    │             │
┌─────────────┐     │             │     ┌─────────────┐
│  Service C  │◀────│             │────▶│  Service D  │
└─────────────┘     └─────────────┘     └─────────────┘

┌─────────────────────────────────────────────────────────┐
│                    Choreography Saga                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Order        Inventory       Payment       Shipping     │
│  Service      Service         Service       Service      │
│    │             │               │             │         │
│    │──Create────▶│               │             │         │
│    │             │───Reserve────▶│             │         │
│    │             │               │───Charge───▶│         │
│    │             │               │             │──Ship   │
│    │◀───────────────────────────────────Complete│        │
│                                                          │
│  Compensation (on failure):                              │
│    │◀─Release───│◀──Refund─────│◀──Cancel────│          │
│                                                          │
└─────────────────────────────────────────────────────────┘

Phase 1 (Prepare):
  Coordinator → All Participants: "Prepare"
  All Participants → Coordinator: "Ready" or "Abort"

Phase 2 (Commit/Abort):
  If all Ready:
    Coordinator → All Participants: "Commit"
  Else:
    Coordinator → All Participants: "Abort"

┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Load      │
└─────────────┘     │  Balancer   │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Server 1 │    │ Server 2 │    │ Server 3 │
    └────┬─────┘    └────┬─────┘    └────┬─────┘
         │               │               │
         └───────────────┼───────────────┘
                         ▼
              ┌─────────────────────┐
              │   Shared State      │
              │   (Redis/DB)        │
              └─────────────────────┘

┌─────────────────────────────────────────────────────┐
│  L1: Application Cache (in-memory)      ~1ms       │
├─────────────────────────────────────────────────────┤
│  L2: Distributed Cache (Redis)          ~5ms       │
├─────────────────────────────────────────────────────┤
│  L3: CDN Cache                          ~50ms      │
├─────────────────────────────────────────────────────┤
│  L4: Database                           ~100ms     │
└─────────────────────────────────────────────────────┘

Cache-Aside:
  1. Check cache
  2. If miss, read from DB
  3. Store in cache
  4. Return data

Write-Through:
  1. Write to cache
  2. Cache writes to DB
  3. Return success

Write-Behind:
  1. Write to cache
  2. Return success
  3. Cache async writes to DB

┌────────────┐
│   Master   │◀────── Writes
└─────┬──────┘
      │ Replication
      ├──────────────┬──────────────┐
      ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Replica 1│  │ Replica 2│  │ Replica 3│
└────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │
     └─────────────┴─────────────┘
                   │
              Reads distributed

# URL Path
GET /api/v1/users

# Query Parameter
GET /api/users?version=1

# Header
GET /api/users
Accept: application/vnd.api+json;version=1

# Content Negotiation
GET /api/users
Accept: application/vnd.company.api.v1+json

Bucket Capacity: 100 tokens
Refill Rate: 10 tokens/second

Request arrives:
  If tokens > 0:
    tokens -= 1
    Process request
  Else:
    Reject (429 Too Many Requests)

States: CLOSED → OPEN → HALF-OPEN → CLOSED

CLOSED:
  - Normal operation
  - Track failures
  - If failure_count > threshold: → OPEN

OPEN:
  - Reject all requests immediately
  - After timeout: → HALF-OPEN

HALF-OPEN:
  - Allow limited requests
  - If success: → CLOSED
  - If failure: → OPEN

┌─────────────────────────────────────────────┐
│               Application                    │
├─────────────┬─────────────┬─────────────────┤
│  Thread     │  Thread     │  Thread         │
│  Pool A     │  Pool B     │  Pool C         │
│  (Orders)   │  (Users)    │  (Analytics)    │
│             │             │                 │
│  [===]      │  [===]      │  [===]          │
│  10 threads │  10 threads │  5 threads      │
└─────────────┴─────────────┴─────────────────┘

If Orders service fails, only Pool A exhausted.
Pools B and C continue operating.

def exponential_backoff(attempt: int, base: float = 1.0, max_delay: float = 60.0):
    delay = min(base * (2 ** attempt), max_delay)
    jitter = random.uniform(0, delay * 0.1)
    return delay + jitter

# Retry pattern
for attempt in range(max_retries):
    try:
        result = make_request()
        break
    except TransientError:
        if attempt == max_retries - 1:
            raise
        time.sleep(exponential_backoff(attempt))

# ADR-001: Use PostgreSQL for primary database

## Status
Accepted

## Context
We need to choose a primary database for our e-commerce platform.
Requirements:
- ACID transactions for orders
- Complex queries for reporting
- Scalability to 10M users

## Decision
We will use PostgreSQL as our primary database.

## Consequences
Positive:
- Strong consistency guarantees
- Rich SQL features
- Excellent JSON support
- Large ecosystem

Negative:
- Manual sharding required at scale
- More complex HA setup than managed NoSQL

## Alternatives Considered
- MongoDB: Better horizontal scaling, but weaker transactions
- CockroachDB: Better scaling, but higher operational complexity
- MySQL: Similar features, but less advanced JSON support

Level 1 - System Context:
  [User] → [System] → [External Systems]

Level 2 - Container:
  [Web App] → [API] → [Database]
                ↓
           [Message Queue] → [Worker]

Level 3 - Component:
  API Container:
    [Controllers] → [Services] → [Repositories]

Level 4 - Code:
  Class diagrams, sequence diagrams

# Architecture diagram generator
python scripts/arch_diagram.py --config services.yaml --output diagram.png

# Dependency analyzer
python scripts/dep_analyzer.py --path ./services --output deps.json

# Capacity planner
python scripts/capacity_plan.py --current 10000 --growth 0.5 --period 12

# Service mesh analyzer
python scripts/mesh_analyzer.py --namespace production