Architecture Library

System diagrams, explained.

A growing collection of architecture diagrams from real systems - distilled to the choices that mattered and the trade-offs behind them.

AI Orchestration Control Plane

How requests flow through routing, policy, execution, and observability when a single API call can touch multiple models and tools.

AIArchitectureAgents

        ┌──────────────┐
        │   Client     │
        └──────┬───────┘
               │
        ┌──────▼───────┐      ┌─────────────┐
        │   Gateway    │─────▶│   Policy    │
        └──────┬───────┘      │  (budget,   │
               │              │   safety)   │
        ┌──────▼───────┐      └─────────────┘
        │   Router     │
        │  (capability │
        │   graph)     │
        └──┬────────┬──┘
           │        │
   ┌───────▼──┐  ┌──▼────────┐
   │  Model   │  │   MCP     │
   │  Pool    │  │  Tools    │
   └───────┬──┘  └──┬────────┘
           │        │
        ┌──▼────────▼──┐
        │   Executor   │
        └──────┬───────┘
               │
        ┌──────▼───────┐
        │   Traces +   │
        │   Eval Store │
        └──────────────┘

Notes

Policy runs before dispatch so cost ceilings are enforced pre-call
Router resolves the capability graph at request time, not compile time
Every step emits a span - replay is a first-class dev surface

Azure Stack for a Small Team

The pragmatic Azure baseline I reach for when shipping with 1-5 engineers.

AzureCloudArchitecture

   ┌─────────────┐      ┌─────────────┐
   │   Front     │      │     CDN     │
   │   Door      │─────▶│  + Storage  │
   └──────┬──────┘      └─────────────┘
          │
   ┌──────▼─────────────────────────┐
   │     Container Apps Env         │
   │  ┌────────┐ ┌────────┐ ┌─────┐ │
   │  │  web   │ │  api   │ │ job │ │
   │  └────────┘ └────────┘ └─────┘ │
   └──────┬──────────────┬──────────┘
          │              │
   ┌──────▼──────┐  ┌────▼────────┐
   │  Postgres   │  │  Key Vault  │
   │  Flexible   │  │  (managed   │
   │  Server     │  │  identity)  │
   └─────────────┘  └─────────────┘
          │
   ┌──────▼──────┐
   │ App Insights│
   │  (logs +    │
   │   traces)   │
   └─────────────┘

Notes

Container Apps replaces AKS for the 95% case
Managed identities everywhere - no connection strings in app settings
Application Insights for logs and traces in one place

Agent State + Replay Pipeline

Treating every agent run as a replayable transcript turns debugging from guesswork into a workflow.

AgentsAISystem Design

   Agent Run ──▶ Event Log ──▶ Object Store
                       │
                       ▼
                  ┌─────────┐
                  │ Replay  │──▶ Local Debug
                  │ Engine  │──▶ Eval Harness
                  └─────────┘──▶ Regression Set

Notes

Event log is append-only, addressable by run id
Replay engine reconstructs the exact tool + model state
Failed runs become regression tests automatically