# OmniRoute Architecture (Eesti)

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇪🇹 [am](../../../am/docs/architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇧🇦 [bs](../../../bs/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ARCHITECTURE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/architecture/ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ARCHITECTURE.md)

---

# OmniRoute Arhitektuur

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇪🇹 [am](../../../am/docs/architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇦🇿 [az](../../../az/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇧🇦 [bs](../../../bs/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇬🇷 [el](../../../el/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇪 [ga](../../../ga/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ha](../../../ha/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇷 [hr](../../../hr/docs/architecture/ARCHITECTURE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ARCHITECTURE.md) · 🇦🇲 [hy](../../../hy/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [ig](../../../ig/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇬🇪 [ka](../../../ka/docs/architecture/ARCHITECTURE.md) · 🇰🇭 [km](../../../km/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [kn](../../../kn/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇱🇹 [lt](../../../lt/docs/architecture/ARCHITECTURE.md) · 🇱🇻 [lv](../../../lv/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ml](../../../ml/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇲🇹 [mt](../../../mt/docs/architecture/ARCHITECTURE.md) · 🇲🇲 [my](../../../my/docs/architecture/ARCHITECTURE.md) · 🇳🇵 [ne](../../../ne/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [or](../../../or/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [pa](../../../pa/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇱🇰 [si](../../../si/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇮 [sl](../../../sl/docs/architecture/ARCHITECTURE.md) · 🇷🇸 [sr](../../../sr/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇺🇿 [uz](../../../uz/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇳🇬 [yo](../../../yo/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/ARCHITECTURE.md)

_Viimati uuendatud: 2026-06-28_

## Kokkuvõte

OmniRoute on kohalik AI marsruutimise lüüs ja armatuurlaud, mis on ehitatud Next.js. See pakub ühtset OpenAI-ga ühilduvat lõpp-punkti (`/v1/*`) ja suunab liiklust mitme ülesvoolu pakkuja vahel koos tõlke, varu, loa värskendamise ja kasutamise jälgimisega.

Põhilised võimalused:

- OpenAI-ga ühilduv API pind CLI/tools jaoks (381 pakkujat, 159 täitjamoodulit)
- Request/response tõlge teenusepakkuja vormingute vahel
- Mudeli kombineeritud varu (mitme mudeli jada)
- Struktureeritud kombineeritud sammud (`provider + model + connection`) koos käitusaja järjestamisega `compositeTiers` järgi
- Kontotaseme varu (mitu kontot pakkuja kohta)
- Kvoodi eelkontrolli ja kvooditeadlik P2C konto valik põhivestluse teel
- OAuth + API-võtme pakkuja ühenduse haldus (27 OAuth pakkuja moodulit)
- Genereerimise manustamine `/v1/embeddings` kaudu (18 pakkujat)
- Pildi genereerimine `/v1/images/generations` kaudu (10 + pakkujat, 20 + mudelit)
- Heli transkriptsioon `/v1/audio/transcriptions` kaudu (18 pakkujat)
- Tekst kõneks `/v1/audio/speech` kaudu (24 sisseehitatud pakkujat)
- Video genereerimine `/v1/videos/generations` kaudu (ComfyUI + SD WebUI)
- Muusika genereerimine `/v1/music/generations` kaudu (ComfyUI)
- Veebiotsing `/v1/search` kaudu (20 pakkujat)
- Modereerimine `/v1/moderations` kaudu
- Ümberpaigutamine `/v1/rerank` kaudu
- Mõelge arutlusmudelite jaoks sildi sõelumisele (`<think>...</think>`).
- Reaktsioonide desinfitseerimine range OpenAI SDK ühilduvuse tagamiseks
- Rollide normaliseerimine (arendaja → süsteem, süsteemi → kasutaja) pakkujatevahelise ühilduvuse tagamiseks
- Struktureeritud väljundi teisendamine (json_schema → Gemini responseSchema)
- Pakkujate, võtmete, varjunimede, kombinatsioonide, seadete, hinnakujunduse kohalik püsivus (122 DB moodulit)
- Usage/cost jälgimine ja taotluste logimine
- Valikuline pilvesünkroonimine multi-device/state sünkroonimiseks
- IP allowlist/blocklist API juurdepääsu juhtimiseks
- Mõtlev eelarvejuhtimine (passthrough/auto/custom/adaptive)
- Globaalne süsteemi kiire süstimine
- Seansi jälgimine ja sõrmejälgede võtmine
- Kontopõhine täiustatud tariifipiirang teenusepakkujapõhiste profiilidega
- Kaitselüliti muster pakkuja vastupidavuse tagamiseks
- Äikesevastane karjakaitse mutex-lukuga
- Allkirjapõhine päringu deduplikatsiooni vahemälu
- Domeenikiht: kulureeglid, varupoliitika, sulgemispoliitika
- Konteksti edastamine: seansi üleandmise kokkuvõtted konto vaheldumise järjepidevuse jaoks
- Domeeni oleku püsivus (SQLite läbikirjutamise vahemälu varude, eelarvete, lukustuste, kaitselülitite jaoks)
- Tsentraliseeritud taotluste hindamise poliitikamootor (lockout → budget → backback)
- Taotlege telemeetriat p50/p95/p99 latentsusagregatsiooniga
- Kombineeritud sihtmärgi telemeetria ja ajalooline kombineeritud sihtmärk tervise `combo_execution_key` / `combo_step_id` kaudu
- Korrelatsioon ID (X-Request-Id) otsast lõpuni jälgimiseks
- Vastavusauditi logimine loobumisega API võtme kohta
- Eval raamistik LLM kvaliteedi tagamiseks
- Tervise armatuurlaud reaalajas teenusepakkuja kaitselüliti olekuga
- MCP server (110 tööriista) 3 transpordiga (stdio/SSE/Streamable HTTP)
- A2A server (JSON-RPC 2.0 + SSE) oskuste ja ülesannete elutsükliga
- Mälusüsteem (väljavõte, süstimine, otsimine, kokkuvõte)
- Oskuste süsteem (register, täitja, liivakast, sisseehitatud oskused)
- MITM puhverserver sertifikaadihalduse ja DNS -käsitlusega
- Kiire süstimiskaitse vahevara
- Kiire tihenduskonveier Cavemani, RTK, virnastatud konveierite, tihenduskombode, keelepakettide ja analüütikaga
- ACP (Agent Communication Protocol) register
- Modulaarsed OAuth pakkujad (22 individuaalset moodulit `src/lib/oauth/providers/` all)
- Uninstall/full-uninstall skriptid
- OAuth keskkonna parandamise tegevus
- WebSocket sild OpenAI-ga ühilduvatele WS klientidele (`/v1/ws`)
- Sünkroonimisloa haldus (issue/revoke, ETag-versiooniga konfiguratsioonipaketi allalaadimine)
- GLM Thinking (`glmt`) esmaklassiline pakkuja eelseadistus
- Hübriidlubade loendamine (pakkujapoolne `/messages/count_tokens` koos hinnangu tagavaraga)
- Mudeli aliase automaatne külvamine (30 + puhverserveriülese dialekti normaliseerimine käivitamisel)
- Ohutu väljaminev toomine SSRF valvega, privaatne URL blokeerimine ja konfigureeritav uuesti proovimine
- Jahtumisteadlik vestluse korduskatsed konfigureeritavate `requestRetry` ja `maxRetryIntervalSec` abil
- Käituskeskkonna valideerimine Zod käivitamisel
- Vastavusaudit v2 koos lehekülgede, pakkuja CRUD sündmuste ja SSRF-blokeeritud valideerimise logimisega

Esmane käitusaegne mudel:

- Next.js rakenduse marsruudid `src/app/api/*` all rakendavad nii armatuurlaua APIs kui ka ühilduvus APIs
- Jagatud SSE/routing tuum rakenduses `src/sse/*` + `open-sse/*` haldab teenusepakkuja täitmist, tõlkimist, voogesitust, varundust ja kasutamist

## Viitediagrammid

Kanoonilised, versioonihaldusega Mermaid lähtekoodid v3.8.0 platvormi jaoks asuvad
kaustas [`docs/diagrams/`](../diagrams/README.md). Allpool on toodud kaks näidet suunamiseks;
ülejäänud on lingitud vastavatest valdkonnaspetsiifilistest juhenditest.

![Päringu töövoog (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Allikas: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

> Allikas: [diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd) — samuti lingitud
> juhendist [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) ja `CLAUDE.md` vastupidavuse viitest.

## Ulatus ja piirid

### Kuulub ulatusse

- Kohalik gateway käitusaeg (runtime)
- Töölaua (dashboard) haldus-API-d
- Teenusepakkuja autentimine ja tokeni värskendamine
- Päringute teisendamine ja SSE voogedastus
- Kohalik olek + kasutuse säilitamine
- Valikuline pilvesünkroonimise orkestreerimine

### Ei kuulu ulatusse

- Pilveteenuse implementatsioon `NEXT_PUBLIC_CLOUD_URL` taga
- Teenusepakkuja SLA/juhtimistasand väljaspool kohalikku protsessi
- Välised CLI binaarfailid (Claude CLI, Codex CLI, jne)

## Juhtpaneeli vaated (praegused)

Peamised lehed kataloogis `src/app/(dashboard)/dashboard/`:

- `/dashboard` — kiirkäivitus ja teenusepakkujate ülevaade
- `/dashboard/endpoint` — lõpp-punkti puhverserveri ning MCP, A2A ja API lõpp-punktide vahekaardid
- `/dashboard/providers` — teenusepakkujate ühendused ja pääsuandmed
- `/dashboard/combos` — kombinatsioonistrateegiad, mallid, sammupõhine koostur, mudelite marsruutimisreeglid ja käsitsi määratud püsiv järjestus
- `/dashboard/auto-combo` — automaatne kombinatsioonimootor: hindamiskaalud, režiimipaketid, virtuaalse tehase eelseadistused ja telemeetria
- `/dashboard/costs` — kulude koondamine ja hinnastuse nähtavus
- `/dashboard/analytics` — kasutusanalüütika, hindamised ja kombinatsiooni sihtmärkide seisund
- `/dashboard/limits` — kvoodi- ja kiirusepiirangud
- `/dashboard/cli-tools` — CLI kasutuselevõtt, käituskeskkonna tuvastamine ja konfiguratsiooni genereerimine
- `/dashboard/agents` — tuvastatud ACP agendid ja kohandatud agentide registreerimine
- `/dashboard/cloud-agents` — pilves majutatud agentide ülesanded (Codex Cloud, Devin, Jules) ja ülesannete elutsükkel
- `/dashboard/skills` — A2A oskuste register, isoleeritud keskkonnas käitamine ja sisseehitatud oskuste kataloog
- `/dashboard/memory` — püsiva vestlusmälu uurimine ja sealt teabe hankimine
- `/dashboard/webhooks` — väljaminevate veebihaakide tellimused, saladuste roteerimine ja korduskatsete statistika
- `/dashboard/batch` — pakktööde esitamine ja edenemine
- `/dashboard/cache` — läbiloetava ja arutluskäigu vahemälu statistika ning eemaldamise juhtelemendid
- `/dashboard/playground` — interaktiivne vestluse katsekeskkond mis tahes konfigureeritud kombinatsiooni või mudeli jaoks
- `/dashboard/changelog` — rakendusesisene muudatuste logi vaatur (renderdab faili `CHANGELOG.md`)
- `/dashboard/system` — käituskeskkonna diagnostika, versiooniteave ja keskkonna valideerimise vaade
- `/dashboard/onboarding` — uute paigalduste esmase seadistamise viisard
- `/dashboard/media` — piltide, videote ja muusika katsekeskkond
- `/dashboard/search-tools` — otsinguteenuse pakkujate testimine ja ajalugu
- `/dashboard/health` — töövõimeaeg, kaitselülitid, kiirusepiirangud ja kvoodijälgimisega seansid
- `/dashboard/logs` — päringu-, puhverserveri-, auditi- ja konsoolilogid
- `/dashboard/settings` — süsteemiseadete vahekaardid (üldine, marsruutimine, kombinatsioonide vaikeväärtused jne)
- `/dashboard/context/caveman` — Cavemani tihendusreeglid, keelepaketid, eelvaade ja väljundrežiim
- `/dashboard/context/rtk` — RTK käsuväljundi filtrid, eelvaade ja käituskeskkonna ohutusseaded
- `/dashboard/context/combos` — nimega tihenduskonveierid, mis on määratud marsruutimiskombinatsioonidele
- `/dashboard/translator` — tõlkija uurimine ja päringuvormingu teisendamise eelvaade
- `/dashboard/audit` — lehekülgjaotuse ja struktureeritud metaandmetega vastavusauditi logi brauser
- `/dashboard/usage` — üksikpäringute kasutusandmete brauser, mis on seotud tabeliga `usage_history`
- `/dashboard/compression` — tihendusanalüütika, statistika ja konveierite määramine
- `/dashboard/api-manager` — API võtmete elutsükkel ja mudelite õigused

Kasutajaliidese kiht: iga leht renderdatakse ühes kestas — `src/app/(dashboard)/layout.tsx` →
`src/shared/components/layouts/DashboardLayout.tsx` → `DashboardShell.tsx` (komplekti
`SidebarProvider`/`SidebarInset` ning OmniRoute'i `Sidebar.tsx` ja `Header.tsx`). Lehed impordivad oma
koosteplokid moodulist `@/shared/components` (projekti kaasatud Keak CI UI Kiti adapterid kataloogis
`packages/ui-kit`) või komplekti komponentide alamteedelt (`@omniroute/ui-kit/table`, `…/page-header`) ning
ikoone komponendi `<Icon>` kaudu (`ICON_MAP` → Lucide). Teema (vaikimisi `system`, hele/tume) ja tõendid pärinevad
komplektist faili `src/app/globals.css` silla kaudu. Üksikasjad: `docs/architecture/DESIGN_SYSTEM.md`.

## Kõrgetasemeline süsteemikontekst

```mermaid
flowchart LR
    subgraph Clients[Arendajate kliendid]
        C1[Claude Code]
        C2[Codex CLI]
        C3[OpenClaw / Droid / Cline / Continue / Roo]
        C4[Kohandatud OpenAI-ühilduvad kliendid]
        BROWSER[Brauseri töölaud]
    end

    subgraph Router[OmniRoute kohalik protsess]
        API[V1 ühilduvuse API\n/v1/*]
        DASH[Töölaud + haldus-API\n/api/*]
        CORE[SSE + tõlketuum\nopen-sse + src/sse]
        DB[(storage.sqlite)]
        UDB[(kasutustabelid + logiartefaktid)]
    end

    subgraph Upstreams[Ülemvoolu pakkujad]
        P1[OAuth pakkujad\nClaude/Codex/Gemini/Qoder/GitHub/Kiro/Cursor/Antigravity]
        P2[API-võtme pakkujad\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
        P3[Ühilduvad sõlmed\nOpenAI-ühilduv / Anthropic-ühilduv]
    end

    subgraph Cloud[Valikuline pilvesünkroonimine]
        CLOUD[Pilvesünkroonimise lõpp-punkt\nNEXT_PUBLIC_CLOUD_URL]
    end

    C1 --> API
    C2 --> API
    C3 --> API
    C4 --> API
    BROWSER --> DASH

    API --> CORE
    DASH --> DB
    CORE --> DB
    CORE --> UDB

    CORE --> P1
    CORE --> P2
    CORE --> P3

    DASH --> CLOUD
```

## Peamised käitusaja komponendid

## 1) API ja ruutimiskiht (Next.js App Routes)

Peamised kataloogid:

- `src/app/api/v1/*` ja `src/app/api/v1beta/*` ühilduvus-API-de jaoks
- `src/app/api/*` haldus-/konfiguratsiooni-API-de jaoks
- Next'i ümbersuunamised failis `next.config.mjs`, mis kaardistavad `/v1/*` teele `/api/v1/*`

Olulised ühilduvusruutid:

- `src/app/api/v1/chat/completions/route.ts`
- `src/app/api/v1/messages/route.ts`
- `src/app/api/v1/responses/route.ts`
- `src/app/api/v1/models/route.ts` — sisaldab kohandatud mudeleid koos `custom: true`
- `src/app/api/v1/embeddings/route.ts` — manuste (embeddings) genereerimine (6 pakkujat)
- `src/app/api/v1/images/generations/route.ts` — pildigenereerimine (4+ pakkujat, sh Antigravity/Nebius)
- `src/app/api/v1/messages/count_tokens/route.ts`
- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — pakkuja-spetsiifiline vestlus
- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — pakkuja-spetsiifilised manused
- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — pakkuja-spetsiifilised pildid
- `src/app/api/v1beta/models/route.ts`
- `src/app/api/v1beta/models/[...path]/route.ts`

Haldusdomeenid:

- Autentimine/seaded: `src/app/api/auth/*`, `src/app/api/settings/*`
- Pakkujad/ühendused: `src/app/api/providers*`
- Pakkuja sõlmed: `src/app/api/provider-nodes*`
- Kohandatud mudelid: `src/app/api/provider-models` (GET/POST/DELETE)
- Mudelikataloog: `src/app/api/models/route.ts` (GET)
- Puhverserveri (proxy) konfiguratsioon: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
- OAuth: `src/app/api/oauth/*`
- Võtmed/aliased/kombod/hinnastamine: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
- Kasutus: `src/app/api/usage/*`
- Sünkroonimine/pilv: `src/app/api/sync/*`, `src/app/api/cloud/*`
- CLI tööriistade abistajad: `src/app/api/cli-tools/*`
- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT)
- Mõtlemiseelarve: `src/app/api/settings/thinking-budget` (GET/PUT)
- Süsteemipromt: `src/app/api/settings/system-prompt` (GET/PUT)
- Tihendamine: `src/app/api/settings/compression`, `src/app/api/compression/*`, ja
  `src/app/api/context/*`
- Sessioonid: `src/app/api/sessions` (GET)
- Kiirusepiirangud: `src/app/api/rate-limits` (GET)
- Vastupidavus: `src/app/api/resilience` (GET/PATCH) — päringute järjekord, ühenduse jahutusaeg, pakkuja katkestaja (breaker), jahutusaja ootekonfiguratsioon
- Vastupidavuse taastamine: `src/app/api/resilience/reset` (POST) — pakkuja katkestajate lähtestamine
- Vahemälu statistika: `src/app/api/cache/stats` (GET/DELETE)
- Telemeetria: `src/app/api/telemetry/summary` (GET)
- Eelarve: `src/app/api/usage/budget` (GET/POST)
- Varuahelad (fallback chains): `src/app/api/fallback/chains` (GET/POST/DELETE)
- Vastavuse auditeerimine: `src/app/api/compliance/audit-log` (GET, koos lehestamise ja struktureeritud metaandmetega)
- Hindamised (evals): `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
- Poliitikad: `src/app/api/policies` (GET/POST)
- Sünkroonimise märgid (tokens): `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)
- Konfiguratsioonipakett: `src/app/api/sync/bundle` (GET, ETag-versiooniga seadete/pakkujate/kombode/võtmete hetktõmmis)
- WebSocket: `src/app/api/v1/ws/route.ts` — uuenduskäsitleja (Upgrade handler) OpenAI-ühilduvatele WS klientidele

## 2) SSE + tõlketuum

Põhivoo moodulid:

- Sisenemispunkt: `src/sse/handlers/chat.ts`
- Põhivoo orkestreerimine: `open-sse/handlers/chatCore.ts`
- Pakkuja käivitamise adapterid: `open-sse/executors/*`
- Vormingu tuvastamine / pakkuja konfiguratsioon: `open-sse/services/provider.ts`
- Mudeli parsimine / lahendamine: `src/sse/services/model.ts`, `open-sse/services/model.ts`
- Konto varuvariandi loogika: `open-sse/services/accountFallback.ts`
- Tõlkeregister: `open-sse/translator/index.ts`
- Voo teisendused: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
- Kasutusandmete eraldamine / normaliseerimine: `open-sse/utils/usageTracking.ts`
- Mõtlemissildi parser: `open-sse/utils/thinkTagParser.ts`
- Manustamispäringu töötleja: `open-sse/handlers/embeddings.ts`
- Manustamispakkujate register: `open-sse/config/embeddingRegistry.ts`
- Pildiloome töötleja: `open-sse/handlers/imageGeneration.ts`
- Pildipakkujate register: `open-sse/config/imageRegistry.ts`
- Vastuse puhastamine: `open-sse/handlers/responseSanitizer.ts`
- Rollide normaliseerimine: `open-sse/services/roleNormalizer.ts`

Teenused (äriloogika):

- Kontode valimine / hindamine: `open-sse/services/accountSelector.ts`
- Konteksti elutsükli haldus: `open-sse/services/contextManager.ts`
- IP-filtri jõustamine: `open-sse/services/ipFilter.ts`
- Seansside jälgimine: `open-sse/services/sessionManager.ts`
- Päringute duplikaatide eemaldamine: `open-sse/services/signatureCache.ts`
- Süsteemiviiba sisestamine: `open-sse/services/systemPrompt.ts`
- Mõtlemiseelarve haldus: `open-sse/services/thinkingBudget.ts`
- Metamärkidega mudelite marsruutimine: `open-sse/services/wildcardRouter.ts`
- Päringusageduse piirangute haldus: `open-sse/services/rateLimitManager.ts`
- Kaitselüliti: `src/shared/utils/circuitBreaker.ts`
- Konteksti üleandmine: `open-sse/services/contextHandoff.ts` — üleandmise kokkuvõtte genereerimine ja sisestamine konteksti edastamise strateegia jaoks
- Tihendamine: `open-sse/services/compression/*` — ennetav tihendamine enne pakkujale tõlkimist;
  hõlmab Cavemani reegleid, RTK-filtreid, virnastatud konveiereid, tihenduskombinatsioone, statistikat ja valideerimist
- Codexi kvoodi hankija: `open-sse/services/codexQuotaFetcher.ts` — hangib Codexi kvoodi konteksti edastamise üleandmisotsuste jaoks
- Jahtumisaega arvestav korduskatse: `src/sse/services/cooldownAwareRetry.ts` — mudelipõhised jahtumisaja korduskatsed seadistatavate väärtustega `requestRetry` / `maxRetryIntervalSec`
- Turvaline väljaminev päring: `src/shared/network/safeOutboundFetch.ts` — kaitstud pakkuja-/mudelipäring SSRF-kaitse, privaatsete URL-ide blokeerimise, korduskatsete ja ajalõpuga
- Väljaminevate URL-ide kaitse: `src/shared/network/outboundUrlGuard.ts` — pakkujate URL-ide hostikontrollid; `src/shared/network/outboundUrlGuardPolicy.ts` valib režiimi muutujate `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS`, `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` ja nende töölaual olevate lülitite põhjal (vt `docs/reference/ENVIRONMENT.md`)
- Pakkuja päringute vaikeväärtused: `open-sse/services/providerRequestDefaults.ts` — pakkuja taseme `maxTokens`, `temperature`, `thinkingBudgetTokens` vaikeväärtused
- GLM-i pakkuja konstandid: `open-sse/config/glmProvider.ts` — jagatud GLM-i mudelid, kvoodi-URL-id ning GLMT ajalõpp/vaikeväärtused
- Antigravity ülesvool: `open-sse/config/antigravityUpstream.ts` — baas-URL-i ja tuvastustee konstandid
- Codexi kliendi konstandid: `open-sse/config/codexClient.ts` — versioonitud kasutajaagendi ja kliendiversiooni väärtused
- Mudelialiaste algandmed: `src/lib/modelAliasSeed.ts` — lisab käivitamisel üle 30 puhverserveriülest dialektialiase

Domeenikihi moodulid:

- Kulureeglid / eelarved: `src/domain/costRules.ts`
- Varuvariandi poliitika: `src/domain/fallbackPolicy.ts`
- Kombinatsioonide lahendaja: `src/domain/comboResolver.ts`
- Lukustuspoliitika: `src/domain/lockoutPolicy.ts`
- Poliitikamootor: `src/domain/policyEngine.ts` — tsentraliseeritud lukustuse → eelarve → varuvariandi hindamine
- Veakoodide kataloog: `src/shared/constants/errorCodes.ts`
- Päringu ID: `src/shared/utils/requestId.ts`
- Päringu ajalõpp: `src/shared/utils/fetchTimeout.ts`
- Päringu telemeetria: `src/shared/utils/requestTelemetry.ts`
- Vastavus / audit: `src/lib/compliance/index.ts`
- Hindamiste käitaja: `src/lib/evals/evalRunner.ts`
- Domeenioleku püsisalvestus: `src/lib/db/domainState.ts` — SQLite CRUD varuahelate, eelarvete, kuluajaloo, lukustusoleku ja kaitselülitite jaoks

OAuth-pakkujate moodulid (27 eraldi faili kataloogis `src/lib/oauth/providers/`):

- Registri indeks: `src/lib/oauth/providers/index.ts`
- Üksikud pakkujad: `agy.ts`, `antigravity.ts`, `claude.ts`, `cline.ts`, `codebuddy-cn.ts`, `codebuddy-intl.ts`, `codex.ts`, `cursor.ts`, `devin-desktop.ts`, `ghe-copilot.ts`, `github.ts`, `gitlab-duo.ts`, `grok-cli-oauth.ts`, `grok-cli.ts`, `kilocode.ts`, `kimi-coding.ts`, `kiro.ts`, `muse-code.ts`, `openference.ts`, `qoder.ts`, `trae.ts`, `workbuddy.ts`, `xai-oauth.ts`, `zed-hosted.ts`, `zed.ts`
- Jagatud abifunktsioonid: `codebuddyDeviceAuth.ts` (CodeBuddy CN/intl seadmevoog), `museCodeDeviceResponse.ts`
- Õhuke ümbris: `src/lib/oauth/providers.ts` — reekspordib üksikutest moodulitest

## 5) Manustatud teenused (v3.8.4)

OmniRoute saab paigaldada, jälgida ja marsruutida kohalikult töötavatesse AI tööriistade protsessidesse, mida nimetatakse **manustatud teenusteks** (embedded services). Tarnitakse viit: 9Router, CLIProxyAPI, Bifrost, Mux ja Dario.

Arhitektuuri kihid:

- **UI** (`/dashboard/providers/services`) — kahe vahekaardiga leht elutsükli juhtelementidega,
  live logivooga, API võtmete haldusega ja (9Routeri jaoks) manustatud native UI-ga läbi
  sisemise pöördproksi (reverse proxy).
- **API** (`/api/services/{name}/*`) — 11 lõpp-punkti 9Routerile, 10 CLIProxyAPI-le, 8 igale Bifrost / Mux / Dario jaoks,
  kõik klassifitseeritud kui **LOCAL_ONLY** (kõva reegel #17). Jagatud `GET /api/services/[name]/logs`
  SSE lõpp-punkt teenindab mõlemat teenust.
- **Superviisor** (`src/lib/services/`) — üldine `ServiceSupervisor` klass mähib
  `child_process.spawn`-i, hoiab 5 MB ringpuhvrit SSE logivoo jaoks, tervisekontrolli
  tsüklit, atomaarset toimingulukku ja SIGTERM→SIGKILL sujuvat väljalülitust.
  `bootstrap.ts` seob kõik konfigureeritud teenused protsessi käivitumisel.
- **Provider/täitur** (`open-sse/executors/ninerouter.ts`) — 9Router on eksponeeritud
  päris teenusepakkujana. Mudelitel on eesliide `9router/{sub}/{model}` ja need sünkroonitakse
  iga 5 min tagant 9Routeri `/v1/models` lõpp-punktist.

Süvaanalüüs: `docs/frameworks/EMBEDDED-SERVICES.md`

## Peamised alamsüsteemid (v3.8.0)

### A. Automaatne kombineeritud mootor

Automaatne kombineerimine hindab ja valib dünaamiliselt marsruutimise sihtmärke päringu ajal, selle asemel, et tugineda staatilisele kombineeritud määratlusele. See juhib `auto/*` mudeli eesliidete perekonda.

- Mootori sisestus: `open-sse/services/autoCombo/` (`autoComboEngine.ts`, `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)
- Lahendus: `src/domain/comboResolver.ts` ( `auto/` eesliite automaatne tuvastamine)
- Armatuurlaud: `/dashboard/auto-combo`
- Telemeetria: `auto_combo_decisions` SQLite tabel

Peamised võimalused:

- **20 marsruutimisstrateegiat** (prioriteetne, kaalutud, täitke enne, round-robin, P2C, juhuslik, vähim kasutatud, kuluoptimeeritud, lähtestamisteadlik, lähtestamisaken, vaba ruumi, kvoodiga kaalutud, rangelt juhuslik,** auto** , lkgp, konteksti optimeeritud, vahemälu optimeeritud, kontekstirelee,** sulandumine** , torujuhe) — auto on pealkirja lisamine versioonis 3.8.0; `fusion` (paneel fan-out + kohtuniku süntees, `open-sse/services/fusion.ts`) on versioonis 3.8.36 uus.
- **16-faktoriline punktiarvestus** : kvoot, tervis, pöördkulu, pöördlatentsus, ülesande sobivus ja veel kümme. Tegurite ja nende vaikekaalude kanooniline tabel on [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md) —, kui seda siin uuesti korrata, oleks see aegunud.
- **Virtuaalne tehas** realiseerib lühiajalised kombinatsioonid, kui sobivat nimelist kombinatsiooni pole olemas, hankides kandidaate tervetest aktiivsetest pakkujaühendustest.
- **Automaatsed eesliited** : `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`, `auto/smart`, `auto/lkgp` — millest igaüks toetab häälestatud kaaluprofiili.
- **6 režiimipaketti** : `ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`, `reliability-first` ja `chaos-mode` — eelseadistatud kaalukonfiguratsioonid, mida saab helistada armatuurlaualt. (Mitte segi ajada ülaltoodud `auto/*` eesliidetega, mis on päringu aja variandid.)

Täieliku algoritmi üksikasjade (faktorivalemid, kaalu häälestamine) kohta vt [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).

### B. Pilveagendid

Cloud Agents koondab kolmanda osapoole hostitud koodiagendi platvormid (Codex Cloud, Devin, Jules) ühtse DB-ga toetatud ülesannete elutsükli taha. Kõik ülesande creation/inspection lõpp-punktid nõuavad halduse autentimist.

- Mooduli juur: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`, `types.ts`, `db.ts`, pluss `agents/` all olevad agendipõhised alamkataloogid)
- Agendipõhised rakendused: `agents/codex/`, `agents/devin/`, `agents/jules/`
- Avalikud lõpp-punktid: `/api/v1/agents/tasks/*` (list/create/get/cancel)
- Haldamise lõpp-punktid: `/api/cloud/*` (ettevalmistamine, olek, partii)
- Armatuurlaud: `/dashboard/cloud-agents`
- Ladustamine: `cloud_agent_tasks` laud

Agendipõhise varustamise ja OAuth spetsiifiliste kohta vaadake jaotist [`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).

### C. Kaitsepiirded

Kaitsepiirete moodul on kuumalt taaslaaditav vahevarakiht, mis kontrollib taotlusi ja vastuseid PII, kiire süstimise ja ebaturvalise nägemissisu kohta. Rikkumised lühistavad taotluse HTTP ga** 503** pluss struktureeritud veakood, mis võimaldab allavoolu helistajatel uuesti proovida või hargneda.

- Mooduli juur: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)
- Kuum uuesti laadimine: register jälgib konfiguratsioonimuudatusi ja loob ahela paigale
- Juhtimispunktid: vestluse töötleja sisenemine, piltide genereerimise töötleja, vastuse puhastaja
- HTTP leping: rikkumiste pind `503` ja `error.code = "GUARDRAIL_VIOLATION"`

Reeglikomplekti loomise ja läve häälestamise kohta vt [`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).

### D. Domeenikiht

`src/domain/` nimeruum tsentraliseerib poliitikaotsused, nii et marsruudihaldurid ei pea ise lockout/budget/fallback loogikat kokku panema.

- Poliitikamootor: `src/domain/policyEngine.ts` — üks sisestuspunkt täitmiseelseks hindamiseks (lockout → eelarve → varujärjestus)
- Kulureeglid: `src/domain/costRules.ts`
- Varupoliitika: `src/domain/fallbackPolicy.ts`
- Lukustuspoliitika: `src/domain/lockoutPolicy.ts`
- Sildipõhine marsruutimine: `src/domain/tagRouter.ts`
- Kombineeritud lahendaja: `src/domain/comboResolver.ts` — lahendab kombineeritud nimed, automaatsed/\*-eesliited ja metamärgimudeli sihtmärgid konkreetseteks täitmisplaanideks
- Connection/model reegli liitja: `src/domain/connectionModelRules.ts`
- Mudeli saadavuse hetktõmmised: `src/domain/modelAvailability.ts`
- Pakkuja aegumise jälgimine: `src/domain/providerExpiration.ts`
- Kvoodi vahemälu: `src/domain/quotaCache.ts`. Pakkujad lisavad ja eemaldavad kvoodiaknaid (mõnede plaanide puhul loobus OpenAI 5-tunnise Codex aknast), nii et teenusepakkuja adapteri kasutuslugemine kinnitab täielikku (`quotasComplete`, vt `src/lib/usage/usageReading.ts`) on konto täielik akende komplekt: varem tuntud aken, mis sellest puudus, on kasutuselt kõrvaldatud, vahemälus, lisa `quota_snapshots`. püsis Codex kvoodi olek ja Claude küllastussalvedes. Osalised tõendid (vastuse päised, aegunud koopiad) värskendavad ainult neid aknaid, mida see kannab.
- Lagunemisaste: `src/domain/degradation.ts`
- Konfiguratsiooni audit: `src/domain/configAudit.ts`
- OmniRoute vastuse metaandmete koostaja: `src/domain/omnirouteResponseMeta.ts`
- Hindamise alamsüsteem: `src/domain/assessment/` — perioodilised hindamistööd

### E. Autoriseerimistoru

Autoriseerimiskonveier klassifitseerib kõik sissetulevad taotlused ja rakendab enne saatmist vastava poliitikaahela.

- Torujuhtme sisestus: `src/server/authz/pipeline.ts`
- Taotluse klassifikaator: `src/server/authz/classify.ts` — eristab avalikke ühilduvusmarsruute haldusmarsruutidest
- Avalike marsruutide loend: `src/shared/constants/publicApiRoutes.ts`
- Reeglid: `src/server/authz/policies/` — komponeeritavad predikaadid (`requireApiKey`, `requireManagement`, `requireFreshAuth` jne)
- Päise utiliidid: `src/server/authz/headers.ts`
- Väiteabiline: `src/server/authz/assertAuth.ts`
- Taotluse kontekst: `src/server/authz/context.ts`

Avalikud vs haldusmarsruudid on ranged piirid: agent/cooldown APIs ja pakkuja mutatsioonid nõuavad haldamise autentimist (kui puudub HTTP 401).

Täielikud marsruudi klassifitseerimise reeglid leiate jaotisest [`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).

### F. Töövoo FSM ja Task-Aware ruuter

Lõpliku olekuga masinaga juhitav ruuter, mis on kombineeritud valiku kohal, et suunata liiklust tuvastatud töövoo etapi (planeerimine, teostamine, ülevaatamine) ja taustaülesannete afiinsuse põhjal.

- Töövoog FSM: `open-sse/services/workflowFSM.ts`
- Ülesanneteadlik ruuter: `open-sse/services/taskAwareRouter.ts`
- Taustaülesannete detektor: `open-sse/services/backgroundTaskDetector.ts`
- Kavatsuse klassifikaator: `open-sse/services/intentClassifier.ts`

FSM üleminekud lähtuvad Auto Combo punktiarvestusest, kaldudes background/automation ülesannete jaoks odavamate mudelite poole ja interaktiivsete planning/review pöörete jaoks tugevamate mudelite poole.

### G. Pakkuja-spetsiifiline vastupidavus

Mitmed pakkujad tarnivad spetsiaalseid vastupidavus- ja varjamismooduleid, mis tagavad globaalse kaitselüliti / ühenduse jahtumise / mudeli lukustuskihi:

- Antigravity 429 mootor: `open-sse/services/antigravity429Engine.ts` (pöörab identiteeti, puhastab vastuse päiseid, juhib credits/version jälgimist `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`, `antigravityIdentity.ts`, `antigravityVersion.ts` kaudu)
- Antigravity 429 valvur: `open-sse/services/antigravity429Guard.ts` (päringupõhine ülesvoolu 429-de eelarve kõigis hostides, `ANTIGRAVITY_MAX_429_ATTEMPTS`; keeldutud keha identsele uuestisaatmisele vastatakse kohapeal; `src/sse/handlers/chat.ts` ei taaskäivita sellist päringut jahtumisest teadliku korduskatse kaudu)
- ModelScope kvoodipoliitika: `open-sse/services/modelscopePolicy.ts`
- Claude kood CCH (ühilduvuskanali käepigistus): `open-sse/services/claudeCodeCCH.ts`, pluss `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`, `claudeCodeToolRemapper.ts`
- Claude Koodi sõrmejälje kujundamine: `open-sse/services/claudeCodeFingerprint.ts`
- Claude Koodi hägustamine: `open-sse/services/claudeCodeObfuscation.ts`

Täieliku varjatud juhendi ja kasutusjuhiste saamiseks vaadake `docs/security/STEALTH_GUIDE.md` (git; ei ole koostatud `/docs`).

### H. Webhooks, arutlusvahemälu, lugemisvahemälu

- **Veebihaagid** — väljaminek provider/account/task sündmuste jaoks.
  - Dispetšer: `src/lib/webhookDispatcher.ts`
  - Salvestusruum: `webhooks` SQLite laud ( `src/lib/db/webhooks.ts` kaudu)
  - Juhtpaneel: `/dashboard/webhooks` (tellimused, saladused, uuesti proovimise ajalugu)
  - Sündmuste taksonoomia ja uuesti proovimise semantika kohta vt [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Arutlusvahemälu** — taasesitavad arutlusplokid pakkujatele, kes väljastavad mõtlemismärke (Claude, GLMT jne), nii et järjestikused pöörded võivad ümbermõtlemise vahele jätta.
  - DB kiht: `src/lib/db/reasoningCache.ts`
  - Teeninduskiht: `open-sse/services/reasoningCache.ts`
  - Taasesituse semantika kohta vt [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Lugege vahemälu** — lühiajaline vastuse vahemälu, mis on sisestatud allkirjaga ja mida kasutatakse identsete korduskatsete ahendamiseks purustatud ülesvoolu SDKs.
  - DB kiht: `src/lib/db/readCache.ts`
  - Statistika lõpp-punkt: `GET /api/cache/stats`, armatuurlaud at `/dashboard/cache`

## 3) Püsivuskihi (Persistence Layer)

Peamine olekuandmebaas (SQLite):

- Põhitaristu: `src/lib/db/core.ts` (better-sqlite3, migratsioonid, WAL)
- Andmebaasi kasutus: impordi konkreetsed `src/lib/db/*` moodulid otse (vana `localDb.ts` koondmoodul on eemaldatud)
- fail: `${DATA_DIR}/storage.sqlite` (või `$XDG_CONFIG_HOME/omniroute/storage.sqlite`, kui see on määratud, vastasel juhul `~/.omniroute/storage.sqlite`)
- olemid (tabelid + KV nimeruumid): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**

Kasutuse (usage) püsivus:

- fassaad: `src/lib/usageDb.ts` (lahtivõetud moodulid `src/lib/usage/*`)
- SQLite tabelid failis `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`
- valikulised failipõhised artefaktid säilivad ühilduvuse/silumise huvides (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)
- vanad JSON-failid migreeritakse SQLite'i käivitusmigratsioonide käigus, kui need eksisteerivad

Domeenioleku andmebaas (SQLite):

- `src/lib/db/domainState.ts` — domeenioleku CRUD-operatsioonid
- Tabelid (loodud failis `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
- Läbikirjutava vahemälu (write-through cache) muster: mällu paigutatud Map-id on käitusajal autoriteetsed; muudatused kirjutatakse sünkroonselt SQLite'i; olek taastatakse andmebaasist külmkäivitusel

## 4) Autentimine + turbepinnad

- Juhtpaneeli küpsisepõhine autentimine: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
- API-võtmete genereerimine/kontrollimine: `src/shared/utils/apiKey.ts`
- Teenusepakkujate saladused talletatakse `providerConnections` kirjetes
- Väljamineva puhverserveri tugi faili `open-sse/utils/proxyFetch.ts` (keskkonnamuutujad) ja faili `open-sse/utils/networkProxy.ts` (seadistatav teenusepakkuja kaupa või globaalselt) kaudu
- SSRF-i / väljaminevate URL-ide kaitse: `src/shared/network/outboundUrlGuard.ts` — hostikontrollid teenusepakkujate väljakutsetel ja veebihaagi sihtmärkidel; režiim pärineb failist `src/shared/network/outboundUrlGuardPolicy.ts` (lipud failis `docs/reference/ENVIRONMENT.md`)
- Käituskeskkonna muutujate valideerimine: `src/lib/env/runtimeEnv.ts` — Zodi skeem kõigi keskkonnamuutujate jaoks; tõrked ja hoiatused kuvatakse käivitamisel
- Sünkroonimistõendid: `src/lib/db/syncTokens.ts` — ulatusega tõendid konfiguratsioonipaketi allalaadimise lõpp-punktide jaoks; neid toetab SQLite’i tabel `sync_tokens` (migratsioon `024_create_sync_tokens.sql`)
- WebSocketi kätluse autentimine: `src/lib/ws/handshake.ts` — valideerib WS-i täiendamistaotlusi API-võtme või seansiküpsise abil
- Reaalajas juhtpaneeli WebSocketi autentimine: `src/server/ws/liveServer.ts` — külgprotsess (port `LIVE_WS_PORT`) aktsepteerib juhtpaneeli seansiküpsist või Beareri API-võtit, millel on haldusulatus (`manage`/`admin`); ainult järeldamiseks mõeldud võtmetest keeldutakse. Selle sisemine avaldaja lõpp-punkt `POST /__omniroute_event` aktsepteerib tagasisideaadressi kaudu ühenduvaid osapooli ainult juhul, kui puudub puhverserveri vahendusetappi näitav päis (`x-forwarded-*`, `x-real-ip`, `forwarded`, `via`)

## 5) Pilvesünkroonimine

- Ajastaja lähtestamine: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`
- Perioodiline ülesanne: `src/shared/services/cloudSyncScheduler.ts`
- Perioodiline ülesanne: `src/shared/services/modelSyncScheduler.ts`
- Juhtimise marsruut: `src/app/api/sync/cloud/route.ts`

## Päringu elutsükkel (`/v1/chat/completions`)

```mermaid
sequenceDiagram
    autonumber
    participant Client as CLI/SDK Client
    participant Route as /api/v1/chat/completions
    participant Chat as src/sse/handlers/chat
    participant Core as open-sse/handlers/chatCore
    participant Model as Model Resolver
    participant Auth as Credential Selector
    participant Exec as Provider Executor
    participant Prov as Upstream Provider
    participant Stream as Stream Translator
    participant Usage as usageDb

    Client->>Route: POST /v1/chat/completions
    Route->>Chat: handleChat(request)
    Chat->>Model: parse/resolve model or combo

    alt Combo mudel
        Chat->>Chat: itereeri kombo mudelite üle (handleComboChat)
    end

    Chat->>Auth: getProviderCredentials(provider)
    Auth-->>Chat: aktiivne konto + tokenid/API-võti

    Chat->>Core: handleChatCore(body, modelInfo, credentials)
    Core->>Core: tuvasta lähtevorming
    Core->>Core: teisenda päring sihtvormingusse
    Core->>Exec: execute(provider, transformedBody)
    Exec->>Prov: ülemine (upstream) API-kõne
    Prov-->>Exec: SSE/JSON vastus
    Exec-->>Core: vastus + metaandmed

    alt 401/403
        Core->>Exec: refreshCredentials()
        Exec-->>Core: uuendatud tokenid
        Core->>Exec: korda päring
    end

    Core->>Stream: teisenda/normaliseeri voog kliendi vormingusse
    Stream-->>Client: SSE tükid / JSON vastus

    Stream->>Usage: eralda kasutusandmed + salvesta ajalugu/logi
```

## Kombo + konto varusüsteemi (fallback) voog

```mermaid
flowchart TD
    A[Sisenev mudeli string] --> B{Kas kombo nimi?}
    B -- Jah --> C[Laadi kombo mudelite jada]
    B -- Ei --> D[Ühe mudeli tee]

    C --> E[Proovi mudelit N]
    E --> F[Lahenda provider/mudel]
    D --> F

    F --> G[Vali konto autentimisandmed]
    G --> H{Autentimisandmed olemas?}
    H -- Ei --> I[Tagasta provider ei ole saadaval]
    H -- Jah --> J[Käivita päring]

    J --> K{Õnnestus?}
    K -- Jah --> L[Tagasta vastus]
    K -- Ei --> M{Varusüsteemi (fallback) sobiv viga?}

    M -- Ei --> N[Tagasta viga]
    M -- Jah --> O[Märgi konto ajutiselt mittesaadavaks (cooldown)]
    O --> P{Kas providerile on veel kontosid?}
    P -- Jah --> G
    P -- Ei --> Q{Kombos on järgmine mudel?}
    Q -- Jah --> E
    Q -- Ei --> R[Tagasta kõik mittesaadavaks]
```

Varusüsteemi (fallback) otsuseid juhib `open-sse/services/accountFallback.ts`, kasutades staatuskoode ja veateate heuristikat. Kombo ruutimine lisab veel ühe kaitsemehhanismi: provideri-spetsiifilised 400 vead, näiteks upstream sisu blokeerimise ja rolli kehtivuse kontrolli vead, käsitletakse mudeli-lokaalsete vigadena, et hilisemad kombo sihtmärgid saaksid siiski töötada.

## OAuth kasutuselevõtu ja tokeni värskendamise elutsükkel

```mermaid
sequenceDiagram
    autonumber
    participant UI as Dashboard UI
    participant OAuth as /api/oauth/[provider]/[action]
    participant ProvAuth as Provideri autentimisserver
    participant DB as localDb
    participant Test as /api/providers/[id]/test
    participant Exec as Provideri täitja (Executor)

    UI->>OAuth: GET authorize või device-code
    OAuth->>ProvAuth: loo auth/device voog
    ProvAuth-->>OAuth: auth URL või device koodi payload
    OAuth-->>UI: voo andmed

    UI->>OAuth: POST exchange või poll
    OAuth->>ProvAuth: tokeni vahetus/päring
    ProvAuth-->>OAuth: juurdepääsu/värskendustokenid
    OAuth->>DB: createProviderConnection(oauth andmed)
    OAuth-->>UI: õnnestumine + ühenduse id

    UI->>Test: POST /api/providers/[id]/test
    Test->>Exec: valideeri autentimisandmed / valikuline värskendamine
    Exec-->>Test: kehtiv või värskendatud tokeni info
    Test->>DB: värskenda staatust/tokeneid/vigu
    Test-->>UI: valideerimise tulemus
```

Värskendamine reaalajas liikluse ajal toimub `open-sse/handlers/chatCore.ts` sees täitja (executor) funktsiooni `refreshCredentials()` kaudu.

## Pilvesünkroonimise elutsükkel (lubamine / sünkroonimine / keelamine)

```mermaid
sequenceDiagram
    autonumber
    participant UI as Endpoint Page UI
    participant Sync as /api/sync/cloud
    participant DB as localDb
    participant Cloud as Väline pilvesünkroonimine
    participant Claude as ~/.claude/settings.json

    UI->>Sync: POST action=enable
    Sync->>DB: määra cloudEnabled=true
    Sync->>DB: kontrolli, et API võti eksisteerib
    Sync->>Cloud: POST /sync/{machineId} (providerid/aliased/kombod/võtmed)
    Cloud-->>Sync: sünkroonimise tulemus
    Sync->>Cloud: GET /{machineId}/v1/verify
    Sync-->>UI: lubatud + verifitseerimise staatus

    UI->>Sync: POST action=sync
    Sync->>Cloud: POST /sync/{machineId}
    Cloud-->>Sync: kaugandmed
    Sync->>DB: värskenda uuemaid kohalikke tokeneid/staatust
    Sync-->>UI: sünkroonitud

    UI->>Sync: POST action=disable
    Sync->>DB: määra cloudEnabled=false
    Sync->>Cloud: DELETE /sync/{machineId}
    Sync->>Claude: lülita ANTHROPIC_BASE_URL tagasi kohalikuks (kui vajalik)
    Sync-->>UI: keelatud
```

Perioodiline sünkroonimine käivitatakse `CloudSyncScheduler` poolt, kui pilv on lubatud.

## Andmemudel ja säilituskaardistus

```mermaid
erDiagram
    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage

    SETTINGS {
      boolean cloudEnabled
      number stickyRoundRobinLimit
      boolean requireLogin
      string password_hash
      string fallbackStrategy
      json rateLimitDefaults
      json providerProfiles
    }

    PROVIDER_CONNECTION {
      string id
      string provider
      string authType
      string name
      number priority
      boolean isActive
      string apiKey
      string accessToken
      string refreshToken
      string expiresAt
      string testStatus
      string lastError
      string rateLimitedUntil
      json providerSpecificData
    }

    PROVIDER_NODE {
      string id
      string type
      string name
      string prefix
      string apiType
      string baseUrl
    }

    MODEL_ALIAS {
      string alias
      string targetModel
    }

    COMBO {
      string id
      string name
      string[] models
    }

    API_KEY {
      string id
      string name
      string key
      string machineId
    }

    USAGE_ENTRY {
      string provider
      string model
      number prompt_tokens
      number completion_tokens
      string connectionId
      string timestamp
    }

    CUSTOM_MODEL {
      string id
      string name
      string providerId
    }

    PROXY_CONFIG {
      string global
      json providers
    }

    IP_FILTER {
      string mode
      string[] allowlist
      string[] blocklist
    }

    THINKING_BUDGET {
      string mode
      number customBudget
      string effortLevel
    }

    SYSTEM_PROMPT {
      boolean enabled
      string prompt
      string position
    }
```

Füüsilised säilitusfailid:

- peamine töötlusaegne andmebaas: `${DATA_DIR}/storage.sqlite`
- päringute logiread: `${DATA_DIR}/log.txt` (ühilduvuse/silumise artefakt)
- struktureeritud kõnepäringute salvestised: `${DATA_DIR}/call_logs/`
- valikulised tõlkija/päringute silumissessioonid: `<repo>/logs/...`

## Juurutuse topoloogia

```mermaid
flowchart LR
    subgraph LocalHost[Arendaja hosti]
        CLI[CLI tööriistad]
        Browser[Töölaua veebilehitseja]
    end

    subgraph ContainerOrProcess[OmniRoute töötlusaegne keskkond]
        Next[Next.js server\nPORT=20128]
        Core[SSE tuum + täiturid]
        MainDB[(storage.sqlite)]
        UsageDB[(kasutustabelid + logiartefaktid)]
    end

    subgraph External[Välised teenused]
        Providers[AI teenusepakkujad]
        SyncCloud[Pilvesünkroonimisteenus]
    end

    CLI --> Next
    Browser --> Next
    Next --> Core
    Next --> MainDB
    Core --> MainDB
    Core --> UsageDB
    Core --> Providers
    Next --> SyncCloud
```

## Moodulite kaardistus (otsuste tegemisel kriitiline)

### Marsruudi- ja API-moodulid

- `src/app/api/v1/*`, `src/app/api/v1beta/*`: ühilduvuse API-d
- `src/app/api/v1/providers/[provider]/*`: teenusepakkuja-spetsiifilised eraldi marsruudid (vestlus, manustused, pildid)
- `src/app/api/providers*`: teenusepakkujate CRUD, valideerimine, testimine
- `src/app/api/provider-nodes*`: kohandatud ühilduvate sõlmede haldus
- `src/app/api/provider-models`: kohandatud mudelite haldus (CRUD)
- `src/app/api/models/route.ts`: mudelikataloogi API (aliased + kohandatud mudelid)
- `src/app/api/oauth/*`: OAuth/seadme-koodi vood
- `src/app/api/keys*`: kohaliku API-võtme elutsükkel
- `src/app/api/models/alias`: aliaste haldus
- `src/app/api/combos*`: varusammastike (fallback combo) haldus
- `src/app/api/pricing`: hinnastuse ülekirjutused kulude arvutamiseks
- `src/app/api/settings/proxy`: puhverserveri konfiguratsioon (GET/PUT/DELETE)
- `src/app/api/settings/proxy/test`: väljuva puhverserveri ühenduvuse test (POST)
- `src/app/api/usage/*`: kasutuse ja logide API-d
- `src/app/api/sync/*` + `src/app/api/cloud/*`: pilvesünkroonimine ja pilvele suunatud abifunktsioonid
- `src/app/api/cli-tools/*`: kohalikud CLI konfiguratsioonikirjutajad/kontrollijad
- `src/app/api/settings/ip-filter`: IP lubatud/keelatud loend (GET/PUT)
- `src/app/api/settings/thinking-budget`: mõtlemistokenite eelarve konfiguratsioon (GET/PUT)
- `src/app/api/settings/system-prompt`: globaalne süsteemipäring (GET/PUT)
- `src/app/api/settings/compression`: globaalsed tihendusseaded (GET/PUT)
- `src/app/api/compression/*`: tihenduse eelvaade, reeglite metaandmed ja keelepaketid
- `src/app/api/context/caveman/config`: Caveman'i seadete alias (GET/PUT)
- `src/app/api/context/rtk/*`: RTK konfiguratsioon, filtrikataloog, testimispunkt ja toorväljundi taastamine
- `src/app/api/context/combos*`: tihenduskombode CRUD ja marsruutimiskombode määramised
- `src/app/api/context/analytics`: tihendusanalüütika alias
- `src/app/api/sessions`: aktiivsete sessioonide loend (GET)
- `src/app/api/rate-limits`: konto-põhine piirmäära staatus (GET)
- `src/app/api/sync/tokens`: sünkroonimistoken CRUD (GET/POST)
- `src/app/api/sync/tokens/[id]`: sünkroonimistokeni pärimine/kustutamine (GET/DELETE)
- `src/app/api/sync/bundle`: konfiguratsioonipaketi allalaadimine (GET, ETag versioonihaldus)
- `src/app/api/v1/ws`: WebSocket ühenduse ülesehitamise haldur OpenAI-ühilduvatele WS klientidele

### Marsruutimise ja täitmise tuum

- `src/sse/handlers/chat.ts`: päringu parsimine, kombo käsitlus, konto valiku tsükkel
- `open-sse/handlers/chatCore.ts`: tõlkimine, täituri väljakutsumine, kordusürituse/värskendamise käsitlus, voo seadistus
- `open-sse/executors/*`: teenusepakkuja-spetsiifiline võrgu- ja vorminguline käitumine

### Tõlkeregistrid ja vormindusmuundurid

- `open-sse/translator/index.ts`: tõlkijaregister ja orkestreerimine
- Päringutõlkijad: `open-sse/translator/request/*` (9 moodulit — `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`, `gemini-to-openai`, `openai-responses`, `openai-to-claude`, `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`)
- Vastustõlkijad: `open-sse/translator/response/*` (11 moodulit — `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`, `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`, `openai-to-claude`, `openai-to-gemini`, `openai-to-gemini-sse`, `responsesToolItem`)
- Abifunktsioonid: `open-sse/translator/helpers/*` (12 moodulit — `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `jsonUtil`, `markdownBoundary`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `strictSystemHoist`, `toolCallHelper`, `toolCallShim`)
- Vormingu konstandid: `open-sse/translator/formats.ts`
- Käivitus ja register: `open-sse/translator/bootstrap.ts`, `open-sse/translator/registry.ts`
- Pildivormingu abifunktsioonid: `open-sse/translator/image/`

### Püsivus

- `src/lib/db/*`: püsiv konfiguratsioon/olek ja domeeni püsivus SQLite peal
- `src/lib/db/*`: importige konkreetseid mooduleid otse — koondfaili ei ole (vana `localDb.ts` uuestieksportimise kihi eemaldati)
- `src/lib/usageDb.ts`: kasutusajaloo/kõnede logide liides SQLite tabelite peal

## Pakkuja täitmismootorite (Executor) katvus (Strateegia muster)

Igal pakkujal on spetsialiseeritud täitmismootor, mis laiendab klassi `BaseExecutor` (failis `open-sse/executors/base.ts`), mis pakub URL-i koostamist, päiste koostamist, korduskatseid eksponentsiaalse tagasilangusega, mandaatide värskendamise konkse (hooks) ja `execute()` orkestreerimismeetodit.

| Executor                  | Pakkuja(d)                                                                                                                                                  | Erikäsitlus                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `DefaultExecutor`         | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, jne. | Dünaamiline URL/päiste konfiguratsioon vastavalt pakkujale                                |
| `AntigravityExecutor`     | Google Antigravity                                                                                                                                          | Kohandatud projekti/seansi ID-d, Retry-After parsimine, 429 hägustamine                   |
| `AzureOpenAIExecutor`     | Azure OpenAI                                                                                                                                                | Juurutuse (deployment) põhine ruutimine, api-version päringuparameetri jõustamine         |
| `BlackboxWebExecutor`     | Blackbox AI (veebirežiim)                                                                                                                                   | Veebiseansi pöördlahendus TLS jäljendi emuleerimisega                                     |
| `ClaudeIdentityExecutor`  | Claude.ai (CCH tee)                                                                                                                                         | Piirangute + tööriistade ümbermääramise (tool-remap) torustikud, jäljendi kujundamine     |
| `CliProxyApiExecutor`     | CLIProxyAPI-ühilduvad pakkujad                                                                                                                              | Kohandatud autentimise ja protokolli käsitlus                                             |
| `CloudflareAiExecutor`    | Cloudflare Workers AI                                                                                                                                       | Konto ID süstimine, Neuronite (Neurons) põhine kasutuse jälgimine                         |
| `CodexExecutor`           | OpenAI Codex                                                                                                                                                | Süstib süsteemseid juhiseid, sunnib arutlustaseme (reasoning effort)                      |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex)                                                                                                                                         | Brauseriseansi Responses API sild lõime/käigu kinnistamisega                              |
| `CommandCodeExecutor`     | Command Code                                                                                                                                                | OAuth + seansipõhine päiste rotatsioon                                                    |
| `CursorExecutor`          | Cursor IDE                                                                                                                                                  | ConnectRPC protokoll, Protobuf kodeerimine, päringute allkirjastamine kontrollsumma kaudu |
| `DevinCliExecutor`        | Devin CLI                                                                                                                                                   | Devin'i ülesande elutsükli sidumine pilveagendi mooduli kaudu                             |
| `GithubExecutor`          | GitHub Copilot                                                                                                                                              | Copilot'i tokeni värskendamine, VSCode'i jäljendavad päised                               |
| `GitlabExecutor`          | GitLab Duo                                                                                                                                                  | GitLab OAuth + projekti ulatuses ruutimine                                                |
| `GlmExecutor`             | Z.AI GLM (kaasa arvatud `glmt` eelseadistus)                                                                                                                | Mõtlemiseelarve (thinking-budget) teadlikkus, GLMT eelseadistuse konstandid               |
| `GrokWebExecutor`         | xAI Grok veeb                                                                                                                                               | Veebiseansi pöördlahendus, režiimi valik (mõtlemine/standard)                             |
| `KieExecutor`             | KIE                                                                                                                                                         | Kohandatud tokeni väljastamine roteeruvate seansi ankrutega                               |
| `KiroExecutor`            | AWS CodeWhisperer/Kiro                                                                                                                                      | AWS EventStream'i binaarvormingu → SSE teisendus                                          |
| `MuseSparkWebExecutor`    | Muse Spark (veeb)                                                                                                                                           | Veebiseansi pöördlahendus pildisõnumite sidumisega                                        |
| `NlpCloudExecutor`        | NLP Cloud                                                                                                                                                   | Pakkujaspetsiifiline päringukeha kuju                                                     |
| `OpenCodeExecutor`        | OpenCode                                                                                                                                                    | AI SDK-ga ühilduva pakkuja seadistus                                                      |
| `PerplexityWebExecutor`   | Perplexity veeb                                                                                                                                             | Veebiseansi pöördlahendus vestluse jätkamiseks                                            |
| `PetalsExecutor`          | Petals hajutatud järelduse (inference) mootor                                                                                                               | Detsentraliseeritud pesa (swarm) ruutimine                                                |
| `PollinationsExecutor`    | Pollinations AI                                                                                                                                             | API-võtit ei vajata, kiiruspiiratud (rate-limited) päringud                               |
| `QoderExecutor`           | Qoder AI                                                                                                                                                    | PAT ja OAuth tugi, mitme mudeli tasuta tase                                               |
| `VertexExecutor`          | Google Vertex AI                                                                                                                                            | Teenusekonto autentimine, regioonipõhised lõpp-punktid                                    |
| `DevinDesktopExecutor`    | Devin Desktop                                                                                                                                               | Imporditud API-võti + Connect-protobufi vestluse voogesitus                               |

Kõik muud pakkujad (kaasa arvatud kohandatud ühilduvad sõlmed) kasutavad `DefaultExecutor`-it.

## Pakkujate ühilduvusmaatriks

> **Märkus:** Allolev maatriks on esinduslik valik 351 registreeritud pakkujast
> OmniRoute v3.8.0-s. Kanoonilise ja pidevalt värskendatava loendi leiate
> failist [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (automaatselt genereeritud) või usaldusväärikast allikast
> `src/shared/constants/providers.ts` (valideeritud Zod-iga laadimisel).

| Pakkuja             | Vorming          | Autentimine               | Voogesitus       | Ilma voota | Tokeni uuendamine | Kasutuse API                  |
| ------------------- | ---------------- | ------------------------- | ---------------- | ---------- | ----------------- | ----------------------------- |
| Claude              | claude           | API Key / OAuth           | ✅               | ✅         | ✅                | ⚠️ Ainult administraatoritele |
| Gemini              | gemini           | API Key / OAuth           | ✅               | ✅         | ✅                | ⚠️ Cloud Console              |
| Antigravity         | antigravity      | OAuth                     | ✅               | ✅         | ✅                | ✅ Täielik kvoodi API         |
| OpenAI              | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Codex               | openai-responses | OAuth                     | ✅ sundvoog      | ❌         | ✅                | ✅ Piirmäärad                 |
| ChatGPT Web (Codex) | openai-responses | Brauseri seanss           | ✅ sundvoog      | ❌         | ❌                | ❌                            |
| GitHub Copilot      | openai           | OAuth + Copilot Token     | ✅               | ✅         | ✅                | ✅ Kvoodi ülevaated           |
| Cursor              | cursor           | Kohandatud kontrollsumma  | ✅               | ✅         | ❌                | ❌                            |
| Kiro                | kiro             | AWS SSO OIDC              | ✅ (EventStream) | ❌         | ✅                | ✅ Kasutuspiirid              |
| Qoder               | openai           | OAuth / PAT               | ✅               | ✅         | ✅                | ⚠️ Päringu kohta              |
| Kilo Code           | openai           | OAuth                     | ✅               | ✅         | ✅                | ❌                            |
| Cline               | openai           | OAuth                     | ✅               | ✅         | ✅                | ❌                            |
| Kimi Coding         | openai           | OAuth                     | ✅               | ✅         | ✅                | ❌                            |
| OpenRouter          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| GLM/Kimi/MiniMax    | claude           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| DeepSeek            | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Groq                | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| xAI (Grok)          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Mistral             | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Perplexity          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Together AI         | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Fireworks AI        | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Cerebras            | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Cohere              | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| NVIDIA NIM          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Cloudflare AI       | openai           | API Token + Konto ID      | ✅               | ✅         | ❌                | ❌                            |
| Pollinations        | openai           | Puudub (võtit ei vaja)    | ✅               | ✅         | ❌                | ❌                            |
| Scaleway AI         | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| LongCat             | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Ollama Cloud        | openai           | API Key (valikuline)      | ✅               | ✅         | ❌                | ❌                            |
| HuggingFace         | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Nebius              | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| SiliconFlow         | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Hyperbolic          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Vertex AI           | gemini           | Teenusekonto              | ✅               | ✅         | ✅                | ⚠️ Cloud Console              |
| Command Code        | openai           | OAuth                     | ✅               | ✅         | ✅                | ⚠️ Päringu kohta              |
| Z.AI / GLM          | openai           | API Key / OAuth           | ✅               | ✅         | ❌                | ❌                            |
| GLMT (eelseade)     | claude           | API Key                   | ✅               | ✅         | ❌                | ⚠️ Päringu kohta              |
| Kimi Coding         | openai           | OAuth / API Key           | ✅               | ✅         | ✅                | ❌                            |
| KIE                 | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Devin Desktop       | openai           | Imporditud API võti       | ✅ (Connect→SSE) | ✅         | ❌                | ⚠️ Päringu kohta              |
| GitLab Duo          | openai           | OAuth (GitLab)            | ✅               | ✅         | ✅                | ❌                            |
| Devin CLI           | openai           | Kohalik CLI sisselogimine | ✅               | ✅         | ❌                | ✅ Ülesannete API             |
| Codex Cloud         | openai-responses | OAuth                     | ✅               | ❌         | ✅                | ✅ Piirmäärad                 |
| Jules               | openai           | OAuth                     | ✅               | ✅         | ✅                | ✅ Ülesannete API             |
| AgentRouter         | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Grok-Web            | openai           | Seansi küpsis             | ✅               | ✅         | ❌                | ❌                            |
| Perplexity-Web      | openai           | Seansi küpsis             | ✅               | ✅         | ❌                | ❌                            |
| BlackBox-Web        | openai           | Seansi küpsis + TLS       | ✅               | ✅         | ❌                | ❌                            |
| Muse-Spark-Web      | openai           | Seansi küpsis             | ✅               | ✅         | ❌                | ❌                            |
| ModelScope          | openai           | API Key                   | ✅               | ✅         | ❌                | ⚠️ Kvoodipoliitika            |
| BazaarLink          | openai           | API Key                   | ✅               | ✅         | ❌                | ❌                            |
| Petals              | openai           | Puudub                    | ✅               | ✅         | ❌                | ❌                            |
| Qoder               | openai           | OAuth / PAT               | ✅               | ✅         | ✅                | ⚠️ Päringu kohta              |
| OpenCode (Go/Zen)   | openai           | OAuth                     | ✅               | ✅         | ✅                | ❌                            |
| CLIProxyAPI         | openai           | Kohandatud                | ✅               | ✅         | ❌                | ❌                            |

## Vormingu teisendamise kaetus

Tuvastatud lähtevormingud sisaldavad:

- `openai`
- `openai-responses`
- `claude`
- `gemini`

Sihtvormingud sisaldavad:

- OpenAI chat/Responses
- Claude
- Gemini/Antigravity envelope
- Kiro
- Cursor

Teisendused kasutavad **OpenAI-t keskse vormingina (hub format)** — kõik teisendused toimuvad läbi OpenAI vahepealse vorminguna:

```
Lähtevorming → OpenAI (hub) → Sihtvorming
```

Teisendused valitakse dünaamiliselt lähtekasuliku andmemahu kuju ja teenusepakkuja sihtvormingu alusel.

Teisenduspipeline'i täiendavad töötlusetapid:

- **Vastuse puhastamine (sanitization)** — Eemaldab OpenAI-vormingus vastustest (nii voogesituse kui mitte-voogesituse korral) mittestandardsed väljad, tagamaks range SDK-le vastavuse
- **Rolli normaliseerimine** — Teisendab `developer` → `system` mitte-OpenAI sihtvormingute jaoks; ühendab `system` → `user` mudelite jaoks, mis lükkavad system-rolli tagasi (GLM, ERNIE)
- **Think-tag'ide eraldamine** — Analüüsib `` blokid sisust ja eraldab need `reasoning_content` väljale
- **Struktureeritud väljund** — Teisendab OpenAI `response_format.json_schema` Gemini `responseMimeType` + `responseSchema` vormingusse

## Toetatud API lõpp-punktid

| Lõpp-punkt                                         | Vorming                | Handler                                                                                          |
| -------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| `POST /v1/chat/completions`                        | OpenAI Chat            | `src/sse/handlers/chat.ts`                                                                       |
| `POST /v1/messages`                                | Claude Messages        | Sama handler (automaatselt tuvastatud)                                                           |
| `POST /v1/responses`                               | OpenAI Responses       | `open-sse/handlers/responsesHandler.ts`                                                          |
| `POST /v1/embeddings`                              | OpenAI Embeddings      | `open-sse/handlers/embeddings.ts`                                                                |
| `GET /v1/embeddings`                               | Mudelite loend         | API tee                                                                                          |
| `POST /v1/images/generations`                      | OpenAI Images          | `open-sse/handlers/imageGeneration.ts`                                                           |
| `GET /v1/images/generations`                       | Mudelite loend         | API tee                                                                                          |
| `POST /v1/providers/{provider}/chat/completions`   | OpenAI Chat            | Teenusepakkuja-põhine dedikeeritud lahendus mudeli valideerimisega                               |
| `POST /v1/providers/{provider}/embeddings`         | OpenAI Embeddings      | Teenusepakkuja-põhine dedikeeritud lahendus mudeli valideerimisega                               |
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images          | Teenusepakkuja-põhine dedikeeritud lahendus mudeli valideerimisega                               |
| `POST /v1/messages/count_tokens`                   | Claude Token Count     | API tee                                                                                          |
| `GET /v1/models`                                   | OpenAI mudelite loend  | API tee (chat + embedding + image + kohandatud mudelid)                                          |
| `GET /api/models/catalog`                          | Katalog                | Kõik mudelid grupeerituna teenusepakkuja ja tüübi järgi                                          |
| `POST /v1beta/models/*:streamGenerateContent`      | Gemini native          | API tee                                                                                          |
| `GET/PUT/DELETE /api/settings/proxy`               | Proxy seaded           | Võrgu proxy konfiguratsioon                                                                      |
| `POST /api/settings/proxy/test`                    | Proxy ühenduvus        | Proxy tervise/ühenduvuse testimise lõpp-punkt                                                    |
| `GET/POST/DELETE /api/provider-models`             | Teenusepakkuja mudelid | Teenusepakkuja mudelite metaandmed, mis toetavad kohandatud ja hallatavaid saadaolevaid mudeleid |

## Bypass Handler

Bypass handler (`open-sse/utils/bypassHandler.ts`) püüab kinni teadaolevad "ühekordsed" päringud Claude CLI-lt — soojenduse pingid, pealkirjade eraldamised ja tokenite loendused — ning tagastab **võltsvastuse**, kulutamata seejuures upstream-pakkuja tokeneid. See rakendub ainult juhul, kui `User-Agent` sisaldab `claude-cli`.

## Päringute logimine ja artefaktid

Vanem failipõhine päringulogija (`open-sse/utils/requestLogger.ts`) on säilitatud
üksnes tagasiühilduvuse tarbeks. Praegune käitusaja leping kasutab:

- `APP_LOG_TO_FILE=true` rakenduse- ja auditilogide jaoks, mis kirjutatakse kausta `<repo>/logs/`
- SQLite-põhiseid kõnelogi kirjeid tabelis `call_logs`
- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artefakte, kui kõnelogi torustik on sisse lülitatud

## Rikke stsenaariumid ja vastupidavus

## 1) Konto/pakkuja saadavus

- ühenduse jahtumisaeg (cooldown) korduskatsele alluvate upstream-rikete puhul
- kontole ülemineku varulahendus enne päringu ebaõnnestumist
- kombineeritud mudeli varulahendus, kui praegune mudeli/pakkuja tee on ammendatud

## 2) Tokeni kehtivusaja lõppemine

- eelkontroll ja värskendamine korduskatsega taastuvate pakkujate jaoks
- 401/403 korduskatse pärast värskenduskatset põhirajal

## 3) Voo turvalisus

- katkestustundlik voo kontroller
- tõlkevoog voo lõpu tühjendamise ja `[DONE]` käsitlemisega
- kasutuse hindamise varulahendus, kui pakkuja kasutusmetaandmed puuduvad

## 4) Pilvesünkroniseerimise halvenemine

- sünkroniseerimisvead tuuakse esile, kuid kohalik käitusaeg jätkab tööd
- ajastajal on korduskatse võimekusega loogika, kuid perioodiline käivitamine kutsub praegu vaikimisi välja ühekordse katsega sünkroniseerimise

## 5) Andmete terviklus

- SQLite skeemi migratsioonid ja automaatse uuendamise hoogud käivitamisel
- vana JSON → SQLite migratsiooni ühilduvustee

## 6) SSRF / väljuva URL-i kaitse

- `src/shared/network/outboundUrlGuard.ts` blokeerib kõik privaatsed/loopback/link-local sihtmärk-URL-id enne, kui need jõuavad pakkuja täitjatesse
- Pakkuja mudeli avastamise ja valideerimise rajad kasutavad `src/shared/network/safeOutboundFetch.ts`, mis rakendab kaitset enne igat väljuvat päringut
- Kaitse vead ilmuvad kui `URL_GUARD_BLOCKED` koos HTTP 422 staatusega ning logitakse vastavuse auditi rajale `providerAudit.ts` kaudu

## Vaadeldavus ja operatiivsed signaalid

Käitusaja nähtavuse allikad:

- konsoolilogid failist `src/sse/utils/logger.ts`
- päringupõhised kasutuse koondandmed SQLite-s (`usage_history`, `call_logs`, `proxy_logs`)
- neljaastmelised detailsed andmekoormuse (payload) jäädvustused SQLite-s (`request_detail_logs`), kui `settings.detailed_logs_enabled=true`
- tekstiline päringuoleku logi failis `log.txt` (valikuline/ühilduvus)
- valikulised rakenduslogi failid kaustas `logs/`, kui `APP_LOG_TO_FILE=true`
- valikulised päringuartefaktid kaustas `${DATA_DIR}/call_logs/`, kui kõnelogi torustik on sisse lülitatud
- armatuurlaua (dashboard) kasutusliidesed (`/api/usage/*`) UI tarbimiseks

Detailne päringu andmekoormuse jäädvustus salvestab kuni neli JSON-andmekoormuse etappi ruuditud kõne kohta:

- kliendilt saadud töötlemata päring
- tõlgitud päring, mis tegelikult upstream-i saadeti
- pakkuja vastus, taastatud JSON-ina; voogesitatud vastused pakitakse kokku lõppkokkuvõtteks pluss voo metaandmed
- OmniRoute'i tagastatud lõplik kliendivastus; voogesitatud vastused salvestatakse samal kokkupakitud kokkuvõtte kujul

## Turvatundlikud piirid

- JWT saladus (`JWT_SECRET`) tagab töölaua seansi küpsise kontrollimise/allkirjastamise turvalisuse
- Esmase parooli algseadistus (`INITIAL_PASSWORD`) tuleks esmakäivituse jaoks selgesõnaliselt konfigureerida
- API-võtme HMAC saladus (`API_KEY_SECRET`) tagab genereeritud kohaliku API-võtme formaadi turvalisuse
- Teenusepakkuja saladused (API-võtmed/tokenid) salvestatakse kohalikku andmebaasi ja need tuleks failisüsteemi tasemel kaitsta
- Pilvesünkroonimise lõpp-punktid põhinevad API-võtme autentimisel + masina ID semantikal

## Keskkonna ja käitusaja maatriks

Koodis aktiivselt kasutatavad keskkonnamuutujad:

- Rakendus/autentimine: `JWT_SECRET`, `INITIAL_PASSWORD`
- Salvestus: `DATA_DIR`
- Valikuline salvestuse baasi ülekirjutus (Linux/macOS, kui `DATA_DIR` on määramata): `XDG_CONFIG_HOME`
- Turva räsimine: `API_KEY_SECRET`, `MACHINE_ID_SALT`
- Logimine: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`
- Sünkroonimise/pilve URL-id: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
- Väljuv puhverserver: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` ja väiketäht-variandid
- SOCKS5 funktsioonilipud: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
- Platvormi/käitusaja abistajad (ei ole rakendusepõhine konfiguratsioon): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`

## Tuntud arhitektuurilised märkused

1. `usageDb` ja `localDb` jagavad sama baaskataloogi põhimõtet (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) koos pärandfailide migratsiooniga.
2. `/api/v1/route.ts` delegeerib samale ühtsele kataloogiehitajale, mida kasutab `/api/v1/models` (`src/app/api/v1/models/catalog.ts`), et vältida semantilist lahknevust.
3. Päringulogija kirjutab kui lubatud, täielikud päised/kehad; käsitle logikataloogi kui tundlikku.
4. Pilve käitumine sõltub õigest `NEXT_PUBLIC_BASE_URL` väärtusest ja pilve lõpp-punkti kättesaadavusest.
5. Kataloog `open-sse/` avaldatakse **npm workspace paketina** `@omniroute/open-sse`. Lähtekood impordib seda kaudu `@omniroute/open-sse/...` (lahendatakse Next.js `transpilePackages` abil). Selle dokumendi failiteed kasutavad järjepidevuse huvides jätkuvalt kataloogi nime `open-sse/`.
6. Töölaua diagrammid kasutavad **Recharts**'i (SVG-põhine) juurdepääsetavate, interaktiivsete analüütikavisualisatsioonide jaoks (mudeli kasutuse tulpdiagrammid, teenusepakkujate jaotuse tabelid õnnestumismääradega).
7. E2E testid kasutavad **Playwright**'it (`tests/e2e/`), käivitatakse käsuga `npm run test:e2e`. Ühiktestid kasutavad **Node.js test runner**'it (`tests/unit/`), käivitatakse käsuga `npm run test:unit`. Lähtekood kataloogis `src/` on **TypeScript** (`.ts`/`.tsx`); `open-sse/` workspace jääb JavaScript'iks (`.js`).
8. Seadete leht on jaotatud 7 vahelehele: General, Appearance, AI, Security, Routing, Resilience, Advanced. Resilience leht konfigureerib ainult päringujärjekorra, ühenduse jahtumisaja, teenusepakkuja katkestaja (breaker) ja jahtumisaja-ootamise käitumise; katkestaja käituse hetkeseisu näidatakse Health lehel.
9. **Context Relay** strateegia (`context-relay`) on jaotatud kahe kihi vahel: `combo.ts` otsustab, kas üleandmine (handoff) tuleks genereerida, `chat.ts` süstib üleandmise pärast konto lahendamist. Üleandmisandmed elavad `context_handoffs` SQLite tabelis. See jaotus on tahtlik, sest ainult `chat.ts` teab, kas tegelik konto muutus.
10. **Puhverserveri jõustamine** on nüüd põhjalik: `tokenHealthCheck.ts` lahendab puhverserveri ühenduse põhiselt, `/api/providers/validate` kasutab `runWithProxyContext`, ja `proxyFetch.ts` kasutab `undici.fetch()`, et säilitada dispetšeri ühilduvus Node 22-l.
11. **Node.js käitusaja poliitika tuvastamine**: `/api/settings/require-login` tagastab väljad `nodeVersion` ja `nodeCompatible`. Sisselogimislehel kuvatakse hoiatusriba, kui käitusaeg jääb väljapoole toetatud turvaliste Node.js liinide vahemikku.

## Toimimise kontrollnimekiri

- Ehita lähtekoodist: `npm run build`
- Ehita Docker'i pilt: `docker build -t omniroute .`
- Käivita teenus ja kontrolli:
- `GET /api/settings`
- `GET /api/v1/models`
- CLI sihtmärgi baas-URL peaks olema `http://<host>:20128/v1`, kui `PORT=20128`