# 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 Next.js-il põhinev kohalik tehisintellekti marsruutimislüüs ja juhtpaneel.
See pakub ühtset OpenAI-ga ühilduvat lõpp-punkti (`/v1/*`) ning marsruudib liiklust mitme ülesvoolu teenusepakkuja vahel, toetades teisendamist, varuvarianti, tokenite värskendamist ja kasutuse jälgimist.

Põhifunktsioonid:

- OpenAI-ga ühilduv API-liides CLI-le ja tööriistadele (375 teenusepakkujat, 156 täiturmoodulit)
- Päringute ja vastuste teisendamine teenusepakkujate vormingute vahel
- Mudelikombinatsioonide varuvariandid (mitme mudeli jada)
- Struktureeritud kombinatsioonisammud (`provider + model + connection`) käitusaegse järjestamisega välja `compositeTiers` alusel
- Kontotaseme varuvariandid (mitu kontot teenusepakkuja kohta)
- Kvoodi eelkontroll ja kvooditeadlik P2C-konto valimine vestluse põhivoos
- OAuthi ja API-võtmetega teenusepakkujaühenduste haldus (27 OAuthi teenusepakkujamoodulit)
- Manuste genereerimine lõpp-punkti `/v1/embeddings` kaudu (18 teenusepakkujat)
- Piltide genereerimine lõpp-punkti `/v1/images/generations` kaudu (üle 10 teenusepakkuja, üle 20 mudeli)
- Heli transkribeerimine lõpp-punkti `/v1/audio/transcriptions` kaudu (18 teenusepakkujat)
- Tekstist kõne süntees lõpp-punkti `/v1/audio/speech` kaudu (24 sisseehitatud teenusepakkujat)
- Video genereerimine lõpp-punkti `/v1/videos/generations` kaudu (ComfyUI + SD WebUI)
- Muusika genereerimine lõpp-punkti `/v1/music/generations` kaudu (ComfyUI)
- Veebiotsing lõpp-punkti `/v1/search` kaudu (20 teenusepakkujat)
- Sisu modereerimine lõpp-punkti `/v1/moderations` kaudu
- Ümberjärjestamine lõpp-punkti `/v1/rerank` kaudu
- Mõttekäigumärgendite sõelumine (``) arutlusmudelite jaoks
- Vastuste puhastamine range ühilduvuse tagamiseks OpenAI SDK-ga
- Rollide normaliseerimine (developer→system, system→user) teenusepakkujatevahelise ühilduvuse tagamiseks
- Struktureeritud väljundi teisendamine (json_schema → Gemini responseSchema)
- Teenusepakkujate, võtmete, pseudonüümide, kombinatsioonide, sätete ja hinnastuse kohalik püsitalletus (122 andmebaasimoodulit)
- Kasutuse ja kulude jälgimine ning päringute logimine
- Valikuline pilvesünkroonimine mitme seadme ja oleku sünkroonimiseks
- IP-aadresside lubamis- ja blokeerimisloend API juurdepääsu juhtimiseks
- Mõtlemise eelarve haldus (muutmata edastus / automaatne / kohandatud / adaptiivne)
- Globaalse süsteemiviiba lisamine
- Seansside jälgimine ja sõrmejäljestamine
- Kontopõhine täiustatud päringusageduse piiramine teenusepakkujapõhiste profiilidega
- Kaitselüliti muster teenusepakkujate töökindluse tagamiseks
- Päringutulva vastane kaitse mutex-lukustusega
- Allkirjapõhine päringute deduplikeerimise vahemälu
- Domeenikiht: kulureeglid, varuvariandi poliitika, lukustuspoliitika
- Context Relay: seansi üleandmise kokkuvõtted järjepidevuse säilitamiseks kontode vahetamisel
- Domeenioleku püsitalletus (SQLite'i läbikirjutusega vahemälu varuvariantide, eelarvete, lukustuste ja kaitselülitite jaoks)
- Poliitikamootor päringute tsentraliseeritud hindamiseks (lukustus → eelarve → varuvariant)
- Päringute telemeetria p50/p95/p99 latentsuse koondamisega
- Kombinatsiooni sihtmärgi telemeetria ja kombinatsiooni sihtmärkide ajalooline seisund väljade `combo_execution_key` / `combo_step_id` kaudu
- Korrelatsiooni-ID (X-Request-Id) läbivjälgimiseks
- Nõuetele vastavuse auditilogimine koos API-võtmepõhise loobumisvõimalusega
- Hindamisraamistik LLM-i kvaliteedi tagamiseks
- Seisundi juhtpaneel teenusepakkujate kaitselülitite reaalajaolekuga
- MCP-server (110 tööriista) 3 transpordiga (stdio/SSE/voogedastatav HTTP)
- A2A-server (JSON-RPC 2.0 + SSE) oskuste ja ülesande elutsükliga
- Mälusüsteem (eraldamine, lisamine, otsing, kokkuvõtete tegemine)
- Oskuste süsteem (register, täitur, liivakast, sisseehitatud oskused)
- MITM-puhverserver sertifikaatide halduse ja DNS-i käsitlusega
- Viibasüstide vastane vahevarakiht
- Viipade tihendamise konveier Cavemani, RTK, virnastatud konveierite, tihenduskombinatsioonide, keelepakettide ja analüütikaga
- ACP (Agent Communication Protocol) register
- Modulaarsed OAuthi teenusepakkujad (22 eraldi moodulit kataloogis `src/lib/oauth/providers/`)
- Desinstallimise ja täieliku desinstallimise skriptid
- OAuthi keskkonna parandamise toiming
- WebSocketi sild OpenAI-ga ühilduvatele WS-klientidele (`/v1/ws`)
- Sünkroonimistokenite haldus (väljastamine/tühistamine, ETag-versioonitud konfiguratsioonipaketi allalaadimine)
- GLM Thinking (`glmt`) esmatasandi teenusepakkuja eelseadistus
- Hübriidne tokenite loendamine (teenusepakkujapoolne `/messages/count_tokens` koos hinnangulise varumeetodiga)
- Mudelite pseudonüümide automaatne algväärtustamine (üle 30 puhverserveritevahelise dialekti normaliseerimise käivitamisel)
- Turvaline väljaminev fetch SSRF-kaitse, privaatsete URL-ide blokeerimise ja konfigureeritava korduskatsega
- Jahtumisperioodi arvestavad vestluse korduskatsed konfigureeritavate väärtustega `requestRetry` ja `maxRetryIntervalSec`
- Käituskeskkonna valideerimine Zodiga käivitamisel
- Nõuetele vastavuse audit v2 lehekülgjaotuse, teenusepakkujate CRUD-sündmuste ja SSRF-i blokeeritud valideerimiste logimisega

Peamine käitusmudel:

- Next.js-i rakenduse marsruudid kataloogis `src/app/api/*` rakendavad nii juhtpaneeli API-sid kui ka ühilduvus-API-sid
- Jagatud SSE- ja marsruutimistuumik kataloogides `src/sse/*` + `open-sse/*` haldab teenusepakkujate käivitamist, teisendamist, voogedastust, varuvariante ja kasutust

## 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)

## Töölaua pinnapealne ülevaade (praegune)

Peamised lehed kausta `src/app/(dashboard)/dashboard/` alt:

- `/dashboard` — kiirstart + teenusepakkujate ülevaade
- `/dashboard/endpoint` — lõpp-punkti proxy + MCP + A2A + API lõpp-punkti sakid
- `/dashboard/providers` — teenusepakkuja ühendused ja mandaadid
- `/dashboard/combos` — kombo strateegiad, mallid, sammupõhine koostaja, mudeli suunamisreeglid, käsitsi säilitatud järjestus
- `/dashboard/auto-combo` — Auto Combo mootor: skoorimiskaalud, režiimipakid, virtuaalse tootmise eelseaded, telemeetria
- `/dashboard/costs` — kulude koondamine ja hinnastuse nähtavus
- `/dashboard/analytics` — kasutusanalüütika, hindamised, kombo sihtmärkide tervis
- `/dashboard/limits` — kvoodi/kiirusepiirangute kontroll
- `/dashboard/cli-tools` — CLI kasutuselevõtt, käitusaja tuvastamine, konfiguratsiooni genereerimine
- `/dashboard/agents` — tuvastatud ACP agendid + kohandatud agendi registreerimine
- `/dashboard/cloud-agents` — pilves majutatud agendi ülesanded (Codex Cloud, Devin, Jules) ja ülesande eluring
- `/dashboard/skills` — A2A oskuste registreerimine, sandbox täitmine, sisseehitatud oskuste katalog
- `/dashboard/memory` — püsiva vestlusmälu ülevaatus ja pärimine
- `/dashboard/webhooks` — väljuvad veebihaagi (webhook) tellimused, saladuste rotatsioon, uuestisaatmise statistika
- `/dashboard/batch` — partii tööde esitamine ja edenemine
- `/dashboard/cache` — läbilugemise ja põhjendamise puhvri (cache) statistika, eemaldamise kontrollid
- `/dashboard/playground` — interaktiivne vestluse mänguväljak vastu suvalise seadistatud kombo/mudeli
- `/dashboard/changelog` — rakendusesisene muudatuste logi vaatur (renderdab `CHANGELOG.md`)
- `/dashboard/system` — käitusaja diagnostika, versiooniinfo, keskkonna valideerimise pind
- `/dashboard/onboarding` — esmakordse käivituse seadistusviisard uute paigalduste jaoks
- `/dashboard/media` — pildi/video/muusika mänguväljak
- `/dashboard/search-tools` — otsingu teenusepakkuja testimine ja ajalugu
- `/dashboard/health` — töövalmisolek (uptime), kaitseahelad, kiirusepiirangud, kvoodiga jälgitud seansid
- `/dashboard/logs` — päringute/proxy/audit/konsooli logid
- `/dashboard/settings` — süsteemi seadete sakid (üldine, suunamine, kombo vaikeväärtused jne)
- `/dashboard/context/caveman` — Caveman'i tihendamise reeglid, keelepakid, eelvaade ja väljundrežiim
- `/dashboard/context/rtk` — RTK käsu väljundi filtrid, eelvaade ja käitusaja turvaseaded
- `/dashboard/context/combos` — nimega tihendamise torustikud, mis on omistatud suunamiskombodele
- `/dashboard/translator` — tõlkija ülevaatus ja päringuvormingu teisendamise eelvaade
- `/dashboard/audit` — vastavuse auditilogi sirvija koos leheküljestamise ja struktureeritud metaandmetega
- `/dashboard/usage` — üksikpäringute kasutuse sirvija, seotud `usage_history`-ga
- `/dashboard/compression` — tihendamise analüütika, statistika ja torustiku omistamine
- `/dashboard/api-manager` — API võtme eluring ja mudeliõigused

## 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. Auto Combo mootor

Auto Combo hindab dünaamiliselt marsruutimissihtmärke ja valib need päringu ajal, selle asemel et
tugineda staatilisele combo definitsioonile. See käitab mudeliprefiksite perekonda `auto/*`.

- Mootori sisenemispunkt: `open-sse/services/autoCombo/` (`autoComboEngine.ts`,
  `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)
- Lahendaja: `src/domain/comboResolver.ts` (`auto/` prefiksi automaatne tuvastamine)
- Juhtpaneel: `/dashboard/auto-combo`
- Telemeetria: SQLite'i tabel `auto_combo_decisions`

Põhivõimalused:

- **20 marsruutimisstrateegiat** (prioriteet, kaalutud, esmalt täitmine, ringsuunamine, P2C, juhuslik,
  vähim kasutatud, kuludele optimeeritud, lähtestamisteadlik, lähtestusaken, varuruum, kvoodiga kaalutud,
  rangelt juhuslik, **auto**, lkgp, kontekstile optimeeritud, vahemälule optimeeritud, kontekstiedastus, **fusion**,
  konveier) —
  auto on versiooni v3.8.0 olulisim täiendus; `fusion` (paneelile hajutamine + kohtunikupoolne süntees,
  `open-sse/services/fusion.ts`) lisandus versioonis v3.8.36.
- **16 teguriga hindamine**: kvoot, tervislik seisund, pöördkulu, pöördlatentsus, ülesandega sobivus ja
  veel kümme tegurit. Tegurite ja nende vaikekaalude kanooniline tabel asub failis
  [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md) — selle siin uuesti esitamine
  looks teise koha, kus see võib aeguda.
- **Virtuaalne tehas** loob efemeerseid combo'sid, kui sobivat nimega combo't
  ei leidu, hankides kandidaadid aktiivsetest ja töökorras teenusepakkuja ühendustest.
- **Automaatsed prefiksid**: `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`,
  `auto/smart`, `auto/lkgp` — igaüht toetab häälestatud kaaluprofiil.
- **6 režiimipaketti**: `ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`,
  `reliability-first` ja `chaos-mode` — eelseadistatud kaalude konfiguratsioonid, mida saab käivitada
  juhtpaneelilt. (Neid ei tohi segi ajada ülaltoodud `auto/*` prefiksitega, mis on
  päringu ajal rakendatavad variandid.)

Täielikud algoritmilised üksikasjad (tegurite valemid, kaalude häälestamine) leiate failist
[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).

### B. Pilveagendid

Pilveagendid koondavad kolmandate poolte majutatud koodiagendi platvormid (Codex Cloud, Devin,
Jules) ühtse andmebaasipõhise ülesande elutsükli taha. Kõik ülesannete loomise ja kontrollimise
otspunktid nõuavad haldusautentimist.

- Mooduli juurkataloog: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`,
  `types.ts`, `db.ts` ning agendipõhised alamkataloogid kataloogis `agents/`)
- Agendipõhised teostused: `agents/codex/`, `agents/devin/`, `agents/jules/`
- Avalikud otspunktid: `/api/v1/agents/tasks/*` (loendamine/loomine/hankimine/tühistamine)
- Haldusotspunktid: `/api/cloud/*` (ettevalmistamine, olek, pakktöötlus)
- Juhtpaneel: `/dashboard/cloud-agents`
- Salvestusruum: tabel `cloud_agent_tasks`

Agendipõhise ettevalmistamise ja OAuthi üksikasjad leiate failist
[`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).

### C. Kaitsepiirded

Kaitsepiirete moodul on käigult taaslaaditav vahevarakiht, mis kontrollib päringuid
ja vastuseid isikut tuvastava teabe, viibainjektsiooni ning ohtliku visuaalse sisu suhtes. Rikkumised
katkestavad päringu HTTP-koodiga **503** koos struktureeritud veakoodiga, võimaldades
allavoolu kutsujatel päringut korrata või valida muu haru.

- Mooduli juurkataloog: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`,
  `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)
- Käigult taaslaadimine: register jälgib konfiguratsioonimuudatusi ja loob ahela kohapeal uuesti
- Ühenduspunktid: vestlustöötleja sisenemispunkt, pildiloome töötleja, vastuse puhastaja
- HTTP-leping: rikkumised kuvatakse koodiga `503` ja väärtusega `error.code = "GUARDRAIL_VIOLATION"`

Reeglistike koostamise ja lävendite häälestamise kohta vaadake faili
[`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).

### D. Domeenikiht

Nimeruum `src/domain/` tsentraliseerib poliitikaotsused, et marsruuditöötlejad ei peaks
lukustuse, eelarve ja varuvariandi loogikat ise koostama.

- Poliitikamootor: `src/domain/policyEngine.ts` — üks sisenemispunkt
  käivituseelseks hindamiseks (lukustus → eelarve → varuvariandi järjestus)
- Kulureeglid: `src/domain/costRules.ts`
- Varuvariandi poliitika: `src/domain/fallbackPolicy.ts`
- Lukustuspoliitika: `src/domain/lockoutPolicy.ts`
- Sildipõhine marsruutimine: `src/domain/tagRouter.ts`
- Combo lahendaja: `src/domain/comboResolver.ts` — lahendab combo nimed, auto/\*
  prefiksid ja metamärgiga mudelisihtmärgid konkreetseteks käivitusplaanideks
- Ühenduse/mudeli reeglite ühendaja: `src/domain/connectionModelRules.ts`
- Mudeli saadavuse hetktõmmised: `src/domain/modelAvailability.ts`
- Teenusepakkuja aegumise jälgimine: `src/domain/providerExpiration.ts`
- Kvoodivahemälu: `src/domain/quotaCache.ts`
- Degradeerumisolek: `src/domain/degradation.ts`
- Konfiguratsiooniaudit: `src/domain/configAudit.ts`
- OmniRoute'i vastuse metaandmete koostaja: `src/domain/omnirouteResponseMeta.ts`
- Hindamise alamsüsteem: `src/domain/assessment/` — perioodilised hindamistööd

### E. Autoriseerimiskonveier

Autoriseerimiskonveier liigitab iga sissetuleva päringu ja rakendab enne
edasisaatmist sobiva poliitikaahela.

- Konveieri sisenemispunkt: `src/server/authz/pipeline.ts`
- Päringute liigitaja: `src/server/authz/classify.ts` — eristab avalikke
  ühilduvusmarsruute haldusmarsruutidest
- Avalike marsruutide loend: `src/shared/constants/publicApiRoutes.ts`
- Poliitikad: `src/server/authz/policies/` — kombineeritavad predikaadid
  (`requireApiKey`, `requireManagement`, `requireFreshAuth` jne)
- Päiseutiliidid: `src/server/authz/headers.ts`
- Kontrolli abifunktsioon: `src/server/authz/assertAuth.ts`
- Päringukontekst: `src/server/authz/context.ts`

Avalike ja haldusmarsruutide vahel on jäik piir: agentide/jahtumisaja API-d ja
teenusepakkuja muudatused nõuavad haldusautentimist (selle puudumisel HTTP 401).

Täielikud marsruutide liigitamise reeglid leiate failist
[`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).

### F. Töövoo FSM ja ülesandeteadlik marsruuter

Lõpliku olekumasina juhitud marsruuter, mis paikneb combo valiku kohal ning suunab
liikluse tuvastatud töövoo etapi (plaanimine, täitmine,
ülevaatus) ja taustülesande seotuse põhjal.

- Töövoo FSM: `open-sse/services/workflowFSM.ts`
- Ülesandeteadlik ruuter: `open-sse/services/taskAwareRouter.ts`
- Taustülesannete tuvastaja: `open-sse/services/backgroundTaskDetector.ts`
- Kavatsuse klassifikaator: `open-sse/services/intentClassifier.ts`

FSM-i olekusiirded mõjutavad Auto Combo punktiarvestust, eelistades tausta- ja automatiseerimisülesannete puhul odavamaid mudeleid ning interaktiivsete plaanimis- ja ülevaatusvoorude puhul võimekamaid mudeleid.

### G. Pakkujapõhine vastupidavus

Mitmel pakkujal on spetsiaalsed vastupidavus- ja varjamismoodulid, mis kasutavad globaalseid kaitselüliti, ühenduse ooteaja ja mudeli lukustamise kihte:

- Antigravity 429 mootor: `open-sse/services/antigravity429Engine.ts` (vahetab identiteeti,
  puhastab vastuse päised ning haldab krediitide ja versioonide jälgimist moodulite
  `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`,
  `antigravityIdentity.ts`, `antigravityVersion.ts` kaudu)
- ModelScope'i kvoodipoliitika: `open-sse/services/modelscopePolicy.ts`
- Claude Code'i CCH (ühilduvuskanali kätlus): `open-sse/services/claudeCodeCCH.ts`,
  lisaks `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`,
  `claudeCodeToolRemapper.ts`
- Claude Code'i sõrmejälje kujundamine: `open-sse/services/claudeCodeFingerprint.ts`
- Claude Code'i hägustamine: `open-sse/services/claudeCodeObfuscation.ts`

Täielikku varjamise juhendit ja käitussoovitusi vaadake failist
`docs/security/STEALTH_GUIDE.md` (git; ei kompileerita kataloogi `/docs`).

### H. Veebihaagid, arutluskäikude vahemälu, lugemisvahemälu

- **Veebihaagid** — pakkuja-, konto- ja ülesandesündmuste väljaminev edastus.
  - Dispetšer: `src/lib/webhookDispatcher.ts`
  - Salvestus: SQLite'i tabel `webhooks` (faili `src/lib/db/webhooks.ts` kaudu)
  - Töölaud: `/dashboard/webhooks` (tellimused, saladused, korduskatsete ajalugu)
  - Sündmuste taksonoomiat ja korduskatsete semantikat vaadake failist [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Arutluskäikude vahemälu** — taasesitatavad arutlusplokid pakkujatele, mis väljastavad
  mõtlemislubasid (Claude, GLMT jne), et järjestikustes voorudes saaks uuesti mõtlemise vahele jätta.
  - Andmebaasikiht: `src/lib/db/reasoningCache.ts`
  - Teenusekiht: `open-sse/services/reasoningCache.ts`
  - Taasesituse semantikat vaadake failist [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Lugemisvahemälu** — signatuuri järgi võtmetatud lühiajaline vastuste vahemälu, mida kasutatakse
  vigaste ülesvoolu SDK-de identsete korduskatsete koondamiseks.
  - Andmebaasikiht: `src/lib/db/readCache.ts`
  - Statistika otspunkt: `GET /api/cache/stats`, töölaud aadressil `/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`