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

OmniRoute Codebase Documentation (Română)

🌐 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 · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Versiune: v3.8.51 Ultima actualizare: 2026-06-28 Public vizat: Ingineri care contribuie la OmniRoute sau dezvoltă integrări peste acesta.

Pentru diagrame de arhitectură de nivel înalt și raționamentul din spatele fiecărui subsistem, consultați ARCHITECTURE.md. Pentru analize aprofundate ale subsistemelor individuale (Auto Combo, serverul MCP, serverul A2A, Skills, Memory, Cloud Agents, Resilience, Compression etc.), consultați fișierele dedicate acestora din acest director docs/.

Acest fișier descrie ce există în prezent în depozit, astfel încât un inginer nou să poată naviga prin structură, să înțeleagă organizarea pe niveluri a mediului de execuție și să știe unde să adauge cod fără a inventa module noi.

---

1. Stiva tehnologică

Aspect	Alegere
Cadru web	Next.js 16 (App Router, ieșire autonomă, fără middleware global)
Limbaj	TypeScript 6.0+ — țintă ES2022, module: esnext, moduleResolution: bundler, strict: false
Mediu de execuție	Node.js >=22.22.2 <23 sau >=24.0.0 <27 (impus prin engines + SUPPORTED_NODE_RANGE)
Bază de date	SQLite prin better-sqlite3 (singleton, jurnalizare WAL)
Desktop	Electron 41 + electron-builder 26.10 (spațiu de lucru separat în electron/)
Teste	Executorul nativ de teste Node (unitare/de integrare), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Compilare	Next.js autonom prin scripts/build/build-next-isolated.mjs
Verificare/formatare	Configurație plată ESLint + Prettier (lint-staged prin pre-commit Husky)
Sistem de module	ESM peste tot ("type": "module")
Spații de lucru	spațiu de lucru npm — open-sse este singurul spațiu de lucru secundar

Aliasuri de căi (tsconfig.json):

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

Port HTTP implicit: 20128 (API-ul și panoul de control partajează același proces). Directorul de date este variabila de mediu DATA_DIR, având valoarea implicită ~/.omniroute/.

---

2. Structura depozitului

OmniRoute/
├── src/                  Aplicația Next.js (App Router, biblioteci, domeniu, server, cod partajat)
├── open-sse/             Spațiul de lucru al motorului de streaming (@omniroute/open-sse)
├── electron/             Înveliș desktop (proces principal Electron 41 + preîncărcare)
├── bin/                  Puncte de intrare CLI (omniroute, reset-password)
├── tests/                Teste unitare, de integrare, e2e, protocols-e2e, translator, securitate, fixture-uri
├── scripts/              Scripturi auxiliare pentru compilare, sincronizare, verificare, migrare și execuție
├── docs/                 Documentație publică (acest director)
├── public/               Resurse statice, manifest PWA, service worker
├── config/               Exemple de configurare pentru mediul de execuție
├── images/               Resurse de marketing/capturi de ecran
├── _ideia/, _references/, _mono_repo/, _tasks/   Fișiere interne temporare / planificare (neincluse în distribuție)
├── CLAUDE.md             Reguli ale depozitului pentru Claude Code
├── AGENTS.md             Referință de arhitectură mai detaliată pentru agenți
├── package.json          v3.8.51, rădăcina spațiului de lucru
└── tsconfig.json         Aliasuri de căi + opțiuni principale ale compilatorului

---

3. src/ — Aplicația Next.js

src/
├── app/                  Pagini App Router + rute API
├── lib/                  Biblioteci de bază (bază de date, autentificare, OAuth, abilități, memorie, …)
├── domain/               Strat de domeniu pur (politici, mecanisme de rezervă, costuri, blocare, …)
├── server/               Module exclusiv pentru server (autorizare, CORS, autentificare)
├── shared/               Tipuri, constante, validare, contracte, utilitare (sigure între limite)
├── mitm/                 Utilitare proxy de tip „man-in-the-middle” pentru integrarea CLI
├── models/               Metadate / aliasuri pentru modele locale
├── sse/                  Gestionare SSE veche, aflată încă în src/ (nu în open-sse/)
├── store/                Store-uri de stare pe partea de client
├── middleware/           Utilitare middleware la nivel de rută (nu middleware global Next.js)
├── scripts/              Scripturi din arbore care pot fi importate de codul aplicației
├── types/                Tipuri TS ambientale și partajate
├── i18n/                 Pachete de localizare
├── instrumentation.ts    Hook de instrumentare Next.js
├── instrumentation-node.ts
└── proxy.ts              Utilitar de inițializare proxy de nivel superior

3.1 src/app/ — App Router

App Router expune atât interfața panoului de control, cât și API-ul HTTP public/de administrare. Nu există middleware global — interceptarea se face pentru fiecare rută în parte.

Segmente de nivel superior din src/app/:

Cale	Scop
api/	Toate rutele API HTTP (consultați detalierea de mai jos)
a2a/	Endpoint A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Document de descoperire A2A Agent Card
(dashboard)/	Interfața panoului de control (grup de rute, fără prefix URL)
auth/, login/, forgot-password/, callback/	Fluxuri de autentificare
landing/	Pagină de marketing/destinație
docs/	Vizualizator încorporat pentru documentația API
status/, maintenance/, offline/	Pagini operaționale
privacy/, terms/	Pagini juridice
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Pagini statice de eroare
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Limite de eroare/încărcare ale frameworkului
layout.tsx, page.tsx, globals.css, manifest.ts	Structura-rădăcină

3.1.1 src/app/(dashboard)/dashboard/ — Pagini UI

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 fișierele-rădăcină page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Grupuri API de nivel superior

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/   Administrarea serviciilor încorporate (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API public compatibil cu OpenAI
├── v1beta/     Compatibilitate în stil Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Administrarea serviciilor încorporate

Rute pentru instalarea, pornirea, oprirea și monitorizarea 9Router și CLIProxyAPI. Toate căile sunt clasificate drept LOCAL_ONLY (doar loopback, regula strictă #17), deoarece pot invoca npm install și pot genera procese copil.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             funcția auxiliară getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install prin 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 pentru o versiune mai nouă
│   ├── rotate-key/route.ts POST — generează o cheie API nouă + repornește
│   ├── status/route.ts     GET  — starea în timp real + starea bazei de date + metadatele versiunii
│   └── auto-start/route.ts POST — comută indicatorul auto_start
├── cliproxy/
│   ├── _lib.ts             funcția auxiliară 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 pentru o versiune mai nouă
│   ├── status/route.ts     GET  — starea în timp real + starea bazei de date + metadatele versiunii
│   └── auto-start/route.ts POST — comută indicatorul auto_start
└── [name]/
    └── logs/route.ts       GET  — flux SSE cu ultimele înregistrări din jurnal (partajat de toate serviciile)

Interfața corespunzătoare a panoului de control: src/app/(dashboard)/dashboard/providers/services/ — pagină cu două file (CLIProxyAPI + 9Router). Proxy invers pentru interfața încorporată 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Prezentare detaliată: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API public compatibil cu OpenAI

v1/
├── accounts/[id]/                       căutarea contului
├── agents/tasks/[id]/, agents/tasks/    puncte finale pentru sarcini în stil A2A
├── api/                                 funcții auxiliare API interne expuse sub v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API-ul OpenAI Batches
├── chat/completions/                    Chat Completions (punctul final principal)
├── completions/                         completări de text moștenite
├── embeddings/                          reprezentări vectoriale
├── files/[id]/, files/                  API-ul Files
├── _helpers/                            funcții auxiliare partajate pentru rute (fără URL public)
├── images/{edits, generations}/         generarea și editarea imaginilor
├── issues/                              puncte finale auxiliare pentru triaj
├── management/{proxies}/                rute pentru administrare în cadrul v1
├── messages/{count_tokens}/             compatibilitate cu mesajele în stil Anthropic
├── models/                              listarea modelelor (`route.ts`, `catalog.ts`)
├── moderations/                         moderare
├── music/                               generarea muzicii
├── providers/[provider]/                operațiuni pentru fiecare furnizor
├── quotas/{check}                       verificări ale cotelor
├── registered-keys/                     administrarea cheilor înregistrate
├── rerank/                              reclasificare
├── responses/[...path]/                 API-ul OpenAI Responses (rută universală)
├── search/                              căutare pe web
├── videos/                              generarea videoclipurilor
├── ws/                                  punte WebSocket
└── route.ts                             gestionar pentru index

Fiecare fișier de rută urmează același tipar:

Rută → verificare preliminară CORS → validarea corpului cu Zod → autentificare opțională
     → aplicarea politicii privind cheia API → delegarea către gestionar (open-sse)

v1beta/ este suprafața de compatibilitate în stil Gemini (un înveliș subțire care traduce în același flux open-sse/handlers/).

3.2 src/lib/ — Biblioteci de bază

Importați întotdeauna datele, sincronizarea, OAuth, abilitățile, memoria etc. prin intermediul acestor module. Tabelul grupează directoarele efective și fișierele importante de nivel superior.

Modul	Scop
a2a/	Server pentru protocolul A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 abilități: analiza costurilor, raport de stare, descoperirea furnizorilor, gestionarea cotelor, rutare inteligentă, list-capabilities)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Utilitare pentru API-ul intern: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (resetarea parolei / hashing)
batches/	Serviciu pentru API-ul OpenAI Batches (service.ts)
catalog/	Sincronizarea catalogului OpenRouter (openrouterCatalog.ts)
cloudAgent/	Registrul agenților cloud: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Utilitare pentru rezolvarea combinațiilor
compliance/	Audit + auditul furnizorilor: index.ts, providerAudit.ts
config/	Cod de integrare pentru configurarea la rulare
db/	Module de domeniu SQLite (consultați §3.2.1)
display/	Utilitare pentru interfața cu utilizatorul/afișare, utilizate de răspunsurile API
embeddings/	Registrul serviciilor de înglobare
env/	Încărcarea + introspecția mediului
evals/	Mediu de rulare pentru evaluări
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Sarcini de fundal (autoUpdate.ts, …)
memory/	Memorie persistentă: 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/	Module OAuth/de import pentru furnizori (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/ și constants/oauth.ts
plugins/	Încărcător de pluginuri (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Ciclul de viață al modelelor gestionate: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Utilitare pentru furnizori: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — setări pentru disjunctor, perioadă de așteptare și blocare
runtime/	Detectarea funcționalităților la rulare
search/	executeWebSearch.ts
services/	Cadru pentru servicii încorporate: ServiceSupervisor.ts (supervizor generic pentru procese copil, cu blocare a operațiunilor, buffer circular și verificator al stării), bootstrap.ts (înregistrare la nivel de proces și pornire automată), registry.ts (mapare instrument → supervizor), apiKey.ts (depozit de chei AES-256-GCM), modelSync.ts (sincronizare periodică a modelelor), ringBuffer.ts (buffer circular de 5 MB pentru jurnale), healthCheck.ts (sondă HTTP pentru verificarea stării), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Consultați docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Catalog + generator pentru abilitățile agenților: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → scrie în skills/{id}/SKILL.md), openapiParser.ts (extrage punctele finale REST din specificația OpenAPI), cliRegistryParser.ts (extrage subcomenzile CLI din bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Utilizat de rutele REST (/api/agent-skills/*), instrumentele MCP (omniroute_agent_skills_*) și abilitatea A2A list-capabilities. Consultați AGENT-SKILLS.md.
skills/	Cadru pentru abilități: 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 cu scriere amânată)
sync/	bundle.ts, tokens.ts (sincronizare în cloud)
system/	Utilitare la nivel de sistem
translator/	Cod de integrare pentru translatorul de nivel superior (deleagă către open-sse/translator/)
usage/	Contabilizarea utilizării: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Actualizare automată + manifestul versiunilor
ws/	Punte WebSocket
zed-oauth/	Fluxul OAuth al editorului Zed

Fișiere de nivel superior în src/lib/:

• Vechiul barrel localDb.ts a fost eliminat — consumatorii importă direct modulele specifice src/lib/db/*.
• 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/

Bază de date SQLite singleton (getDbInstance() în core.ts, jurnalizare WAL). Nu scrieți niciodată SQL brut în rute sau gestionare — utilizați aceste module.

Sursă: diagrams/db-schema-overview.mmd

Module de domeniu (fiecare gestionează unul sau mai multe tabele): 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.

migrations/ conține 168 de fișiere .sql versionate (idempotente, tranzacționale) și este executat de migrationRunner.ts la pornire.

Tabele create prin migrări (123 în total):

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 tabele virtuale FTS5 pentru căutarea în memorie).

3.3 src/domain/ — Strat de domeniu

Logică de business pură, fără I/O. Importată de rute și gestionare.

Fișier	Scop
policyEngine.ts	Rezolvator de politici de nivel superior
fallbackPolicy.ts	Arbore decizional pentru fallback
costRules.ts	Reguli de calculare a costurilor
lockoutPolicy.ts	Decizii privind blocarea modelelor
tagRouter.ts	Rutare bazată pe etichete
comboResolver.ts	Rezolvarea combinației din cerere → lista de ținte
connectionModelRules.ts	Filtre de modele pentru fiecare conexiune
modelAvailability.ts	Verificarea disponibilității modelului
degradation.ts	Tranziții în modul degradat
providerExpiration.ts	Detectarea conturilor/cheilor expirate
quotaCache.ts	Decizii de cotă stocate în cache
responses.ts, omnirouteResponseMeta.ts	Funcții auxiliare pentru structura răspunsului
configAudit.ts	Auditarea modificărilor de configurare
assessment/	Evaluarea modelelor (conform RFC, implementată parțial)
types.ts	Tipuri de domeniu partajate

3.4 src/server/ — Exclusiv pentru server

Nu poate fi importat din componentele client.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Clasifică rutele ca publice sau de administrare
│   ├── assertAuth.ts      Funcție auxiliară pentru aserțiuni
│   ├── context.ts         Context authz pentru fiecare cerere
│   ├── headers.ts
│   ├── pipeline.ts        Flux authz
│   ├── policies/          Politici concrete
│   └── types.ts
└── cors/origins.ts        Listă de permisiuni pentru originile CORS

3.5 src/shared/ — Sigur pentru partajare

Împărțit în subdirectoare specializate:

• constants/ — providers.ts (catalog de furnizori validat cu Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (listă de interdicții), 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 de scheme Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — contracte API publice distribuite prin npm.
• types/ — tipuri TS partajate.
• 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, plus hook-uri/componente pentru tabloul de bord în services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Spațiul de lucru al motorului de streaming

Spațiu de lucru npm separat, publicat ca @omniroute/open-sse. Gestionează procesarea cererilor, executorii, translatoarele, serviciile, transformatorul și serverul MCP.

open-sse/
├── index.ts                Exporturi publice
├── package.json            Manifestul spațiului de lucru
├── tsconfig.json
├── types.d.ts
├── config/                 Registre de furnizori, profiluri de anteturi, identitate, …
├── handlers/               Gestionare cereri (chat, încorporări, audio, imagini, …)
├── executors/              108 executori HTTP specifici furnizorilor
├── translator/             Conversie de formate (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformator de flux Responses API ↔ Chat Completions
├── services/               Peste 80 de module de servicii (combinații, rezervă, cote, identitate, …)
├── utils/                  Utilitare de streaming, client TLS, AWS SigV4, preluare prin proxy, …
└── mcp-server/             Server MCP (3 transporturi, 33 de domenii, 110 instrumente)

4.1 open-sse/handlers/

Gestionar	Scop
chatCore.ts	Fluxul principal de chat (cache, limitarea ratei, rutarea combinațiilor, trimiterea către executori)
responsesHandler.ts	Punct de intrare pentru OpenAI Responses API
embeddings.ts	Încorporări
imageGeneration.ts	Generare de imagini
audioSpeech.ts	Conversie text în vorbire
audioTranscription.ts	Conversie vorbire în text
videoGeneration.ts	Generare video
musicGeneration.ts	Generare de muzică
rerank.ts	Reordonare
moderations.ts	Moderare
search.ts	Căutare pe web
sseParser.ts	Analizor de evenimente SSE
usageExtractor.ts	Extrage numărul de tokenuri din fluxurile din amonte
responseSanitizer.ts	Elimină zgomotul specific furnizorului
responseTranslator.ts	Interfață între răspunsul furnizorului și stratul de traducere

4.2 open-sse/executors/

108 executori pentru furnizori, fiecare extinzând 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, plus claudeIdentity.ts (utilitar comun pentru identitate) și index.ts (registru).

Notă: furnizorii care nu sunt enumerați aici sunt deserviți de default.ts folosind executorul generic compatibil cu OpenAI. Catalogul complet de furnizori (355 de furnizori) se află în src/shared/constants/providers.ts.

4.3 open-sse/translator/

Traducere de tip hub-and-spoke (OpenAI este nodul central).

• 9 translatoare de cereri (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 translatoare de răspunsuri (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 utilitare (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, plus teste pentru utilitare.
• Utilitare pentru imagini (translator/image/sizeMapper.ts).
• La nivel superior: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — convertor Responses API ↔ Chat Completions bazat pe TransformStream (utilizat de ruta universală responses/).

4.5 open-sse/services/

Elemente principale (lista completă se află în open-sse/services/):

Aspect	Fișiere
Rutare Combo	combo.ts (19 strategii), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Motor 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
Reziliență	accountFallback.ts (perioadă de așteptare + blocare), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Cote	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Memorare în cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Rutare inteligentă	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Gestionarea modelelor	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Compresie	compression/ — cablarea completă a motorului de compresie
Token + sesiune	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Nivel / manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / rețea	ipFilter.ts, webSearchFallback.ts
Loturi	batchProcessor.ts
Utilizare	usage.ts

4.6 open-sse/mcp-server/

• 110 instrumente unice conectate în server.ts (45 canonice în schemas/tools.ts + module pentru memorie, abilități, abilități GitHub, pool, gamificare, pluginuri, Notion, Obsidian, corpus local și compresie — reuniunea este numărată de countUniqueMcpTools).
• 3 transporturi: stdio, HTTP Streamable, SSE.
• 33 de domenii de acces impuse în timpul execuției — lista de bază se află în src/shared/constants/mcpScopes.ts, iar setul complet este reuniunea domeniilor de acces declarate de fiecare modul de instrumente.
• Tabel de audit: mcp_tool_audit (populat de audit.ts).
• Fișiere: 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 teste în __tests__/.
• Consultați MCP-SERVER.md pentru catalogul complet de instrumente.

4.7 open-sse/config/

Registre de furnizori (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registre de modele pentru fiecare format (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), funcții auxiliare pentru identitate (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), funcții auxiliare pentru acreditări (credentialLoader.ts, codexClient.ts) și adaptoare cloud (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/

Primitive de streaming și funcții auxiliare pentru furnizori: 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/ — Wrapper desktop

electron/
├── main.js                  Procesul principal Electron
├── preload.js               Punte de preîncărcare (contextIsolation activat)
├── types.d.ts
├── package.json             Configurație electron-builder, versiunea 3.8.51
├── README.md
├── assets/                  Resurse de compilare (pictograme, drepturi, …)
├── node_modules/            node_modules dedicat (better-sqlite3, electron-updater)
└── dist-electron/           Rezultatul compilării (neinclus în depozit)

Cinci scripturi npm la rădăcina spațiului de lucru: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Actualizarea automată se face prin electron-updater, configurat să utilizeze fluxul de versiuni GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Punctul principal de intrare CLI (Node ESM)
├── reset-password.mjs      Resetează parola de administrare din CLI
├── mcp-server.mjs          Lansator pentru serverul MCP (stdio)
├── nodeRuntimeSupport.mjs  Verificarea versiunii Node
└── cli/
    ├── program.mjs         Constructorul programului Commander
    ├── runtime.mjs         Funcția auxiliară withRuntime (mai întâi serverul/revenire la baza de date)
    ├── output.mjs          Formatoare de ieșire (json/jsonl/table/csv)
    ├── i18n.mjs            Funcția auxiliară t() cu localizări
    ├── api.mjs             Funcție auxiliară pentru solicitări API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Înregistrarea comenzilor
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (câte un fișier pentru fiecare comandă/grup)

Două fișiere binare sunt expuse în package.json → bin:

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

---

7. tests/

Director	Tip
tests/unit/	Teste unitare prin executorul de teste nativ Node (1821 de fișiere, plus subdirectoarele api/, auth/, authz/)
tests/integration/	Teste între module și teste ale stării bazei de date
tests/e2e/	Teste UI Playwright
tests/e2e/protocol-clients.test.ts	Teste e2e pentru protocoalele MCP/A2A
tests/translator/	Teste specifice traducătorului
tests/security/	Teste de regresie pentru securitate
tests/load/	Teste de încărcare/stres
tests/golden-set/	Rezultate de referință pentru regresiile traducătorului
tests/helpers/, tests/fixtures/, tests/manual/	Suport

Comenzi uzuale:

Comandă	Ce execută
npm run test:unit	Toate testele tests/unit/*.test.ts prin executorul de teste Node (concurență 10)
npm run test:vitest	Suita Vitest (MCP, autoCombo, cache)
npm run test:e2e	Suita UI Playwright
npm run test:protocols:e2e	Teste e2e pentru protocoalele MCP + A2A
npm run test:coverage	Prag de acoperire (≥60% linii/instrucțiuni/funcții/ramuri)
node --import tsx/esm --test tests/unit/<file>.test.ts	Executarea unui singur fișier

---

8. scripts/

Organizat în 6 subfoldere în funcție de scop.

• 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. Fluxul cererilor (rezumat)

Sursă: diagrams/request-pipeline.mmd

Cererea clientului
  → /v1/chat/completions (route.ts)
     Verificare preflight CORS
     Validare Zod (chatCompletionsSchema în shared/validation/schemas.ts)
     Autentificare (extractApiKey + isValidApiKey SAU requireManagementAuth)
     Motor de politici (src/server/authz/pipeline.ts)
     Măsuri de protecție (mascarea PII, injectarea de prompturi, puntea pentru viziune)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Verificarea cache-ului (cache semantic + cache de citire)
     Limitarea ratei (rateLimitManager, accountSemaphore)
     Rutare combinată (dacă modelul este rezolvat la o combinație)
       comboResolver → buclă pentru fiecare țintă → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       preluare din amonte → reîncercare/retragere exponențială prin accountFallback
     translateResponse() (open-sse/translator/response/*)
     Flux SSE SAU răspuns JSON
     Dacă se utilizează Responses API: TransformStream prin open-sse/transformer/responsesTransformer.ts
  → Audit de conformitate (src/lib/compliance/)
  → Răspuns către client

Starea de rulare pentru reziliență (trei mecanisme)

Mecanism	Domeniu de aplicare	Unde
Întrerupător de circuit pentru furnizor	Întregul furnizor	src/shared/utils/circuitBreaker.ts, păstrat în domain_circuit_breakers
Perioadă de așteptare a conexiunii	Un cont/o cheie	markAccountUnavailable() în src/sse/services/auth.ts; utilizat de accountFallback.checkFallbackError()
Blocarea modelului	Furnizor + conexiune + model	open-sse/services/accountFallback.ts, păstrat în domain_lockout_state

Consultați RESILIENCE_GUIDE.md și secțiunea dedicată din CLAUDE.md.

---

10. Cum să contribuiți

Adăugarea unui furnizor nou

1. Înregistrați-l în src/shared/constants/providers.ts (validat cu Zod la încărcare).
2. Adăugați un executor în open-sse/executors/ dacă este necesară o logică personalizată (extindeți BaseExecutor).
3. Adăugați un translator în open-sse/translator/ dacă furnizorul nu utilizează formatul OpenAI.
4. Dacă se bazează pe OAuth, adăugați configurația în src/lib/oauth/providers/ și src/lib/oauth/services/.
5. Înregistrați modelele în open-sse/config/providerRegistry.ts (sau în registrul specific formatului din open-sse/config/).
6. Scrieți teste în tests/unit/.

Adăugarea unei rute API noi

1. Creați src/app/api/your-route/route.ts.
2. Urmați modelul: CORS → validarea corpului cu Zod → autentificare → delegarea către handler.
3. Pentru o structură nouă a cererii: adăugați schema Zod în src/shared/validation/schemas.ts.
4. Dacă este destinată exclusiv administrării: adăugați calea în src/shared/constants/publicApiRoutes.ts (lista de interdicții pentru suprafața API-ului public).
5. Adăugați teste în tests/unit/.
6. Actualizați docs/reference/API_REFERENCE.md și docs/openapi.yaml.

Adăugarea unui modul DB nou

1. Creați src/lib/db/yourModule.ts și importați getDbInstance() din ./core.ts.
2. Exportați funcțiile CRUD pentru domeniul dumneavoastră.
3. Pentru tabele noi: adăugați o migrare în src/lib/db/migrations/, numerotată secvențial, idempotentă și tranzacțională.
4. Importatorii utilizează importuri directe din @/lib/db/yourModule (fără barrel — vechiul strat de reexportare localDb.ts a fost eliminat).
5. Adăugați teste în tests/unit/.

Adăugarea unui instrument MCP nou

1. Adăugați definiția instrumentului în open-sse/mcp-server/tools/ (sau extindeți open-sse/mcp-server/schemas/tools.ts).
2. Atribuiți domeniul sau domeniile corespunzătoare în src/shared/constants/mcpScopes.ts.
3. Înregistrați instrumentul în open-sse/mcp-server/server.ts.
4. Adăugați teste în open-sse/mcp-server/__tests__/.
5. Actualizați MCP-SERVER.md.

Adăugarea unei abilități A2A noi

Consultați A2A-SERVER.md § Adăugarea unei abilități noi. Abilitățile se află în src/lib/a2a/skills/ și sunt înregistrate prin managerul de sarcini A2A.

---

11. Convenții

• Stilul codului: indentare cu 2 spații, ghilimele duble, lățime de 100 de caractere, punct și virgulă, virgule finale es5 — impuse de Prettier prin lint-staged.
• Importuri: externe → interne (@/, @omniroute/open-sse) → relative.
• Denumire: fișierele folosesc camelCase sau kebab-case, componentele PascalCase, constantele UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error peste tot; no-explicit-any = warn în open-sse/ și tests/, eroare în rest.
• TypeScript: strict: false (abordare moștenită). Preferați tipurile explicite în locul inferenței la limitele dintre module.
• Baza de date: nu scrieți niciodată SQL brut în rute sau handlere — utilizați întotdeauna modulele din src/lib/db/. Nu utilizați niciodată importuri barrel — folosiți direct modulele specifice src/lib/db/*.
• Tipizarea entităților DB (#3512): o funcție care scrie sau citește forma unui rând dintr-un tabel DB trebuie să accepte/returneze o interfață TS denumită care reflectă coloanele tabelului în raport 1:1, nu any sau un tip anonim inline la locul apelului. Plasați interfața lângă funcție (de exemplu, export interface UsageEntry în src/lib/usage/usageHistory.ts, deasupra saveRequestUsage), păstrați câmpurile individuale opționale/nullabile atunci când diferiți generatori completează rândul incremental și preferați unknown în locul lui any pentru un câmp a cărui formă variază între apelanți (documentat în câmp, de exemplu, UsageEntry.tokens acceptă atât utilizarea brută în forma furnizorului, cât și forma normalizată). După ce numărul de apariții any dintr-un fișier ajunge astfel la zero, adăugați-l în lista de permisiuni check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) pentru a preveni regresiile. Aceasta este o convenție pentru prima etapă — eliminarea mai amplă a tipurilor „any anonime” este iterativă în restul bazei de cod.
• Erori: utilizați try/catch cu tipuri de erori specifice și înregistrați-le cu context pino. Nu ignorați niciodată în mod silențios erorile din fluxurile SSE; utilizați semnale de anulare pentru curățare.
• Securitate: nu utilizați niciodată eval() / new Function() / evaluare implicită. Validați toate intrările cu Zod. Criptați credențialele stocate (AES-256-GCM). Mențineți lista de interdicții src/shared/constants/upstreamHeaders.ts sincronizată cu stratul de sanitizare/validare.
• Commituri: Conventional Commits — feat(scope): subject. Domenii permise: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Ramuri: prefixe feat/, fix/, refactor/, docs/, test/, chore/. Nu faceți niciodată commit direct în main.
• Husky: înainte de commit se rulează lint-staged + check:docs-sync + check:any-budget:t11; înainte de push se rulează check:any-budget:t11 + check:tracked-artifacts (verificări rapide; exclude test:unit).

---

12. Reguli stricte (din CLAUDE.md)

1. Nu comiteți niciodată secrete sau credențiale.
2. Nu folosiți niciodată importuri de tip barrel — utilizați direct modulele specifice src/lib/db/*.
3. Nu utilizați niciodată eval() / new Function() / evaluare implicită.
4. Nu comiteți niciodată direct în main.
5. Nu scrieți niciodată SQL brut în rute — accesați întotdeauna prin modulele src/lib/db/.
6. Nu ignorați niciodată erorile în mod silențios în fluxurile SSE.
7. Validați întotdeauna datele de intrare cu scheme Zod.
8. Includeți întotdeauna teste atunci când modificați codul de producție.
9. Acoperirea trebuie să rămână ≥ 60% (instrucțiuni, linii, funcții, ramuri).

---

13. Consultați și

• ARCHITECTURE.md — arhitectura de nivel înalt și responsabilitățile modulelor.
• API_REFERENCE.md — referință pentru API-ul public și cel de administrare.
• FEATURES.md — matricea funcționalităților și noutățile versiunilor.
• RESILIENCE_GUIDE.md — prezentare detaliată a mecanismelor circuit breaker, cooldown și lockout.
• AUTO-COMBO.md — punctajul și strategiile Auto Combo.
• MCP-SERVER.md — catalogul complet de instrumente MCP și metodele de transport.
• A2A-SERVER.md — capabilitățile protocolului A2A și mecanismele de descoperire.
• COMPRESSION_GUIDE.md — compresia RTK și Caveman.
• CLI-TOOLS.md — integrări CLI.
• ELECTRON_GUIDE.md (dacă există), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — medii-țintă de implementare.
• TROUBLESHOOTING.md — probleme operaționale frecvente.
• CONTRIBUTING.md — fluxul de lucru al colaboratorilor.
• CLAUDE.md — regulile depozitului pentru Claude Code (sursa de referință pentru multe dintre convențiile de mai sus).
• AGENTS.md — referință arhitecturală mai detaliată, utilizată de agenți.