From ee97583e02c03cc21f7df8ec2451e7034f76eebd Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Wed, 13 May 2026 13:54:26 -0300 Subject: [PATCH] docs: link Mermaid diagrams from 8 architecture/framework docs Wire the new docs/diagrams/exported/*.svg into the documents that already describe each flow, with the .mmd source linked alongside so edits stay auditable: - CLAUDE.md resilience-3layers - docs/ARCHITECTURE.md request-pipeline + resilience-3layers - docs/AUTO-COMBO.md auto-combo-9factor - docs/RESILIENCE_GUIDE.md resilience-3layers - docs/I18N.md i18n-flow - docs/MCP-SERVER.md mcp-tools-37 - docs/CLOUD_AGENT.md cloud-agent-flow - docs/AUTHZ_GUIDE.md authz-pipeline - docs/CODEBASE_DOCUMENTATION.md request-pipeline + db-schema-overview Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 5 ++++- docs/ARCHITECTURE.md | 15 +++++++++++++++ docs/AUTHZ_GUIDE.md | 4 ++++ docs/AUTO-COMBO.md | 4 ++++ docs/CLOUD_AGENT.md | 4 ++++ docs/CODEBASE_DOCUMENTATION.md | 8 ++++++++ docs/I18N.md | 4 ++++ docs/MCP-SERVER.md | 4 ++++ docs/RESILIENCE_GUIDE.md | 4 ++++ 9 files changed, 51 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3c96cb643f..8e13ad6f6c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,7 +79,10 @@ API routes follow a consistent pattern: `Route → CORS preflight → Zod body v ## Resilience Runtime State OmniRoute has three related but distinct temporary-failure mechanisms. Keep their -scope separate when debugging routing behavior. +scope separate when debugging routing behavior. See the +[3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg) +(source: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)) +for an at-a-glance map. ### Provider Circuit Breaker diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 719c530dcd..e3880b477a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -78,6 +78,21 @@ Primary runtime model: - Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs - A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage +## Reference Diagrams + +Canonical, version-controlled Mermaid sources for the v3.8.0 platform live in +[`docs/diagrams/`](./diagrams/README.md). Two are reproduced below for orientation; +the rest are linked from their domain-specific guides. + +![Request pipeline (/v1/chat/completions)](./diagrams/exported/request-pipeline.svg) + +> Source: [diagrams/request-pipeline.mmd](./diagrams/request-pipeline.mmd) + +![3-layer resilience model](./diagrams/exported/resilience-3layers.svg) + +> Source: [diagrams/resilience-3layers.mmd](./diagrams/resilience-3layers.mmd) — also linked from +> [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) and the `CLAUDE.md` resilience reference. + ## Scope and Boundaries ### In Scope diff --git a/docs/AUTHZ_GUIDE.md b/docs/AUTHZ_GUIDE.md index 6043be9aa4..b7128a1cee 100644 --- a/docs/AUTHZ_GUIDE.md +++ b/docs/AUTHZ_GUIDE.md @@ -5,6 +5,10 @@ OmniRoute has a route-aware authorization pipeline that gates every API request. Classification is **deterministic** and **fail-closed** — anything that cannot be classified ends up as `MANAGEMENT` and demands a session or management-grade token. This page explains the model for engineers maintaining routes or designing new endpoints. +![AuthZ pipeline (3 route classes + policy evaluation)](./diagrams/exported/authz-pipeline.svg) + +> Source: [diagrams/authz-pipeline.mmd](./diagrams/authz-pipeline.mmd) + ## Two Auth Modes ### 1. API Key (Bearer) diff --git a/docs/AUTO-COMBO.md b/docs/AUTO-COMBO.md index 14421afd6a..a15fd2d756 100644 --- a/docs/AUTO-COMBO.md +++ b/docs/AUTO-COMBO.md @@ -77,6 +77,10 @@ Auto-scoring selects best provider/model per request The Auto-Combo Engine dynamically selects the best provider/model for each request using a **9-factor scoring function** (defined in `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). All weights sum to **1.0**. +![Auto-Combo 9-factor scoring](./diagrams/exported/auto-combo-9factor.svg) + +> Source: [diagrams/auto-combo-9factor.mmd](./diagrams/auto-combo-9factor.mmd) + | Factor | Default Weight | Description | | :----------------- | :------------- | :---------------------------------------------------------------------- | | `health` | 0.22 | Health score from circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) | diff --git a/docs/CLOUD_AGENT.md b/docs/CLOUD_AGENT.md index f0c538284d..5bd7b64575 100644 --- a/docs/CLOUD_AGENT.md +++ b/docs/CLOUD_AGENT.md @@ -12,6 +12,10 @@ A Cloud Agent task is **not** a regular chat completion. It is a durable, multi- unit of work that may take minutes to hours, can produce a Pull Request as its artifact, and supports follow-up messages and (in some providers) plan approval gates. +![Cloud Agent task lifecycle](./diagrams/exported/cloud-agent-flow.svg) + +> Source: [diagrams/cloud-agent-flow.mmd](./diagrams/cloud-agent-flow.mmd) + ## Supported Agents | Provider ID | Class | Source | Upstream Base URL | Plan Approval | diff --git a/docs/CODEBASE_DOCUMENTATION.md b/docs/CODEBASE_DOCUMENTATION.md index bf8bdf5d31..e4d944573d 100644 --- a/docs/CODEBASE_DOCUMENTATION.md +++ b/docs/CODEBASE_DOCUMENTATION.md @@ -286,6 +286,10 @@ Top-level files in `src/lib/`: Singleton SQLite database (`getDbInstance()` in `core.ts`, WAL journaling). **Never write raw SQL in routes or handlers** — go through these modules. +![Database schema overview (selected core tables)](./diagrams/exported/db-schema-overview.svg) + +> Source: [diagrams/db-schema-overview.mmd](./diagrams/db-schema-overview.mmd) + Domain modules (each owns one or more tables): `apiKeys.ts`, `backup.ts`, `batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`, `commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`, @@ -638,6 +642,10 @@ Common commands: ## 9. Request Pipeline (Summary) +![Request pipeline (/v1/chat/completions)](./diagrams/exported/request-pipeline.svg) + +> Source: [diagrams/request-pipeline.mmd](./diagrams/request-pipeline.mmd) + ``` Client request → /v1/chat/completions (route.ts) diff --git a/docs/I18N.md b/docs/I18N.md index 458e5df371..3a6264b86b 100644 --- a/docs/I18N.md +++ b/docs/I18N.md @@ -17,6 +17,10 @@ OmniRoute supports **30 languages** with full dashboard UI translation, translat ## Architecture +![Incremental hash-based i18n pipeline](./diagrams/exported/i18n-flow.svg) + +> Source: [diagrams/i18n-flow.mmd](./diagrams/i18n-flow.mmd) + ### Source of Truth - **UI strings**: `src/i18n/messages/en.json` (English source, ~2800 keys) diff --git a/docs/MCP-SERVER.md b/docs/MCP-SERVER.md index fe91b6bd2e..ee1b87ec55 100644 --- a/docs/MCP-SERVER.md +++ b/docs/MCP-SERVER.md @@ -4,6 +4,10 @@ > > Source of truth: `open-sse/mcp-server/schemas/tools.ts` (30 tools) + `open-sse/mcp-server/tools/memoryTools.ts` (3 tools) + `open-sse/mcp-server/tools/skillTools.ts` (4 tools). Tool registration and scope wiring lives in `open-sse/mcp-server/server.ts`. +![MCP tool inventory (37 tools by category)](./diagrams/exported/mcp-tools-37.svg) + +> Source: [diagrams/mcp-tools-37.mmd](./diagrams/mcp-tools-37.mmd) + ## Installation OmniRoute MCP is built-in. Start it with: diff --git a/docs/RESILIENCE_GUIDE.md b/docs/RESILIENCE_GUIDE.md index 1e630d85d8..085f0b25ae 100644 --- a/docs/RESILIENCE_GUIDE.md +++ b/docs/RESILIENCE_GUIDE.md @@ -2,6 +2,10 @@ OmniRoute has three distinct but related resilience mechanisms. Each has a different scope and purpose. Keep them separate when debugging routing behavior. +![3-layer resilience model](./diagrams/exported/resilience-3layers.svg) + +> Source: [diagrams/resilience-3layers.mmd](./diagrams/resilience-3layers.mmd) + ## 1. Provider Circuit Breaker **Scope:** entire provider (e.g., `glm`, `openai`, `anthropic`).