# OmniRoute Codebase Documentation (Slovenčina)

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

---

> **Verzia:** v3.8.51
> **Posledná aktualizácia:** 2026-06-28
> **Pre koho:** Inžinieri prispievajúci do OmniRoute alebo vytvárajúci integrácie nad ním.
>
> Diagramy architektúry na vysokej úrovni a odôvodnenie jednotlivých subsystémov nájdete v súbore
> [ARCHITECTURE.md](./ARCHITECTURE.md). Podrobné informácie o jednotlivých subsystémoch
> (Auto Combo, server MCP, server A2A, Skills, Memory, Cloud Agents, Resilience,
> Compression atď.) nájdete v ich samostatných súboroch v tomto adresári `docs/`.

Tento súbor opisuje **to, čo sa dnes nachádza v repozitári**, aby sa nový inžinier
dokázal orientovať v stromovej štruktúre, porozumel vrstvám behového prostredia a vedel, kam pridať kód
bez vytvárania nových modulov.

---

## 1. Technologický zásobník

| Oblasť                | Voľba                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Webový framework      | **Next.js 16** (App Router, samostatný výstup, bez globálneho middleware)                                                            |
| Jazyk                 | **TypeScript 6.0+** — cieľ `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                                  |
| Runtime               | **Node.js** `>=22.22.2 <23` alebo `>=24.0.0 <27` (vynútené prostredníctvom `engines` + `SUPPORTED_NODE_RANGE`)                       |
| Databáza              | **SQLite** prostredníctvom `better-sqlite3` (singleton, žurnálovanie WAL)                                                            |
| Desktop               | **Electron 41** + `electron-builder` 26.10 (samostatný pracovný priestor v `electron/`)                                              |
| Testy                 | **Natívny testovací nástroj Node** (jednotkové/integračné), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) |
| Zostavenie            | Samostatný výstup Next.js prostredníctvom `scripts/build/build-next-isolated.mjs`                                                    |
| Lint/formátovanie     | Plochá konfigurácia ESLint + Prettier (`lint-staged` prostredníctvom Husky pre-commit)                                               |
| Systém modulov        | ESM všade (`"type": "module"`)                                                                                                       |
| UI ovládacieho panela | **Tailwind CSS 4** + zahrnutý **Keak CI UI Kit** (`packages/ui-kit`), ikony Lucide — pozrite si `DESIGN_SYSTEM.md`                   |
| Pracovné priestory    | pracovné priestory npm — `open-sse`, `packages/browser-pool`, `packages/ui-kit`                                                      |

Aliasy ciest (`tsconfig.json`):

- `@/*` → `src/*`
- `@omniroute/open-sse` → `open-sse/index.ts`
- `@omniroute/open-sse/*` → `open-sse/*`
- `@omniroute/ui-kit` → `packages/ui-kit/src`, `@omniroute/ui-kit/*` → `packages/ui-kit/src/*`

Predvolený port HTTP: **`20128`** (API a ovládací panel zdieľajú rovnaký proces). Dátový
adresár je určený premennou prostredia `DATA_DIR`, pričom predvolená hodnota je `~/.omniroute/`.

---

## 2. Štruktúra repozitára

```
OmniRoute/
├── src/                  Aplikácia Next.js (App Router, knižnice, doména, server, zdieľané súčasti)
├── open-sse/             Pracovný priestor streamovacieho jadra (@omniroute/open-sse)
├── packages/             Pracovné priestory: ui-kit (integrovaná súprava Keak CI UI Kit), browser-pool
├── electron/             Obal pre desktopovú aplikáciu (hlavný proces Electron 41 + preload)
├── bin/                  Vstupné body CLI (omniroute, reset-password)
├── tests/                Jednotkové, integračné, e2e, protocols-e2e, prekladové a bezpečnostné testy, testovacie dáta
├── scripts/              Pomocné skripty pre zostavenie, synchronizáciu, kontroly, migráciu a beh aplikácie
├── docs/                 Verejná dokumentácia (tento adresár)
├── public/               Statické súbory, manifest PWA, service worker
├── config/               Ukážky konfigurácie behu aplikácie
├── images/               Marketingové materiály a snímky obrazovky
├── _ideia/, _references/, _mono_repo/, _tasks/   Interné pracovné a plánovacie materiály (nedistribuujú sa)
├── CLAUDE.md             Pravidlá repozitára pre Claude Code
├── AGENTS.md             Podrobnejší architektonický referenčný dokument pre agentov
├── package.json          v3.8.51, koreň pracovného priestoru
└── tsconfig.json         Aliasy ciest + základné možnosti kompilátora
```

---

## 3. `src/` — Aplikácia Next.js

```
src/
├── app/                  Stránky smerovača App Router + trasy API
├── lib/                  Základné knižnice (DB, autentifikácia, OAuth, zručnosti, pamäť, …)
├── domain/               Čistá doménová vrstva (politika, záložné riešenie, náklady, uzamknutie, …)
├── server/               Moduly určené iba pre server (autorizácia, CORS, autentifikácia)
├── shared/               Typy, konštanty, validácia, kontrakty, pomocné funkcie (bezpečné naprieč hranicami)
├── mitm/                 Pomocné funkcie proxy typu „man-in-the-middle“ na integráciu CLI
├── models/               Metadáta lokálnych modelov / aliasy
├── sse/                  Staršie obslužné rutiny SSE, ktoré sa stále nachádzajú v src/ (nie open-sse/)
├── store/                Úložiská stavu na strane klienta
├── middleware/           Pomocné nástroje middlewaru na úrovni trás (nie globálny middleware Next.js)
├── scripts/              Skripty v rámci stromu, ktoré môže importovať kód aplikácie
├── types/                Ambientné a zdieľané typy TS
├── i18n/                 Lokalizačné balíky
├── instrumentation.ts    Hook inštrumentácie Next.js
├── instrumentation-node.ts
└── proxy.ts              Pomocný súbor najvyššej úrovne na inicializáciu proxy
```

### 3.1 `src/app/` — App Router

App Router sprístupňuje používateľské rozhranie riadiaceho panela aj verejné/spravovacie HTTP API.
Neexistuje **žiadny globálny middleware** — zachytávanie sa vykonáva pre každú trasu samostatne.

Segmenty najvyššej úrovne v `src/app/`:

| Cesta                                                                         | Účel                                                                      |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `api/`                                                                        | Všetky trasy HTTP API (pozri rozpis nižšie)                               |
| `a2a/`                                                                        | Koncový bod A2A JSON-RPC 2.0 (`POST /a2a`)                                |
| `.well-known/agent.json/`                                                     | Dokument na zisťovanie karty agenta A2A                                   |
| `(dashboard)/`                                                                | Používateľské rozhranie riadiaceho panela (skupina trás, bez prefixu URL) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | Toky autentifikácie                                                       |
| `landing/`                                                                    | Marketingová/vstupná stránka                                              |
| `docs/`                                                                       | Zabudovaný prehliadač dokumentácie API                                    |
| `status/`, `maintenance/`, `offline/`                                         | Prevádzkové stránky                                                       |
| `privacy/`, `terms/`                                                          | Právne stránky                                                            |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | Statické chybové stránky                                                  |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Hranice chýb/načítavania frameworku                                       |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | Koreňový obal                                                             |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — Stránky používateľského rozhrania

`agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`,
`changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`,
`costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`,
`playground`, `providers`, `search-tools`, `settings`, `skills`, `system`,
`translator`, `usage`, `webhooks`, plus koreňové súbory `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — Skupiny API najvyššej úrovne

```
src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Správa zabudovaných služieb (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Verejné API kompatibilné s OpenAI
├── v1beta/     Kompatibilita v štýle Gemini
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — Správa zabudovaných služieb

Trasy na inštaláciu, spúšťanie, zastavovanie a monitorovanie služieb 9Router a CLIProxyAPI.
Všetky cesty sú klasifikované ako **LOCAL_ONLY** (iba loopback, pevné pravidlo č. 17), pretože
môžu vyvolať `npm install` a spúšťať podradené procesy.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             pomocná funkcia getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install prostredníctvom execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install novšej verzie
│   ├── rotate-key/route.ts POST — vygenerovanie nového kľúča API + reštart
│   ├── status/route.ts     GET  — aktuálny stav + stav DB + metadáta verzie
│   └── auto-start/route.ts POST — prepnutie príznaku auto_start
├── cliproxy/
│   ├── _lib.ts             pomocná funkcia getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install novšej verzie
│   ├── status/route.ts     GET  — aktuálny stav + stav DB + metadáta verzie
│   └── auto-start/route.ts POST — prepnutie príznaku auto_start
└── [name]/
    └── logs/route.ts       GET  — koniec protokolu cez SSE (zdieľaný všetkými službami)
```

Zodpovedajúce používateľské rozhranie ovládacieho panela:
`src/app/(dashboard)/dashboard/providers/services/` — stránka s dvoma kartami (CLIProxyAPI + 9Router).
Reverzný proxy server pre vložené používateľské rozhranie 9Router:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

Podrobný rozbor: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — verejné API kompatibilné s OpenAI

```
v1/
├── accounts/[id]/                       vyhľadanie účtu
├── agents/tasks/[id]/, agents/tasks/    koncové body úloh v štýle A2A
├── api/                                 interné pomocné funkcie API sprístupnené pod v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API OpenAI Batches
├── chat/completions/                    Chat Completions (hlavný koncový bod)
├── completions/                         staršie textové dokončovania
├── embeddings/                          vektorové reprezentácie
├── files/[id]/, files/                  API súborov
├── _helpers/                            zdieľané pomocné funkcie trás (bez verejnej URL)
├── images/{edits, generations}/         generovanie + úprava obrázkov
├── issues/                              pomocné koncové body na triedenie problémov
├── management/{proxies}/                trasy s rozsahom správy v rámci v1
├── messages/{count_tokens}/             kompatibilita správ v štýle Anthropic
├── models/                              zoznam modelov (`route.ts`, `catalog.ts`)
├── moderations/                         moderovanie
├── music/                               generovanie hudby
├── providers/[provider]/                operácie jednotlivých poskytovateľov
├── quotas/{check}                       kontroly kvót
├── registered-keys/                     správa registrovaných kľúčov
├── rerank/                              zmena poradia
├── responses/[...path]/                 API OpenAI Responses (zachytáva všetky trasy)
├── search/                              vyhľadávanie na webe
├── videos/                              generovanie videí
├── ws/                                  most WebSocket
└── route.ts                             obslužná funkcia indexu
```

Každý súbor trasy používa rovnaký vzor:

```
Trasa → predbežná požiadavka CORS → validácia tela pomocou Zod → voliteľné overenie
      → uplatnenie zásad kľúča API → delegovanie obslužnej funkcii (open-sse)
```

`v1beta/` je vrstva kompatibility v štýle Gemini (tenký obal, ktorý vykonáva preklad do
rovnakého spracovateľského reťazca `open-sse/handlers/`).

### 3.2 `src/lib/` — Základné knižnice

Dáta, synchronizáciu, OAuth, zručnosti, pamäť atď. vždy importujte prostredníctvom týchto modulov.
Tabuľka zoskupuje skutočné adresáre a významné súbory najvyššej úrovne.

| Modul             | Účel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `a2a/`            | Server protokolu A2A: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 zručností: analýza nákladov, správa o stave, vyhľadávanie poskytovateľov, správa kvót, inteligentné smerovanie, zoznam možností)                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `acp/`            | Protokol Agent-Control: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `api/`            | Interné pomocné nástroje API: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `auth/`           | `managementPassword.ts` (obnovenie hesla / hašovanie)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `batches/`        | Služba API OpenAI Batches (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `catalog/`        | Synchronizácia katalógu OpenRouter (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `cloudAgent/`     | Register cloudových agentov: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `combos/`         | Pomocné nástroje na rozlišovanie kombinácií                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `compliance/`     | Audit + audit poskytovateľa: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `config/`         | Prepojenie konfigurácie za behu                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `db/`             | Doménové moduly SQLite (pozri §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `display/`        | Pomocné nástroje používateľského rozhrania/zobrazenia používané odpoveďami API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `embeddings/`     | Register služieb vektorových reprezentácií                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `env/`            | Načítanie + introspekcia prostredia                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `evals/`          | Runtime pre evaluácie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `jobs/`           | Úlohy na pozadí (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `memory/`         | Trvalá pamäť: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `monitoring/`     | `observability.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `oauth/`          | Moduly poskytovateľov OAuth/importu (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `openference`, `qoder`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, plus `services/`, `utils/` a `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                                     |
| `plugins/`        | Načítavanie pluginov (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `providerModels/` | Spravovaný životný cyklus modelov: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `providers/`      | Pomocné nástroje poskytovateľov: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `resilience/`     | `settings.ts` — nastavenia pre istič, čas čakania a uzamknutie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `runtime/`        | Detekcia funkcií za behu                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `services/`       | Framework vložených služieb: `ServiceSupervisor.ts` (všeobecný správca podriadených procesov so zámkom operácií, kruhovou vyrovnávacou pamäťou a kontrolou stavu), `bootstrap.ts` (registrácia na úrovni procesu a automatické spustenie), `registry.ts` (mapovanie nástroja na správcu), `apiKey.ts` (úložisko kľúčov AES-256-GCM), `modelSync.ts` (pravidelná synchronizácia modelov), `ringBuffer.ts` (5 MB kruhová vyrovnávacia pamäť protokolov), `healthCheck.ts` (HTTP kontrola stavu), `types.ts`, `embedWsProxy.ts` (WebSocket proxy), `installers/{ninerouter,cliproxy}.ts`. Pozrite si `docs/frameworks/EMBEDDED-SERVICES.md`                                                               |
| `agentSkills/`    | Katalóg a generátor Agent Skills: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → zapisuje do `skills/{id}/SKILL.md`), `openapiParser.ts` (extrahuje koncové body REST zo špecifikácie OpenAPI), `cliRegistryParser.ts` (extrahuje podpríkazy CLI z bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Používajú ho trasy REST (`/api/agent-skills/*`), nástroje MCP (`omniroute_agent_skills_*`) a zručnosť A2A `list-capabilities`. Pozrite si [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | Framework zručností: `registry.ts`, `executor.ts`, `interception.ts`, `injection.ts`, `sandbox.ts`, `custom.ts`, `hybrid.ts`, `builtins.ts`, `a2a.ts`, `providerSettings.ts`, `schemas.ts`, `skillssh.ts`, `types.ts` a `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `spend/`          | `batchWriter.ts` (buffer s odloženým zápisom)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sync/`           | `bundle.ts`, `tokens.ts` (cloudová synchronizácia)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `system/`         | Pomocné nástroje na úrovni systému                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `translator/`     | Prepojovacia vrstva prekladača najvyššej úrovne (deleguje do `open-sse/translator/`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `usage/`          | Evidencia využitia: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `versionManager/` | Automatická aktualizácia + manifest verzie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `ws/`             | Most WebSocket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `zed-oauth/`      | Tok OAuth editora Zed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

Súbory najvyššej úrovne v `src/lib/`:

- Starý zlučovací modul `localDb.ts` bol odstránený — používatelia importujú konkrétne moduly `src/lib/db/*` priamo.
- `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts`
- `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts`
- `cloudSync.ts`, `initCloudSync.ts`
- `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts`
- `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts`
- `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts`
- `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts`
- `piiSanitizer.ts`, `pricingSync.ts`
- `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts`
- `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts`

#### 3.2.1 `src/lib/db/`

Singleton databáza SQLite (`getDbInstance()` v `core.ts`, žurnálovanie WAL).
**Nikdy nezapisujte nespracované SQL v trasách ani obslužných rutinách** — používajte tieto moduly.

![Prehľad databázovej schémy (vybrané základné tabuľky)](../diagrams/exported/db-schema-overview.svg)

> Zdroj: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

Doménové moduly (každý spravuje jednu alebo viac tabuliek): `apiKeys.ts`, `backup.ts`,
`batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`,
`commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`,
`compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`,
`contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`,
`detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`,
`healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`,
`modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`,
`providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`,
`readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`,
`sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`,
`syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`,
`webhooks.ts`.

Adresár `migrations/` obsahuje 168 verzovaných súborov `.sql` (idempotentných, transakčných) a pri
spustení ich vykonáva `migrationRunner.ts`.

Tabuľky vytvorené migráciami (celkovo 123):

`a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`,
`combo_adaptation_state`, `combos`, `command_code_auth_sessions`,
`compression_analytics`, `compression_cache_stats`,
`compression_combo_assignments`, `compression_combos`, `context_handoffs`,
`daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`,
`domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`,
`eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`,
`key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`,
`provider_connections`, `provider_key_limits`, `provider_nodes`,
`proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`,
`reasoning_cache`, `registered_keys`, `request_detail_logs`,
`routing_decisions`, `semantic_cache`, `session_account_affinity`,
`skill_executions`, `skills`, `sync_tokens`, `tier_assignments`,
`tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`,
`webhooks` (plus virtuálne tabuľky FTS5 na vyhľadávanie v pamäti).

### 3.3 `src/domain/` — Doménová vrstva

Čistá obchodná logika bez vstupno-výstupných operácií. Importujú ju trasy a obslužné rutiny.

| Súbor                                      | Účel                                                    |
| ------------------------------------------ | ------------------------------------------------------- |
| `policyEngine.ts`                          | Resolver politík najvyššej úrovne                       |
| `fallbackPolicy.ts`                        | Rozhodovací strom záložných možností                    |
| `costRules.ts`                             | Pravidlá výpočtu nákladov                               |
| `lockoutPolicy.ts`                         | Rozhodnutia o zablokovaní modelu                        |
| `tagRouter.ts`                             | Smerovanie založené na značkách                         |
| `comboResolver.ts`                         | Rozlíšenie kombinácie z požiadavky → zoznam cieľov      |
| `connectionModelRules.ts`                  | Filtre modelov pre jednotlivé pripojenia                |
| `modelAvailability.ts`                     | Kontrola dostupnosti modelu                             |
| `degradation.ts`                           | Prechody do degradovaného režimu                        |
| `providerExpiration.ts`                    | Detekcia účtov/kľúčov po uplynutí platnosti             |
| `quotaCache.ts`                            | Rozhodnutia o kvótach uložené vo vyrovnávacej pamäti    |
| `responses.ts`, `omnirouteResponseMeta.ts` | Pomocné funkcie pre štruktúru odpovede                  |
| `configAudit.ts`                           | Audit zmien konfigurácie                                |
| `assessment/`                              | Hodnotenie modelu (podľa RFC, čiastočne implementované) |
| `types.ts`                                 | Zdieľané doménové typy                                  |

### 3.4 `src/server/` — Iba pre server

Nemožno importovať z klientskych komponentov.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Klasifikuje trasy ako verejné alebo správcovské
│   ├── assertAuth.ts      Pomocná funkcia pre asercie
│   ├── context.ts         Autorizačný kontext pre každú požiadavku
│   ├── headers.ts
│   ├── pipeline.ts        Autorizačný kanál spracovania
│   ├── policies/          Konkrétne politiky
│   └── types.ts
└── cors/origins.ts        Zoznam povolených zdrojov CORS
```

### 3.5 `src/shared/` — Bezpečné na zdieľanie

Rozdelené do účelovo zameraných podadresárov:

- `constants/` — `providers.ts` (katalóg poskytovateľov validovaný pomocou Zod), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (zoznam zakázaných položiek), `mcpScopes.ts`,
  `errorCodes.ts`, `publicApiRoutes.ts`, `batch.ts`, `batchEndpoints.ts`,
  `bodySize.ts`, `colors.ts`, `appConfig.ts`, `config.ts`,
  `sidebarVisibility.ts`, `visionBridgeDefaults.ts`.
- `validation/` — `schemas.ts` (~80 schém Zod), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — kontrakty verejného API distribuované cez npm.
- `types/` — zdieľané typy TS.
- `utils/` — `circuitBreaker.ts`, `apiAuth.ts`, `apiKey.ts`, `apiKeyPolicy.ts`,
  `api.ts`, `classify429.ts`, `cliCompat.ts`, `clipboard.ts`, `cloud.ts`, `cn.ts`,
  `cors.ts`, `featureFlags.ts`,
  `fetchTimeout.ts`, `formatting.ts`, `inputSanitizer.ts`, `logger.ts`,
  `machine.ts`, `machineId.ts`, `maskEmail.ts`, `modelCatalogSearch.ts`,
  `nodeRuntimeSupport.ts`, `parseApiKeys.ts`, `providerHints.ts`,
  `providerModelAliases.ts`, `rateLimiter.ts`, `releaseNotes.ts`,
  `a11yAudit.ts`, ako aj hooky a komponenty ovládacieho panela v priečinkoch `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/`.
- `components/` — API komponentov ovládacieho panela (súhrnný export `index.tsx`: `Button`, `Input`,
  `Select`, `Modal`, `Card`, `DataTable`, …). Základné komponenty sú adaptérmi nad
  dodávanou súpravou (`packages/ui-kit`, importovanou cez podcestu komponentu, napríklad
  `@omniroute/ui-kit/button`), takže obrazovky si zachovávajú svoje importy, zatiaľ čo značkovanie pochádza zo
  súpravy. Obal je `layouts/DashboardLayout.tsx` → `layouts/DashboardShell.tsx`
  (`SidebarProvider`/`SidebarInset` zo súpravy) spolu s `Sidebar.tsx` a `Header.tsx`; ikony sa načítavajú
  cez `Icon.tsx` a `constants/iconMap.ts`. Pozrite si `docs/architecture/DESIGN_SYSTEM.md`.

---

## 4. `open-sse/` — Pracovný priestor streamovacieho nástroja

Samostatný pracovný priestor npm publikovaný ako `@omniroute/open-sse`. Vlastní spracovanie požiadaviek, vykonávateľov, prekladateľov, služby, transformátor a server MCP.

```
open-sse/
├── index.ts                Public exports
├── package.json            Workspace manifest
├── tsconfig.json
├── types.d.ts
├── config/                 Provider registries, header profiles, identity, …
├── handlers/               Request handlers (chat, embeddings, audio, image, …)
├── executors/              159 provider executor modules (executor classes + per-provider helpers)
├── translator/             Format conversion (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions stream transformer
├── services/               80+ service modules (combos, fallback, quotas, identity, …)
├── utils/                  Streaming helpers, TLS client, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP server (3 transports, 33 scopes, 110 tools)
```

### 4.1 `open-sse/handlers/`

| Handler                 | Účel                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `chatCore.ts`           | Hlavný kanál rozhovoru (vyrovnávacia pamäť, limit rýchlosti, kombinované smerovanie, odoslanie vykonávateľa) |
| `responsesHandler.ts`   | OpenAI Odpovedá na vstupný bod API                                                                           |
| `embeddings.ts`         | Vloženie                                                                                                     |
| `imageGeneration.ts`    | Generovanie obrazu                                                                                           |
| `audioSpeech.ts`        | Prevod textu na reč                                                                                          |
| `audioTranscription.ts` | Prevod reči na text                                                                                          |
| `videoGeneration.ts`    | Generovanie videa                                                                                            |
| `musicGeneration.ts`    | Hudobná generácia                                                                                            |
| `rerank.ts`             | Zmena poradia                                                                                                |
| `moderations.ts`        | Moderovanie                                                                                                  |
| `search.ts`             | vyhľadávanie na webe                                                                                         |
| `sseParser.ts`          | analyzátor udalostí SSE                                                                                      |
| `usageExtractor.ts`     | Vytiahnite počty tokenov z upstream streamov                                                                 |
| `responseSanitizer.ts`  | Odizolujte hluk špecifický pre poskytovateľa                                                                 |
| `responseTranslator.ts` | Lepidlo medzi odpoveďou poskytovateľa a vrstvou prekladateľa                                                 |

### 4.2 `open-sse/executors/`

159 modulov spúšťača najvyššej úrovne (`*.ts` mínus `base.ts`, `index.ts` a testuje — počet meraní `npm run check:docs-counts` ). Každá trieda exekútorov rozširuje `BaseExecutor` (`base.ts`), priamo alebo prostredníctvom `DefaultExecutor` alebo iného exekútora; zostávajúce moduly sú pomocníkmi pre jednotlivých poskytovateľov (schémy nástrojov, adaptéry fetch/TTS, obslužné programy quirk). Medzi vykonávateľov patrí:

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`, `chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`, `muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`, `pollinations`, `qoder`, `vertex` `devin-desktop` plus identita `claudeIdentity.ts`, `index.ts` (registra).

> Poznámka: Poskytovatelia, ktorí tu nie sú uvedení, sú obsluhovaní `default.ts` pomocou všeobecného spúšťača kompatibilného s OpenAI. Úplný katalóg poskytovateľov (381 poskytovateľov) žije v `src/shared/constants/providers.ts`.

### 4.3 `open-sse/translator/`

Hub-and-spoke preklad (OpenAI je hub).

- **9 dopytových prekladateľov** (`translator/request/`): `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`.
- **9 prekladateľov odpovedí** (`translator/response/`): `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`, `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`, `openai-to-claude`.
- **9 pomocníkov** (`translator/helpers/`): `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, plus testy pomocníkov.
- **Obrazoví pomocníci** (`translator/image/sizeMapper.ts`).
- Najvyššia úroveň: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

### 4.4 `open-sse/transformer/`

- `responsesTransformer.ts` — `TransformStream` -based Odpovede API ↔ Konvertor dokončenia chatu (používaný `responses/` route catch-all).

### 4.5 `open-sse/services/`

Najdôležitejšie (úplný zoznam pod `open-sse/services/`):

| Obavy                            | Súbory                                                                                                                                                                                                                                                   |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kombinované smerovanie           | `combo.ts` (20 stratégií), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                     |
| Auto Combo motor                 | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts`             |
| Odolnosť                         | `accountFallback.ts` (uzamknutie + po ochladení), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                  |
| Kvóty                            | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| Ukladanie do vyrovnávacej pamäte | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Smerovacia inteligencia          | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| Manipulácia s modelom            | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| Kompresia                        | `compression/` — úplné vedenie kompresného motora                                                                                                                                                                                                        |
| Relácia tokenu +                 | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| Úroveň / manifest                | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / sieť                        | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| Dávky                            | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Použitie                         | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **110 jedinečných nástrojov** zapojené v `server.ts` (45 kanonických v `schemas/tools.ts` + pamäť, zručnosti, zručnosti GitHub, fond, gamifikácia, plugin, Notion, Obsidian, lokálny korpus a kompresné moduly — union počítané podľa `countUniqueMcpTools`).
- **3 transporty** : stdio, HTTP Streamovateľné, SSE.
- **33 rozsahov** vynútené za behu základného zoznamu — v `src/shared/constants/mcpScopes.ts`, úplná množina je zjednotením rozsahov deklarovaných každým modulom nástroja.
- Tabuľka auditu: `mcp_tool_audit` (vyplnená `audit.ts`).
- Súbory: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`, `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`, `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`, plus testy pod `__tests__/`.
- Úplný katalóg nástrojov nájdete [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### 4.7 `open-sse/config/`

Provider registries (`providerRegistry.ts`, `providerModels.ts`, `providerHeaderProfiles.ts`), per-format model registries (`audioRegistry.ts`, `embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`, `musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`), identity helpers (`codexIdentity.ts`, `codexInstructions.ts`, `anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`, `cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`), credential helpers (`credentialLoader.ts`, `codexClient.ts`), and cloud adapters (`azureAi.ts`, `bedrock.ts`, `datarobot.ts`, `glmProvider.ts`, `maritalk.ts`, `oci.ts`, `petals.ts`, `runway.ts`, `sap.ts`, `watsonx.ts`, `ollamaModels.ts`, `errorConfig.ts`, `constants.ts`, `registryUtils.ts`).

### 4.8 `open-sse/utils/`

Primitíva streamovania a pomocníci poskytovateľa: `stream.ts`, `streamHandler.ts`, `streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`, `sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`, `networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`, `cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`, `comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`, `thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `progressTracker.ts`, `cors.ts` `logger.ts` `error.ts` `requestLogger.ts`, `sleep.ts` `ollamaTransform.ts`

---

## 5. `electron/` — Obal pre desktopovú aplikáciu

```
electron/
├── main.js                  Hlavný proces Electronu
├── preload.js               Most preload (zapnuté contextIsolation)
├── types.d.ts
├── package.json             Konfigurácia electron-builder, verzia 3.8.51
├── README.md
├── assets/                  Prostriedky zostavenia (ikony, oprávnenia, …)
├── node_modules/            Samostatné node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Výstup zostavenia (nie je súčasťou repozitára)
```

Päť npm skriptov v koreňovom adresári pracovného priestoru: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. Automatické aktualizácie zabezpečuje
`electron-updater`, ktorý odkazuje na kanál vydaní GitHubu.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           Hlavný vstupný bod CLI (Node ESM)
├── reset-password.mjs      Obnovenie hesla na správu prostredníctvom CLI
├── mcp-server.mjs          Spúšťač servera MCP (stdio)
├── nodeRuntimeSupport.mjs  Kontrola verzie Node
└── cli/
    ├── program.mjs         Tvorca programu Commander
    ├── runtime.mjs         Pomocná funkcia withRuntime (najprv server, pri zlyhaní DB)
    ├── output.mjs          Formátovače výstupu (json/jsonl/table/csv)
    ├── i18n.mjs            Pomocná funkcia t() s lokalizáciami
    ├── api.mjs             Pomocná funkcia na načítanie API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Registrácia príkazov
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (jeden súbor na príkaz/skupinu)
```

V `package.json` → `bin` sú sprístupnené dva binárne súbory:

- `omniroute` → `bin/omniroute.mjs`
- `omniroute-reset-password` → `bin/reset-password.mjs`

---

## 7. `tests/`

| Adresár                                              | Typ                                                                                                        |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | Jednotkové testy cez natívny testovací nástroj Node (1821 súborov a podadresáre `api/`, `auth/`, `authz/`) |
| `tests/integration/`                                 | Testy naprieč modulmi a testy stavu DB                                                                     |
| `tests/e2e/`                                         | Testy používateľského rozhrania Playwright                                                                 |
| `tests/e2e/protocol-clients.test.ts`                 | Komplexné testy protokolov MCP/A2A                                                                         |
| `tests/translator/`                                  | Testy špecifické pre prekladač                                                                             |
| `tests/security/`                                    | Regresné testy zabezpečenia                                                                                |
| `tests/load/`                                        | Záťažové testy a testy odolnosti                                                                           |
| `tests/golden-set/`                                  | Referenčné výstupy pre regresie prekladača                                                                 |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Podporné súbory                                                                                            |

Bežné príkazy:

| Príkaz                                                   | Čo spúšťa                                                               |
| -------------------------------------------------------- | ----------------------------------------------------------------------- |
| `npm run test:unit`                                      | Všetky `tests/unit/*.test.ts` cez testovací nástroj Node (súbežnosť 10) |
| `npm run test:vitest`                                    | Súpravu Vitest (MCP, autoCombo, vyrovnávacia pamäť)                     |
| `npm run test:e2e`                                       | Súpravu testov používateľského rozhrania Playwright                     |
| `npm run test:protocols:e2e`                             | Komplexné testy protokolov MCP + A2A                                    |
| `npm run test:coverage`                                  | Kontrolu pokrytia (≥60 % riadkov/príkazov/funkcií/vetiev)               |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | Spustenie jedného súboru                                                |

---

## 8. `scripts/`

Usporiadané podľa účelu do 6 podpriečinkov.

- **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`,
  `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`,
  `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`,
  `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`,
  `native-binary-compat.mjs`.
- **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`,
  `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`,
  `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`,
  `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`,
  `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`,
  `system-info.mjs` a pomocné nástroje iba na čítanie na dohľad nad PR:
  `ci-discriminate.sh` (triedi signatúry zlyhaných kontrol PR na vlastné / zdedené /
  neznáme podľa referenčného PR alebo hlásenia o chybách v základnej vetve) a `audit-worktree.sh`
  (zmenené súbory, chránené časti, odstránené asercie, počty potlačení, pozostatky
  dočasných konfigurácií tsconfig, hlavička PR oproti lokálnemu HEAD — pred prijatím PR od pracovníka).
- **`scripts/check/`** — `check-cycles.mjs`, `check-docs-sync.mjs`,
  `check-docs-counts-sync.mjs`, `check-env-doc-sync.mjs`,
  `check-deprecated-versions.mjs`, `check-route-validation.mjs`,
  `check-t11-any-budget.mjs`, `check-pr-test-policy.mjs`,
  `check-supported-node-runtime.ts`, `test-report-summary.mjs`.
- **`scripts/docs/`** — `generate-docs-index.mjs`, `gen-provider-reference.ts`.
- **`scripts/i18n/`** — `generate-multilang.mjs`, `run-visual-qa.mjs`,
  `generate-qa-checklist.mjs`, `apply-priority-overrides.mjs`,
  `validate_translation.py`, `check_translations.py`, `i18n_autotranslate.py`,
  `untranslatable-keys.json`.
- **`scripts/ad-hoc/`** — `cursor-tap.cjs`, `sync-cursor-models.mjs`,
  `migrate-env.mjs`, `dbsetup.js`.

---

## 9. Spracovanie požiadaviek (súhrn)

![Spracovanie požiadaviek (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

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

```
Požiadavka klienta
  → /v1/chat/completions (route.ts)
     Kontrola predbežnej požiadavky CORS
     Validácia pomocou Zod (chatCompletionsSchema v shared/validation/schemas.ts)
     Autentifikácia (extractApiKey + isValidApiKey ALEBO requireManagementAuth)
     Mechanizmus politík (src/server/authz/pipeline.ts)
     Ochranné mechanizmy (maskovanie osobných údajov, vkladanie pokynov, premostenie obrazového vstupu)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Kontrola vyrovnávacej pamäte (sémantická vyrovnávacia pamäť + vyrovnávacia pamäť na čítanie)
     Obmedzenie frekvencie (rateLimitManager, accountSemaphore)
     Kombinované smerovanie (ak sa model preloží na kombináciu)
       comboResolver → cyklus pre každý cieľ → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       načítanie z nadradeného servera → opakovanie/exponenciálne oneskorenie prostredníctvom accountFallback
     translateResponse() (open-sse/translator/response/*)
     Prúd SSE ALEBO odpoveď JSON
     Ak ide o Responses API: TransformStream prostredníctvom open-sse/transformer/responsesTransformer.ts
  → Audit súladu (src/lib/compliance/)
  → Odpoveď klientovi
```

### Stav odolnosti za behu (tri mechanizmy)

| Mechanizmus             | Rozsah                            | Kde                                                                                                     |
| ----------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Istič poskytovateľa     | Celý poskytovateľ                 | `src/shared/utils/circuitBreaker.ts`, uložené v `domain_circuit_breakers`                               |
| Doba čakania pripojenia | Jeden účet/kľúč                   | `markAccountUnavailable()` v `src/sse/services/auth.ts`; používa `accountFallback.checkFallbackError()` |
| Zablokovanie modelu     | Poskytovateľ + pripojenie + model | `open-sse/services/accountFallback.ts`, uložené v `domain_lockout_state`                                |

Pozrite si [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) a vyhradenú časť v
[CLAUDE.md](../../CLAUDE.md).

---

## 10. Ako prispievať

### Pridanie nového poskytovateľa

1. Zaregistrujte ho v `src/shared/constants/providers.ts` (pri načítaní sa overuje pomocou Zod).
2. Ak je potrebná vlastná logika, pridajte vykonávací modul do `open-sse/executors/`
   (rozšírte `BaseExecutor`).
3. Ak nepoužíva formát OpenAI, pridajte prekladač do `open-sse/translator/`.
4. Ak je založený na OAuth, pridajte konfiguráciu do `src/lib/oauth/providers/` a
   `src/lib/oauth/services/`.
5. Zaregistrujte modely v `open-sse/config/providerRegistry.ts` (alebo v registri
   príslušného formátu v `open-sse/config/`).
6. Napíšte testy v `tests/unit/`.

### Pridanie novej API trasy

1. Vytvorte `src/app/api/your-route/route.ts`.
2. Dodržte vzor: CORS → validácia tela pomocou Zod → autentifikácia → delegovanie obslužnej funkcii.
3. Ak ide o nový tvar požiadavky, pridajte schému Zod do `src/shared/validation/schemas.ts`.
4. Ak je trasa určená iba na správu, pridajte cestu do `src/shared/constants/publicApiRoutes.ts`
   (zoznam zakázaných ciest pre verejné API).
5. Pridajte testy do `tests/unit/`.
6. Aktualizujte `docs/reference/API_REFERENCE.md` a `docs/openapi.yaml`.

### Pridanie nového DB modulu

1. Vytvorte `src/lib/db/yourModule.ts` a importujte `getDbInstance()` z `./core.ts`.
2. Exportujte funkcie CRUD pre svoju doménu.
3. Ak pridávate nové tabuľky, pridajte migráciu do `src/lib/db/migrations/`, očíslovanú
   postupne, idempotentnú a transakčnú.
4. Importujúce moduly používajú priame importy z `@/lib/db/yourModule` (bez súhrnného exportu — stará reexportná vrstva `localDb.ts` bola odstránená).
5. Pridajte testy do `tests/unit/`.

### Pridanie nového nástroja MCP

1. Pridajte definíciu nástroja do `open-sse/mcp-server/tools/` (alebo rozšírte
   `open-sse/mcp-server/schemas/tools.ts`).
2. Priraďte príslušný rozsah alebo rozsahy v `src/shared/constants/mcpScopes.ts`.
3. Zaregistrujte nástroj v `open-sse/mcp-server/server.ts`.
4. Pridajte testy do `open-sse/mcp-server/__tests__/`.
5. Aktualizujte [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### Pridanie novej zručnosti A2A

Pozrite si [A2A-SERVER.md § Pridanie novej zručnosti](../frameworks/A2A-SERVER.md). Zručnosti sa nachádzajú v
`src/lib/a2a/skills/` a registrujú sa prostredníctvom správcu úloh A2A.

---

## 11. Konvencie

- **Štýl kódu**: odsadenie 2 medzerami, dvojité úvodzovky, šírka 100 znakov, bodkočiarky,
  koncové čiarky `es5` — vynucuje Prettier prostredníctvom `lint-staged`.
- **Importy**: externé → interné (`@/`, `@omniroute/open-sse`) → relatívne.
- **Pomenovanie**: súbory `camelCase` alebo `kebab-case`, komponenty `PascalCase`,
  konštanty `UPPER_SNAKE`.
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = `error` všade;
  `no-explicit-any` = `warn` v `open-sse/` a `tests/`, inde `error`.
- **TypeScript**: `strict: false` (zdedené nastavenie). Na hraniciach medzi modulmi uprednostňujte explicitné typy pred
  inferenciou.
- **Databáza**: nikdy nepíšte nespracované SQL v trasách ani obslužných funkciách — vždy používajte
  moduly v `src/lib/db/`. Nikdy neimportujte zo súhrnných exportov — používajte priamo konkrétne moduly `src/lib/db/*`.
- **Typovanie DB entít (#3512)**: funkcia, ktorá zapisuje alebo číta tvar
  riadka DB tabuľky, by mala prijímať/vracať pomenované rozhranie TS, ktoré zrkadlí
  stĺpce danej tabuľky v pomere 1:1, nie `any` ani anonymný typ vložený priamo na mieste volania. Umiestnite
  rozhranie vedľa funkcie (napr. `export interface UsageEntry` v
  `src/lib/usage/usageHistory.ts` nad `saveRequestUsage`), ponechajte jednotlivé
  polia voliteľné alebo s možnosťou hodnoty null, keď rôzne zapisujúce funkcie vypĺňajú riadok
  postupne, a pre pole, ktorého tvar sa medzi volajúcimi líši, uprednostnite `unknown` pred `any`
  (zdokumentujte to pri poli, napr. `UsageEntry.tokens`
  prijíma nespracované údaje o použití v tvare poskytovateľa aj normalizovaný tvar). Keď sa týmto
  spôsobom počet výskytov `any` v súbore zníži na nulu, pridajte ho do zoznamu povolených súborov
  `check:any-budget:t11` (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`), aby nedošlo k regresii. Toto je konvencia pre prvú čiastkovú fázu — širšie
  odstraňovanie „anonymného `any`“ prebieha iteratívne vo zvyšku
  kódovej základne.
- **Chyby**: používajte try/catch s konkrétnymi typmi chýb a zaznamenávajte ich s kontextom pino. Nikdy
  potichu neignorujte chyby v prúdoch SSE; na vyčistenie používajte signály prerušenia.
- **Bezpečnosť**: nikdy nepoužívajte `eval()` / `new Function()` / implicitné vyhodnocovanie. Všetky
  vstupy overujte pomocou Zod. Prihlasovacie údaje uložené v úložisku šifrujte (AES-256-GCM). Udržiavajte
  zoznam zakázaných položiek `src/shared/constants/upstreamHeaders.ts` zosúladený s
  vrstvou sanitizácie/validácie.
- **Commity**: Conventional Commits — `feat(scope): subject`. Povolené rozsahy:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Vetvy**: predpony `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/`. Nikdy nevytvárajte commity priamo do `main`.
- **Husky**: pred commitom spúšťa `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11`; pred odoslaním zmien spúšťa `check:any-budget:t11` + `check:tracked-artifacts` (rýchle kontroly; nezahŕňajú `test:unit`).

---

## 12. Striktné pravidlá (z CLAUDE.md)

1. Nikdy neukladajte tajné údaje ani prihlasovacie údaje do repozitára.
2. Nikdy nepoužívajte súhrnné importy — používajte priamo konkrétne moduly `src/lib/db/*`.
3. Nikdy nepoužívajte `eval()` / `new Function()` / implicitný eval.
4. Nikdy nevykonávajte commity priamo do vetvy `main`.
5. Nikdy nepíšte nespracované SQL v routách — vždy používajte moduly `src/lib/db/`.
6. Nikdy potichu nepotláčajte chyby v prúdoch SSE.
7. Vstupy vždy validujte pomocou schém Zod.
8. Pri zmene produkčného kódu vždy zahrňte testy.
9. Pokrytie musí zostať ≥ 60 % (príkazy, riadky, funkcie, vetvy).

---

## 13. Pozrite tiež

- [ARCHITECTURE.md](./ARCHITECTURE.md) — architektúra na vysokej úrovni a zodpovednosti
  modulov.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — referencia verejného a správcovského API.
- [FEATURES.md](../guides/FEATURES.md) — matica funkcií a hlavné novinky verzií.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — podrobný rozbor prerušovača obvodu, obdobia čakania
  a blokovania.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — hodnotenie a stratégie Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — úplný katalóg nástrojov MCP a transportov.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — schopnosti a zisťovanie protokolu A2A.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — kompresia RTK a Caveman.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — integrácie CLI.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (ak je k dispozícii), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — cieľové prostredia nasadenia.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — bežné prevádzkové problémy.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — pracovný postup pre prispievateľov.
- [CLAUDE.md](../../CLAUDE.md) — pravidlá repozitára pre Claude Code (zdroj pravdy
  pre mnohé z vyššie uvedených konvencií).
- [AGENTS.md](../../AGENTS.md) — podrobnejšia referencia architektúry používaná agentmi.