OmniRoute/docs/i18n/sk/docs/architecture/CODEBASE_DOCUMENTATION.md

OmniRoute Codebase Documentation (Slovenčina)

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

---

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. 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
Behové prostredie	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, vyrovnávacia pamäť), Playwright (e2e + protocols-e2e)
Zostavenie	Samostatné zostavenie Next.js prostredníctvom scripts/build/build-next-isolated.mjs
Lintovanie/formátovanie	Plochá konfigurácia ESLint + Prettier (lint-staged prostredníctvom Husky pre-commit)
Systém modulov	ESM všade ("type": "module")
Pracovné priestory	Pracovný priestor npm — open-sse je jediný podradený pracovný priestor

Aliasy ciest (tsconfig.json):

• @/* → src/*
• @omniroute/open-sse → open-sse/index.ts
• @omniroute/open-sse/* → open-sse/*

Predvolený port HTTP: 20128 (API a ovládací panel zdieľajú rovnaký proces). Dátový adresár určuje premenná 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é časti)
├── open-sse/             Pracovný priestor streamovacieho jadra (@omniroute/open-sse)
├── electron/             Desktopový obal (hlavný proces Electron 41 + preload)
├── bin/                  Vstupné body CLI (omniroute, reset-password)
├── tests/                Jednotkové, integračné, e2e, protocols-e2e, prekladové, bezpečnostné testy a prípravky
├── scripts/              Pomocné skripty pre zostavenie, synchronizáciu, kontroly, migráciu a beh
├── docs/                 Verejná dokumentácia (tento adresár)
├── public/               Statické prostriedky, manifest PWA, service worker
├── config/               Ukážky konfigurácie behového prostredia
├── images/               Marketingové materiály/snímky obrazovky
├── _ideia/, _references/, _mono_repo/, _tasks/   Interné koncepty/plánovanie (nedistribuuje sa)
├── CLAUDE.md             Pravidlá repozitára pre Claude Code
├── AGENTS.md             Podrobnejší architektonický referenčný materiál 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 App Routera + trasy API
├── lib/                  Základné knižnice (DB, autentifikácia, OAuth, zručnosti, pamäť, …)
├── domain/               Čistá doménová vrstva (politiky, záložné mechanizmy, náklady, uzamknutie, …)
├── server/               Moduly určené len pre server (autorizácia, CORS, autentifikácia)
├── shared/               Typy, konštanty, validácia, kontrakty, pomocné nástroje (bezpečné naprieč rozhraniami)
├── mitm/                 Pomocné nástroje 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 v open-sse/)
├── store/                Úložiská stavu na strane klienta
├── middleware/           Pomocné nástroje middleware na úrovni trás (nie globálny middleware Next.js)
├── scripts/              Skripty v rámci stromu importovateľné kódom aplikácie
├── types/                Okolité a zdieľané typy TS
├── i18n/                 Lokalizačné balíky
├── instrumentation.ts    Hook inštrumentácie Next.js
├── instrumentation-node.ts
└── proxy.ts              Pomocný nástroj najvyššej úrovne na inicializáciu proxy

3.1 src/app/ — App Router

App Router sprístupňuje používateľské rozhranie ovládacieho 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 vyhľadanie karty agenta A2A
(dashboard)/	Používateľské rozhranie ovládacieho panela (skupina trás, bez prefixu URL)
auth/, login/, forgot-password/, callback/	Toky autentifikácie
landing/	Marketingová/vstupná stránka
docs/	Vstavaný 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 vstavaný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 vstavaných služieb

Trasy na inštaláciu, spúšťanie, zastavovanie a monitorovanie 9Router a CLIProxyAPI. Všetky cesty sú klasifikované ako LOCAL_ONLY (iba loopback, pevné pravidlo č. 17), pretože môžu spustiť npm install a vytvárať 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 databázy + 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 databázy + metadáta verzie
│   └── auto-start/route.ts POST — prepnutie príznaku auto_start
└── [name]/
    └── logs/route.ts       GET  — priebežné protokoly 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 (zachytenie všetkých trás)
├── search/                              webové vyhľadávanie
├── 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
      → vynútenie zásad kľúča API → delegovanie obslužnej funkcii (open-sse)

v1beta/ je kompatibilné rozhranie v štýle Gemini (tenká obalová vrstva, ktorá prekladá požiadavky 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/	Agent-Control-Protocol: 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 OpenAI Batches API (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 rozpoznávanie kombinácií
compliance/	Audit + audit poskytovateľa: index.ts, providerAudit.ts
config/	Prepojovacia vrstva konfigurácie 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čítavanie + introspekcia premenných prostredia
evals/	Beh vyhodnocovania
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 OAuth/importu poskytovateľov (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čítavač doplnkov (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Riadený ž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 ističa, intervalu čakania a uzamknutia
runtime/	Detekcia funkcií behu
search/	executeWebSearch.ts
services/	Framework vstavaných služieb: ServiceSupervisor.ts (všeobecný správca podriadených procesov so zámkom operácií, kruhovým bufferom a kontrolou stavu), bootstrap.ts (registrácia na úrovni procesu a automatické spustenie), registry.ts (mapovanie nástroj → správca), apiKey.ts (úložisko kľúčov AES-256-GCM), modelSync.ts (pravidelná synchronizácia modelov), ringBuffer.ts (5 MB kruhový buffer protokolov), healthCheck.ts (HTTP kontrola stavu), types.ts, embedWsProxy.ts (WebSocket proxy), installers/{ninerouter,cliproxy}.ts. Pozri docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalóg + generátor zručností agentov: 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 čiastkové prí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. Pozri 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, plus builtin/browser.ts
spend/	batchWriter.ts (buffer odloženého zápisu)
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/	Účtovanie používania: 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 verzií
ws/	Most WebSocket
zed-oauth/	Tok OAuth editora Zed

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

• Starý zberný 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/

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

Zdroj: 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 a transakčných), ktoré pri spustení 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á biznis logika bez vstupno-výstupných operácií. Importujú ju trasy a obslužné rutiny.

Súbor	Účel
policyEngine.ts	Vrcholový prekladač politík
fallbackPolicy.ts	Rozhodovací strom záložných možností
costRules.ts	Pravidlá výpočtu nákladov
lockoutPolicy.ts	Rozhodnutia o uzamknutí modelu
tagRouter.ts	Smerovanie založené na značkách
comboResolver.ts	Preklad 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 s uplynutou platnosťou
quotaCache.ts	Rozhodnutia o kvótach uložené vo vyrovnávacej pamäti
responses.ts, omnirouteResponseMeta.ts	Pomocné funkcie pre tvar 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 overenie
│   ├── context.ts         Autorizačný kontext pre jednotlivé požiadavky
│   ├── headers.ts
│   ├── pipeline.ts        Autorizačný kanál
│   ├── 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 overovaný 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/ — verejné kontrakty API publikované v 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 a tiež hooky/komponenty ovládacieho panela v priečinkoch services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Pracovný priestor streamovacieho jadra

Samostatný npm pracovný priestor publikovaný ako @omniroute/open-sse. Zastrešuje spracovanie požiadaviek, exekútory, translátory, služby, transformátor a server MCP.

open-sse/
├── index.ts                Verejné exporty
├── package.json            Manifest pracovného priestoru
├── tsconfig.json
├── types.d.ts
├── config/                 Registre poskytovateľov, profily hlavičiek, identita, …
├── handlers/               Obslužné rutiny požiadaviek (čet, vnorenia, zvuk, obrázky, …)
├── executors/              108 HTTP exekútorov špecifických pre poskytovateľov
├── translator/             Konverzia formátov (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformátor prúdu Responses API ↔ Chat Completions
├── services/               Viac ako 80 modulov služieb (kombinácie, záložné spracovanie, kvóty, identita, …)
├── utils/                  Pomocné funkcie pre streamovanie, klient TLS, AWS SigV4, proxy fetch, …
└── mcp-server/             Server MCP (3 transporty, 33 rozsahov, 110 nástrojov)

4.1 open-sse/handlers/

Obslužná rutina	Účel
chatCore.ts	Hlavný reťazec spracovania četu (vyrovnávacia pamäť, obmedzenie frekvencie, smerovanie kombinácií, odoslanie exekútoru)
responsesHandler.ts	Vstupný bod OpenAI Responses API
embeddings.ts	Vnorenia
imageGeneration.ts	Generovanie obrázkov
audioSpeech.ts	Prevod textu na reč
audioTranscription.ts	Prevod reči na text
videoGeneration.ts	Generovanie videa
musicGeneration.ts	Generovanie hudby
rerank.ts	Opätovné zoradenie
moderations.ts	Moderovanie
search.ts	Vyhľadávanie na webe
sseParser.ts	Analyzátor udalostí SSE
usageExtractor.ts	Získavanie počtov tokenov z nadradených prúdov
responseSanitizer.ts	Odstránenie šumu špecifického pre poskytovateľa
responseTranslator.ts	Prepojenie medzi odpoveďou poskytovateľa a vrstvou translátora

4.2 open-sse/executors/

108 exekútorov poskytovateľov, pričom každý rozširuje BaseExecutor (base.ts):

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, ako aj claudeIdentity.ts (zdieľaná pomocná funkcia identity) a index.ts (register).

Poznámka: poskytovatelia, ktorí tu nie sú uvedení, sú obsluhovaní súborom default.ts pomocou všeobecného exekútora kompatibilného s OpenAI. Úplný katalóg poskytovateľov (355 poskytovateľov) sa nachádza v src/shared/constants/providers.ts.

4.3 open-sse/translator/

Preklad s architektúrou centrály a lúčov (OpenAI je centrála).

• 9 translátorov požiadaviek (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 translátorov 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ých funkcií (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper a tiež testy pomocných funkcií.
• Pomocné funkcie pre obrázky (translator/image/sizeMapper.ts).
• Najvyššia úroveň: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — konvertor Responses API ↔ Chat Completions založený na TransformStream (používaný univerzálnou trasou responses/).

4.5 open-sse/services/

Najdôležitejšie položky (úplný zoznam v open-sse/services/):

Oblasť	Súbory
Smerovanie Combo	combo.ts (19 stratégií), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Engine Auto Combo	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 (časové pozastavenie + uzamknutie), errorClassifier.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, crofUsageFetcher.ts, antigravityCredits.ts
Ukladanie do cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Inteligentné smerovanie	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Spracovanie modelov	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Kompresia	compression/ — kompletné prepojenie kompresného enginu
Tokeny + relácie	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
Využitie	usage.ts

4.6 open-sse/mcp-server/

• 110 jedinečných nástrojov prepojených v server.ts (45 kanonických v schemas/tools.ts + moduly pamäte, zručností, GitHub zručností, fondu, gamifikácie, pluginov, Notion, Obsidian, lokálneho korpusu a kompresie — zjednotenie spočítané pomocou countUniqueMcpTools).
• 3 transporty: stdio, HTTP Streamable, SSE.
• 33 rozsahov vynucovaných za behu — základný zoznam v src/shared/constants/mcpScopes.ts, úplná množina je zjednotením rozsahov deklarovaných jednotlivými modulmi nástrojov.
• Tabuľka auditu: mcp_tool_audit (napĺňaná súborom 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 v priečinku __tests__/.
• Úplný katalóg nástrojov nájdete v dokumente MCP-SERVER.md.

4.7 open-sse/config/

Registre poskytovateľov (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registre modelov podľa formátu (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), pomocné nástroje identity (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), pomocné nástroje poverení (credentialLoader.ts, codexClient.ts) a cloudové adaptéry (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/

Streamovacie primitíva a pomocné nástroje 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, requestLogger.ts, progressTracker.ts, cors.ts, error.ts, logger.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é do 6 podpriečinkov podľa účelu.

• 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.
• 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)

Zdroj: 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 a vyhradenú časť v 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.

Pridanie novej zručnosti A2A

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