# 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 päringute marsruutimise lüüs ja juhtpaneel.
See pakub ühtset OpenAI-ga ühilduvat lõpp-punkti (`/v1/*`) ning marsruudib liiklust mitme ülesvoolupakkuja vahel, toetades teisendamist, varuvalikuid, pääsulubade värskendamist ja kasutuse jälgimist.

Põhivõimekused:

- OpenAI-ga ühilduv API-liides CLI-dele ja tööriistadele (373 pakkujat, 150 käivitusmoodulit)
- Päringute ja vastuste teisendamine eri pakkujate vormingute vahel
- Mudelikombinatsioonide varuvalik (mitme mudeli järjestus)
- Struktureeritud kombinatsioonisammud (`provider + model + connection`) koos käitusaegse järjestamisega `compositeTiers` alusel
- Kontotaseme varuvalik (mitu kontot ühe pakkuja kohta)
- Kvoodi eelkontroll ja kvooditeadlik P2C-konto valimine peamises vestlusvoos
- OAuthi ja API-võtmega pakkujaühenduste haldus (27 OAuthi pakkujamoodulit)
- Manuste genereerimine lõpp-punkti `/v1/embeddings` kaudu (18 pakkujat)
- Piltide genereerimine lõpp-punkti `/v1/images/generations` kaudu (üle 10 pakkuja, üle 20 mudeli)
- Heli transkribeerimine lõpp-punkti `/v1/audio/transcriptions` kaudu (18 pakkujat)
- Tekst-kõneks teisendus lõpp-punkti `/v1/audio/speech` kaudu (24 sisseehitatud pakkujat)
- 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 pakkujat)
- Sisu modereerimine lõpp-punkti `/v1/moderations` kaudu
- Ümberjärjestamine lõpp-punkti `/v1/rerank` kaudu
- Mõtlemismärgendite (``) parsimine arutlusmudelite jaoks
- Vastuste puhastamine range ühilduvuse tagamiseks OpenAI SDK-ga
- Rollide normaliseerimine (developer→system, system→user) pakkujateülese ühilduvuse tagamiseks
- Struktureeritud väljundi teisendamine (json_schema → Gemini responseSchema)
- Pakkujate, võtmete, aliaste, kombinatsioonide, seadete ja hinnastuse kohalik püsimälu (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õtlemiseelarve haldus (muutmata edastamine / automaatne / kohandatud / adaptiivne)
- Globaalse süsteemiviiba sisestamine
- Seansside jälgimine ja sõrmejäljestamine
- Täiustatud kontopõhine kiirusepiirang koos pakkujapõhiste profiilidega
- Kaitselüliti muster pakkujate töökindluse tagamiseks
- Päringutulva vastane kaitse mutex-lukustusega
- Allkirjapõhine päringute deduplikeerimise vahemälu
- Domeenikiht: kulureeglid, varuvalikupoliitika, lukustuspoliitika
- Konteksti edastamine: seansi üleandmise kokkuvõtted järjepidevuse säilitamiseks kontode vahetamisel
- Domeenioleku püsimälu (SQLite'i läbikirjutusega vahemälu varuvalikute, eelarvete, lukustuste ja kaitselülitite jaoks)
- Poliitikamootor päringute tsentraliseeritud hindamiseks (lukustus → eelarve → varuvalik)
- Päringute telemeetria p50/p95/p99 latentsuse koondamisega
- Kombinatsiooni sihtmärkide telemeetria ja nende ajalooline seisund väljade `combo_execution_key` / `combo_step_id` kaudu
- Korrelatsiooni-ID (X-Request-Id) läbivaks jälgimiseks
- Vastavusauditi logimine koos API-võtme põhise loobumisvõimalusega
- Hindamisraamistik LLM-ide kvaliteedi tagamiseks
- Seisundi juhtpaneel pakkujate kaitselülitite reaalajas olekuga
- MCP-server (110 tööriista) kolme transpordiviisiga (stdio/SSE/Streamable HTTP)
- A2A-server (JSON-RPC 2.0 + SSE) koos oskuste ja ülesannete elutsükliga
- Mälusüsteem (eraldamine, sisestamine, otsimine, kokkuvõtete tegemine)
- Oskuste süsteem (register, käivitaja, liivakast, sisseehitatud oskused)
- MITM-puhverserver sertifikaatide halduse ja DNS-i käsitlusega
- Viibasüstide vastane vahevara
- Viipade tihendamise konveier Cavemani, RTK, virnastatud konveierite, tihenduskombinatsioonide, keelepakettide ja analüütikaga
- ACP (Agent Communication Protocol) register
- Modulaarsed OAuthi pakkujad (22 eraldiseisvat moodulit kataloogis `src/lib/oauth/providers/`)
- Desinstallimise ja täieliku desinstallimise skriptid
- OAuthi keskkonna parandamise toiming
- WebSocketi sild OpenAI-ga ühilduvate WS-klientide jaoks (`/v1/ws`)
- Sünkroonimislubade haldus (väljastamine/tühistamine, ETag-versioonitud konfiguratsioonipaketi allalaadimine)
- GLM Thinking (`glmt`) kui esmaklassiline pakkuja eelseadistus
- Hübriidne lubade loendamine (pakkujapoolne `/messages/count_tokens` koos hinnangulise varumeetodiga)
- Mudelialiaste automaatne algväärtustamine (üle 30 puhverserveriüleste dialektide normaliseeringu käivitamisel)
- Turvaline väljaminev päringumehhanism koos SSRF-kaitse, privaatsete URL-ide blokeerimise ja seadistatavate korduskatsetega
- Jahutusperioodi arvestavad vestluspäringute korduskatsed seadistatavate `requestRetry` ja `maxRetryIntervalSec` väärtustega
- Käituskeskkonna valideerimine Zodiga käivitamisel
- Vastavusauditi v2 koos lehekülgjaotuse, pakkujate CRUD-sündmuste ja SSRF-i tõttu 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 pakkujate käivitamist, teisendamist, voogedastust, varuvalikuid 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 allsüsteemid (v3.8.0)

### A. Auto Combo mootor

Auto Combo hindab dünaamiliselt ja valib marsruutimise sihtmärke päringu ajal, mitte
tuginedes staatilisele combo definitsioonile. See toidab `auto/*` mudelite eesliite perekonda.

- Mootori sisenemispunkt: `open-sse/services/autoCombo/` (`autoComboEngine.ts`,
  `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)
- Lahendaja: `src/domain/comboResolver.ts` (`auto/` eesliite automaatne tuvastamine)
- Töölaud (Dashboard): `/dashboard/auto-combo`
- Telemeetria: `auto_combo_decisions` SQLite tabel

Peamised võimalused:

- **19 marsruutimisstrateegiat** (priority, weighted, fill-first, round-robin, P2C, random,
  least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random,
  **auto**, lkgp, context-optimized, context-relay, **fusion**, pluss tagavaratee) —
  auto on v3.8.0 pealkirjastatud lisandus; `fusion` (paneeli hargnemine + kohtuniku sünteesimine,
  `open-sse/services/fusion.ts`) on uus versioonis v3.8.36.
- **16-teguriline hindamine**: kvoot, tervis, pöördkulu, pöördlatentsus, ülesande sobivus ja
  kümme teist. Tegurite ja nende vaikimisi kaalude kanooniline tabel asub
  [`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md) — selle kordamine siin
  annaks talle teise koha vananemiseks.
- **Virtuaalne vabrik** materialiseerib efemeerseid combosid, kui vastavat nimelist comboed
  ei eksisteeri, hankides kandidaadid tervete aktiivsete teenusepakkuja ühenduste hulgast.
- **Auto eesliited**: `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`,
  `auto/smart`, `auto/lkgp` — igaüks on toestatud häälestatud kaaluprofiiliga.
- **6 režiimipakki**: `ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`,
  `reliability-first` ja `chaos-mode` — eelseadistatud kaalukonfiguratsioonid, mida saab
  töölaualt (dashboard) käivitada. (Ei tule segi ajada ülalmainitud `auto/*` eesliidetega,
  mis on päringuaja variandid.)

Täieliku algoritmilise detaili jaoks (tegurite valemid, kaalude häälestamine), vaata
[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).

### B. Pilveagendid (Cloud Agents)

Cloud Agents mähib kolmandate osapoolte majutatud kood-agenti platvormid (Codex Cloud, Devin,
Jules) ühtse andmebaasipõhise ülesande elutsükli taha. Kõik ülesande loomise/kontrollimise
lõpp-punktid vajavad haldusautentimist.

- Mooduli juur: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`,
  `types.ts`, `db.ts`, pluss agendipõhised alamkataloogid `agents/` alla)
- Agendipõhised implementatsioonid: `agents/codex/`, `agents/devin/`, `agents/jules/`
- Avalikud lõpp-punktid: `/api/v1/agents/tasks/*` (list/create/get/cancel)
- Halduslõpp-punktid: `/api/cloud/*` (provisioneerimine, olek, partii)
- Töölaud (Dashboard): `/dashboard/cloud-agents`
- Salvestus: `cloud_agent_tasks` tabel

Agendipõhise provisioneerimise ja OAuth spetsiifika jaoks, vaata
[`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).

### C. Turvapiirded (Guardrails)

Turvapiirete moodul on kuumtaaslaetav vahekihi (middleware) kiht, mis kontrollib päringuid
ja vastuseid PII, viipainjektsiooni (prompt injection) ja ohtliku visuaalse sisu suhtes.
Rikkumised lühistavad päringu HTTP koodiga **503** pluss struktureeritud veakoodiga, võimaldades
allavoolu kutsujatel korrata või hargnema.

- Mooduli juur: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`,
  `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)
- Kuumtaaslaadimine: registry jälgib konfiguratsiooni muutusi ja ehitab ahela otse ümber
- Sisselülituspunktid: vestluse käitleja sisenemispunkt, pildigeneraatori käitleja, vastuse desinfitseerija
- HTTP lepe: rikkumised kuvatakse kui `503` koos `error.code = "GUARDRAIL_VIOLATION"`

Reeglistiku koostamiseks ja piirmäärade häälestamiseks, vaata
[`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).

### D. Domeenikiht

`src/domain/` nimeruum tsentraliseerib poliitikaotsused, et marsruudikäitlejad
ei peaks lockout/eelarve/tagavara loogikat ise kokku panema.

- Poliitikamootor: `src/domain/policyEngine.ts` — üks sisenemispunkt
  eelnevaks täitmise hindamiseks (lockout → eelarve → tagavara järjestus)
- Kulureeglid: `src/domain/costRules.ts`
- Tagavarapoliitika: `src/domain/fallbackPolicy.ts`
- Lockout poliitika: `src/domain/lockoutPolicy.ts`
- Märgipõhine marsruutimine: `src/domain/tagRouter.ts`
- Combo lahendaja: `src/domain/comboResolver.ts` — lahendab combo nimed, auto/\*
  eesliited ja metamärgi (wildcard) mudeli sihtmärgid konkreetseteks täitmisplaanideks
- Ühenduse/mudelireeglite liitja: `src/domain/connectionModelRules.ts`
- Mudelite saadavuse hetktõmmised: `src/domain/modelAvailability.ts`
- Teenusepakkuja aegumise jälgimine: `src/domain/providerExpiration.ts`
- Kvoodivahemälu: `src/domain/quotaCache.ts`
- Degradatsiooni olek: `src/domain/degradation.ts`
- Konfiguratsiooni audit: `src/domain/configAudit.ts`
- OmniRoute vastuse metaandmete ehitaja: `src/domain/omnirouteResponseMeta.ts`
- Hindamise allsüsteem: `src/domain/assessment/` — perioodilised hindamistööd

### E. Autoriseerimise torujuhe

Autoriseerimise torujuhe klassifitseerib igat sisenevat päringut ja rakendab
enne edastamist sobiva poliitikaahela.

- Torujuhtme sisenemispunkt: `src/server/authz/pipeline.ts`
- Päringu klassifitseerija: `src/server/authz/classify.ts` — eristab avalikud
  ühilduvusmarsruudid haldusmarsruutidest
- Avalike marsruutide loend: `src/shared/constants/publicApiRoutes.ts`
- Poliitikad: `src/server/authz/policies/` — kombineeritavad predikaadid
  (`requireApiKey`, `requireManagement`, `requireFreshAuth` jne)
- Päise utiliidid: `src/server/authz/headers.ts`
- Väite abifunktsioon: `src/server/authz/assertAuth.ts`
- Päringu kontekst: `src/server/authz/context.ts`

Avalikud vs halduslikud marsruudid on kõva piir: agendi/jahtumisaja (cooldown) API-d ja
teenusepakkuja mutatsioonid vajavad haldusautentimist (HTTP 401, kui puudub).

Täieliku marsruudi klassifikatsiooni reeglite jaoks, vaata
[`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).

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

Lõplike olekute masinaga (finite-state-machine) juhitud marsruuter, mis on
kihistatud combo valiku peale, et suunata liiklust tuvastatud töövoo etapi
(planeerimine, täitmine, ülevaatamine) ja taustülesande sobivuse põhjal.

- Töövoo FSM: `open-sse/services/workflowFSM.ts`
- Ülesandeteadlik marsruuter: `open-sse/services/taskAwareRouter.ts`
- Taustülesande detektor: `open-sse/services/backgroundTaskDetector.ts`
- Kavatsuse klassifitseerija: `open-sse/services/intentClassifier.ts`

FSM üleminekud toidavad Auto Combo hindamist, kaldudes odavamate mudelite poole
taust-/automatiseerimisülesannete jaoks ja tugevamate mudelite poole interaktiivsete
planeerimis-/ülevaatuskordade jaoks.

### G. Teenusepakkujaspetsiifiline vastupidavus

Mitmed teenusepakkujad tarnivad pühendatud vastupidavuse ja varjatuse (stealth) mooduleid,
mis toetuvad globaalsele lülitusahela / ühenduse jahtumisaja / mudeli lockout kihtidele:

- Antigravity 429 mootor: `open-sse/services/antigravity429Engine.ts` (rotereerib
  identiteeti, puhastab vastuse päised, juhib krediitide/versiooni jälgimist läbi
  `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`,
  `antigravityIdentity.ts`, `antigravityVersion.ts`)
- ModelScope kvoodipoliitika: `open-sse/services/modelscopePolicy.ts`
- Claude Code CCH (Compatibility Channel Handshake): `open-sse/services/claudeCodeCCH.ts`,
  pluss `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`,
  `claudeCodeToolRemapper.ts`
- Claude Code sõrmejälje kujundamine: `open-sse/services/claudeCodeFingerprint.ts`
- Claude Code hägustamine (obfuscation): `open-sse/services/claudeCodeObfuscation.ts`

Täieliku varjatuse (stealth) mänguplaani ja operatiivsete juhiste jaoks, vaata
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).

### H. Veebihaagised (Webhooks), arutlusvahemälu, lugemisvahemälu

- **Veebihaagised (Webhooks)** — väljuv dispetšeerimine teenusepakkuja/konto/ülesande
  sündmuste jaoks.
  - Dispetšer: `src/lib/webhookDispatcher.ts`
  - Salvestus: `webhooks` SQLite tabel (läbi `src/lib/db/webhooks.ts`)
  - Töölaud (Dashboard): `/dashboard/webhooks` (tellimused, saladused, korduskatsete ajalugu)
  - Sündmuste taksonoomia ja korduskatsete semantika jaoks, vaata [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).
- **Arutlusvahemälu (Reasoning Cache)** — taasesitatavad arutlusplokid teenusepakkujatele,
  mis väljastavad mõttemärke (thinking tokens) (Claude, GLMT jne), et järjestikused
  vooru käigud saaksid vahele jätta korduva mõtlemise.
  - Andmebaasi kiht: `src/lib/db/reasoningCache.ts`
  - Teenusekiht: `open-sse/services/reasoningCache.ts`
  - Taasesitamise semantika jaoks, vaata [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).
- **Lugemisvahemälu (Read Cache)** — allkirja alusel indekseeritud lühiealine vastuse
  vahemälu, mida kasutatakse identsete korduskatsete kokkusurumiseks katkistelt
  ülemvoolu SDK-delt.
  - Andmebaasi kiht: `src/lib/db/readCache.ts`
  - Statistika lõpp-punkt: `GET /api/cache/stats`, töölaud (dashboard) 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) Autentimise ja turvalisuse pinnad

- Töölaua küpsisepõhine autentimine: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
- API-võtme genereerimine/kontrollimine: `src/shared/utils/apiKey.ts`
- Pakkuja saladused salvestatakse `providerConnections` kirjetesse
- Väljuva liikluse proksitugi läbi `open-sse/utils/proxyFetch.ts` (keskkonnamuutujad) ja `open-sse/utils/networkProxy.ts` (konfigureeritav pakkuja kaupa või globaalselt)
- SSRF / väljuva URL-i kaitse: `src/shared/network/outboundUrlGuard.ts` — blokeerib privaatsed/loopback/link-local vahemikud kõikide pakkuja kõnede puhul
- Käitusaja keskkonnamuutujate valideerimine: `src/lib/env/runtimeEnv.ts` — Zod-skeem kõigi keskkonnamuutujate jaoks, mis kuvatakse käivituse vigade/hoiatustena
- Sünkroonimistoetused (sync tokens): `src/lib/db/syncTokens.ts` — piiratud ulatusega toetused konfiguratsioonipaketi allalaadimise lõpp-punktide jaoks; toetatud `sync_tokens` SQLite tabeliga (migratsioon `024_create_sync_tokens.sql`)
- WebSocketi käepigistuse (handshake) autentimine: `src/lib/ws/handshake.ts` — valideerib WS-i uuenduspäringuid API-võtme või seansiküpsise abil

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