Architecture
This section explains how the gateway is put together and why the main boundaries exist.
🧭 Read this when changing the hot path. The architecture pages keep request handling, config lookup, backend sessions, transports, and control-plane boundaries explicit.
The pages are ordered for a first read: start at the top for the big picture, then work down into each boundary. If you are changing one area, jump straight to its page.
| Page | What it covers |
|---|---|
| 🧭 System Shape | The gateway’s role in ContextForge, its crate layout, and the line between dataplane and control plane. |
| 🔀 Request Flow | The ordered path from downstream HTTP request to backend MCP call and merged response. |
| 🧵 Concurrency And Runtime Model | Executor shapes, shared state and locks, fanout, cancellation, and the allocator. |
| 🔐 Authentication And User Config Lookup | How JWT claims, Redis-backed user config, and virtual host selection combine before routing. |
| 🔒 Security Model And Trust Boundaries | What the gateway trusts, what compromise of each boundary means, and transport security posture. |
| 🗂️ Runtime Configuration | The current UserConfig model, MessagePack Redis persistence, cache behavior, and expected growth. |
| 🤝 Control-Plane Integration | The current, still-provisional integration surface: Redis keys, schemas, token shape, and route parity. |
| 🔌 Backend Connections And Transports | Downstream listeners, upstream RMCP transports, config-store transport, and TLS direction. |
| 🧵 Session Ownership | How backend services are keyed, shared, cleaned up, and constrained by local process ownership. |
| 🧱 Architectural Choices | The main tradeoffs behind dataplane scope, namespacing, config boundaries, and future protocols. |