Architecture Decision Records¶
This page tracks all significant design decisions made for ContextForge project, using the ADR format.
| ID | Title | Status | Section | Date |
|---|---|---|---|---|
| 0001 | Adopt FastAPI + Pydantic V2 (Rust-core) | Accepted | Framework | 2025-02-01 |
| 0002 | Use Async SQLAlchemy ORM with Connection Pooling | Accepted | Persistence | 2025-02-01 |
| 0003 | Expose Multi-Transport Endpoints | Accepted | Transport | 2025-02-01 |
| 0004 | Combine JWT & Basic Auth | Accepted | Security | 2025-02-01 |
| 0005 | Structured JSON Logging | Implemented | Observability | 2025-02-21 |
| 0005b | VS Code Dev Container Support | Accepted | Development | 2025-02-21 |
| 0006 | Gateway & Tool-Level Rate Limiting | Accepted | Performance | 2025-02-21 |
| 0007 | Pluggable Cache Backend (memory / Redis Cluster / DB) | Accepted | Caching | 2025-02-21 |
| 0008 | Federation & Auto-Discovery via DNS-SD | Deprecated | Federation | 2025-02-21 |
| 0009 | Built-in Health Checks & Self-Monitoring | Accepted | Operations | 2025-02-21 |
| 0010 | Observability via Prometheus, Structured Logs | Accepted | Observability | 2025-02-21 |
| 0011 | Namespaced Tool Federation | Implemented | Federation | 2025-03-01 |
| 0012 | Drop-down UI Tool Selection | Draft | User Interface | 2025-03-01 |
| 0013 | APIs for Server Connection Strings | Draft | API Design | 2025-03-01 |
| 0014 | Security Headers & Environment-Aware CORS Middleware | Accepted | Security | 2025-08-17 |
| 0015 | Configurable Well-Known URI Handler | Accepted | Security | 2025-08-17 |
| 0016 | Plugin Framework & AI Middleware | Implemented | Extensibility | 2025-08-17 |
| 0017 | Adopt orjson for High-Performance JSON | Accepted | Performance | 2025-10-27 |
| 0018 | Built-in Response Compression (Brotli/Zstd/GZip) | Accepted | Performance | 2025-10-27 |
| 0019 | Modular Architecture Split (14 Independent Modules) | Accepted | Architecture | 2025-10-27 |
| 0020 | Multi-Format Packaging Strategy | Accepted | Distribution | 2025-10-27 |
| 0021 | Built-in Proxy Capabilities vs Service Mesh | Accepted | Architecture | 2025-10-27 |
| 0022 | Elicitation Passthrough Implementation | Accepted | MCP Protocol | 2025-10-26 |
| 0023 | One-Time Authentication Servers | Accepted | Security | 2025-10-27 |
| 0024 | Adopt uvicorn[standard] for Enhanced Server Performance | Accepted | Performance | 2025-12-21 |
| 0025 | Adopt Granian as Alternative HTTP Server | Accepted | Performance | 2025-12-21 |
| 0026 | Add Hiredis as Default Redis Parser | Accepted | Performance | 2025-12-21 |
| 0027 | Migrate from Psycopg2 to Psycopg3 | Accepted | Database | 2025-01-15 |
| 0028 | Authentication Data Caching | Accepted | Performance | 2025-01-15 |
| 0029 | Registry and Admin Stats Caching | Accepted | Performance | 2025-01-15 |
| 0030 | Metrics Cleanup and Rollup | Accepted | Performance | 2025-01-15 |
| 0031 | Parallel Session Cleanup with asyncio.gather() | Accepted | Performance | 2025-01-15 |
| 0032 | MCP Session Pool for Connection Reuse | Accepted | Performance | 2025-01-05 |
| 0033 | Tool Lookup Cache for invoke_tool | Accepted | Performance | 2025-01-20 |
| 0035 | Query Parameter Authentication for Gateways | Accepted | Security | 2026-01-19 |
| 0037 | External Plugin STDIO Launch with Command/Env Overrides | Accepted | Extensibility | 2026-01-28 |
| 0038 | Experimental Rust Transport Backend (Streamable HTTP) | Superseded | Performance | 2025-12-26 |
| 0039 | Adopt Fully Independent Plugin Crates Architecture | Accepted | Architecture | 2026-02-13 |
| 0040 | Flexible Admin UI Section Visibility | Accepted | User Interface | 2026-02-16 |
| 0041 | Top-Level Rust Workspace (Cargo.toml at Repository Root) | Accepted | Architecture | 2026-02-26 |
| 0042 | Enforce Rust in the Build Process | Proposed | Build | 2026-02-26 |
| 0043 | Rust MCP Runtime Sidecar with Mode-Based Rollout | Accepted | Architecture | 2026-03-14 |
| 0044 | Module Communication Protocol (gRPC over UDS) | Proposed | Architecture | 2026-03-15 |
| 0045 | Authentication and Authorization Remain in Core | Proposed | Security | 2026-03-15 |
| 0046 | Shared-Nothing Between Protocol Modules | Proposed | Architecture | 2026-03-15 |
| 0047 | Incremental Migration Over Rewrite | Proposed | Architecture | 2026-03-15 |
| 0048 | Extract Rust-Backed Plugins First and Preserve Python Examples Separately | Accepted | Architecture | 2026-04-10 |
| 0049 | Multi-Protocol Virtual Servers | Accepted | Architecture | 2026-04-16 |
| 0050 | Defer Generic Cluster-Wide Settings Propagation Framework | Accepted | Architecture | 2026-04-18 |
| 0051 | Swappable MCP Ingress Mount | Accepted | Architecture | 2026-04-18 |
| 0052 | GET /mcp Stream and Server-Initiated Request Correlation | Proposed | MCP Protocol | 2026-04-19 |
✳️ Add new decisions chronologically and link to them from this table.