mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-09-14 02:42:24 +03:00
7d57d9f4a1
Rebased onto the current release/v3.8.51 tip as part of a combined provider-retirement/provenance merge batch (Designer Web, Felo Web, Runtime, GPL-derived removal, Qwen Web already landed). Large conflict set (this is the biggest PR in the batch — the common ChatGPT Web provider touches chat, images, count-tokens, session leases, and combos). Conflicts resolved: - `open-sse/config/providers/registry/chatgpt-web/*`, `open-sse/executors/chatgpt-web*`, `open-sse/handlers/imageGeneration/providers/chatgptWeb.ts`, and their tests: kept deleted, matching the PR's stated scope. - `open-sse/config/providers/registry/minimax/web/index.ts`, `open-sse/handlers/imageGeneration/providers/geminiWeb.ts`, `open-sse/executors/gemini-web.ts`'s stale image-mode branch: base-drift collisions against already-merged sibling retirements (#11691, #11708) — kept deleted / dropped the dead code, since this PR's own branch forked before those merged. - `src/shared/constants/reservedProviderPrefixes.ts`, `open-sse/executors/index.ts`, `executorProxy.ts`, `virtualFactory.ts`, `autoStrategy.ts`, `src/lib/db/providers.ts`, `src/sse/handlers/chat.ts`: combined the Designer + Runtime (Felo/Qwen) + common-ChatGPT-Web retirement guard calls at each shared chokepoint — compute-once-then-OR pattern, consistent with prior combinations in this batch. - `src/sse/services/model.ts` / `src/sse/handlers/chatHelpers.ts`: adopted this PR's new `getModelInfoOrRetirementResponse()` central wrapper (a real improvement over ad-hoc try/catch), and extended it to also catch the Designer + Runtime retirement errors it didn't originally cover, so the consolidation doesn't regress the other two mechanisms. - `src/app/api/v1/images/edits/route.ts`: this PR moved the retirement check earlier (before `enforceApiKeyPolicy`) but left the old later call+catch block in place from base drift — removed the now-redundant duplicate `resolveImageRouteModel()` call and merged the Designer catch into the earlier one. - `open-sse/config/imageRegistry.ts`, `tests/snapshots/executors/executor-map.json` (`keyCount` recomputed to 133), `tests/snapshots/provider/translate-path.json`: same "both sides inserted a different retired provider at the same slot" pattern — resolved by dropping both. - `tests/unit/chatcore-executor-proxy.test.ts`, `provider-node-reserved-prefix.test.ts`, `combo-auto-candidate-expansion.test.ts`, `messages-count-tokens-route.test.ts`, `virtual-auto-combo.test.ts`: split into independent per-mechanism test blocks (established pattern); `virtual-auto-combo.test.ts`'s old "includes cookie web-session providers" positive-inclusion test (which used chatgpt-web as its example) was retired along with the provider and replaced by this PR's negative-exclusion test for the same slot. - `docs/architecture/ARCHITECTURE.md`, `CODEBASE_DOCUMENTATION.md` (+ 4 i18n mirrors), `README.md`, `FREE-TIERS-GUIDE.md`, `docs/diagrams/free-tier-budget.svg`, `docs/screenshots/free-tier-budget-card.svg`, `docs/reference/PROVIDER_REFERENCE.md`: recomputed every stale count from the real merged state — 104 executors (`countFiles` gate logic), 351 providers (regenerated via `gen:provider-reference`), 152/351 `hasFree` entries, 445/438/7 free-tier catalog rows, 13 ToS-avoid providers, budget-card regenerated via its real generator script. One doc conflict (`oauth/` module list) needed picking HEAD's side specifically — theirs still listed the already-removed `raycast` module instead of the real `openference`. - `config/quality/test-masking-allowlist.json`: additive merge of the PR's 17 `_deletedWithReplacement` entries alongside the batch's existing ones (one real duplicate-key mistake in my first pass, caught and fixed via a `object_pairs_hook` duplicate-key check before finalizing). Also fixed two real, unrelated-to-my-merge issues surfaced by the focused suite: - `tests/unit/resolve-web-provider-host.test.ts`: the PR's own test had a typo — it asserted `perplexity-web`'s resolved host as `"perplexity.ai"`, but the provider's registered `website` is `"https://www.perplexity.ai"` and the resolver returns the URL's `host` verbatim (no www-stripping), so the correct value is `"www.perplexity.ai"` (consistent with the same test's own `url` assertion). - `tests/unit/hard-session-lease-bypass-inventory.test.ts`: this golden call-site inventory was already stale on the pristine post-#11713 tip (confirmed via a throwaway probe worktree) — `src/lib/db/providers.ts`'s 3 connection-fallback sites and a third `src/app/api/providers/route.ts` site were never added to the golden list by the earlier-merged #11698/#11720 PRs. Updated it to the real current inventory (dated inline comments explain each delta and which PR introduced it), plus this PR's own legitimate deltas (image-edits duplicate-call removal, `ChatGptWebExecutor.execute()` site removed). Focused suite green (433/433 across executor-proxy, reserved-prefix, hard-session-lease-bypass-inventory, resolve-web-provider-host, retirement/runtime-block/source-retirement/management-retirement/image-handler-retirement, migration-168, combo-auto-candidate-expansion, virtual-auto-combo, executor-map-golden and siblings), plus `typecheck:core`, `check-file-size`, and `check-changelog-integrity` clean. Thanks for the thorough provenance-hold retirement work — appreciated.
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| Diagrams | 3.8.49 | 2026-07-17 |
Diagrams
Mermaid sources (.mmd) and exported SVGs for OmniRoute v3.8.0 architecture flows.
Canonical diagrams
| Source | Exported | Used in |
|---|---|---|
| request-pipeline.mmd | SVG | docs/architecture/ARCHITECTURE.md, docs/architecture/CODEBASE_DOCUMENTATION.md |
| auto-combo-12factor.mmd | SVG | docs/routing/AUTO-COMBO.md |
| resilience-3layers.mmd | SVG | docs/architecture/RESILIENCE_GUIDE.md, CLAUDE.md |
| i18n-flow.mmd | SVG | docs/guides/I18N.md |
| mcp-tools-107.mmd | SVG | docs/frameworks/MCP-SERVER.md |
| cloud-agent-flow.mmd | SVG | docs/frameworks/CLOUD_AGENT.md |
| authz-pipeline.mmd | SVG | docs/architecture/AUTHZ_GUIDE.md |
| db-schema-overview.mmd | SVG | docs/architecture/CODEBASE_DOCUMENTATION.md |
Hand-authored animated diagrams
Not every diagram comes from a .mmd source. Hand-authored SVGs live at this
directory's root and animate with SMIL only (no JS, no external fonts), so they play
inside GitHub's <img> sandbox:
| File | Used in | Notes |
|---|---|---|
| tier-cascade.svg | README.md (root) | Animated 4-tier auto-fallback cascade (16s loop, 4 acts). Edit the SVG directly — there is no .mmd source. |
| pool-fair-share.svg | README.md (root) | Animated key-pool fair-share quota (generous → strict, 16s loop). Edit the SVG directly — there is no .mmd source. |
| combo-always-on.svg | style reference | Animated priority-combo fallback (4 layers, 16s loop). Edit the SVG directly — there is no .mmd source. |
| cli-terminal.svg | README.md (root) | Compact half-height animated terminal (1200×350): 3 real CLI commands cycling with typewriter + scrolling subcommand ticker; first frame = completed providers screen. Edit the SVG directly — there is no .mmd source. |
| compression-pipeline.svg | README.md (root) | Animated 10-engine compression funnel (8s loop). Edit the SVG directly — there is no .mmd source. |
| free-tier-budget.svg | README.md (root) | Animated free-tier budget card (~1.51B/mo quantified headline, 20-pool budget bar, per-pool grid, signup credits, 10s loop). Edit the SVG directly — there is no .mmd source. |
| readme-hero.svg | README.md (root) | Animated hero card (tagline, live provider/free-access headline, full-width compression bar demo, 6 stat chips). Edit the SVG directly — there is no .mmd source. |
| promise-pillars.svg | README.md (root) | Animated "The Promise" 6-pillar card (12s border-highlight sweep). Edit the SVG directly — there is no .mmd source. |
| why-pain-fix.svg | README.md (root) | Animated "Why OmniRoute" 10-row pain-vs-fix ledger (15s green row sweep). Edit the SVG directly — there is no .mmd source. |
| strategies-grid.svg | README.md (root) | Animated grid illustrating 18 of the 19 routing strategies; cache-optimized remains documented in the adjacent table. Edit the SVG directly — there is no .mmd source. |
| privacy-local.svg | README.md (root) | Animated "Private & Local-First" 11-row guarantee ledger with receipt chips (16s green row sweep). Edit the SVG directly — there is no .mmd source. |
| resilience-layers.svg | README.md (root) | Animated 3-layer resilience card (breaker states CLOSED→OPEN→HALF-OPEN, key cooldown with ×2 backoff, model lockout — 18s loops). Edit the SVG directly — there is no .mmd source. |
How to update
- Edit
*.mmd. - Re-render:
npm run docs:render-diagrams(uses@mermaid-js/mermaid-cli). - Commit both
.mmdand.svg.
If @mermaid-js/mermaid-cli is not available locally, install it once:
npm install -g @mermaid-js/mermaid-cli
The script renders every .mmd in docs/diagrams/ into docs/diagrams/exported/*.svg
with a white background, suitable for both dark and light themes.
Linking from a doc
From a doc in docs/<subfolder>/, the relative path becomes ../diagrams/...:
> Source: [../diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)
From the repo root (e.g. CLAUDE.md):
Conventions
- One concept per diagram. Don't try to fit the whole platform in one chart.
- Keep node labels short (3-6 words). Use
<br/>for line breaks inside nodes. - Prefer
flowchart LRfor pipelines andflowchart TBfor layered models. - Use
sequenceDiagramfor interactive (request/response) flows. - Use
erDiagramfor database schema overviews. - Update both
.mmdand.svgin the same commit. Keep them in lock-step.