# OmniRoute Codebase Documentation (Română)

🌐 **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) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/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)

---

> **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](./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](../frameworks/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.

![Prezentare generală a schemei bazei de date (tabele principale selectate)](../diagrams/exported/db-schema-overview.svg)

> Sursă: [diagrams/db-schema-overview.mmd](../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 antet, identitate, …
├── handlers/               Gestionare cereri (chat, embeddings, audio, imagini, …)
├── executors/              108 executori HTTP specifici furnizorilor
├── translator/             Conversie de format (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, expedierea executorilor) |
| `responsesHandler.ts`   | Punct de intrare pentru OpenAI Responses API                                                      |
| `embeddings.ts`         | Reprezentări vectoriale                                                                           |
| `imageGeneration.ts`    | Generarea imaginilor                                                                              |
| `audioSpeech.ts`        | Conversia textului în vorbire                                                                     |
| `audioTranscription.ts` | Conversia vorbirii în text                                                                        |
| `videoGeneration.ts`    | Generarea videoclipurilor                                                                         |
| `musicGeneration.ts`    | Generarea muzicii                                                                                 |
| `rerank.ts`             | Reordonare                                                                                        |
| `moderations.ts`        | Moderare                                                                                          |
| `search.ts`             | Căutare pe web                                                                                    |
| `sseParser.ts`          | Parser de evenimente SSE                                                                          |
| `usageExtractor.ts`     | Extrage numărul de tokenuri din fluxurile din amonte                                              |
| `responseSanitizer.ts`  | Elimină elementele nedorite specifice furnizorului                                                |
| `responseTranslator.ts` | Legătura dintre 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 centrul).

- **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 bazat pe `TransformStream` pentru Responses API ↔ Chat
  Completions (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`, `llmgatewayQuotaFetcher.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`                                                              |
| Comprimare            | `compression/` — integrarea completă a motorului de comprimare                                                                                                                                                                                           |
| 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 de memorie, abilități, abilități GitHub, pool, gamificare, pluginuri, Notion, Obsidian,
  corpus local și comprimare — reuniunea este calculată 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](../frameworks/MCP-SERVER.md) pentru catalogul complet al instrumentelor.

### 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 subdirectoare, î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)

![Fluxul cererilor (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Sursă: [diagrams/request-pipeline.mmd](../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](./RESILIENCE_GUIDE.md) și secțiunea dedicată din
[CLAUDE.md](../../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](../frameworks/MCP-SERVER.md).

### Adăugarea unei abilități A2A noi

Consultați [A2A-SERVER.md § Adăugarea unei abilități noi](../frameworks/A2A-SERVER.md). 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](./ARCHITECTURE.md) — arhitectura de nivel înalt și responsabilitățile
  modulelor.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — referință pentru API-ul public și cel de administrare.
- [FEATURES.md](../guides/FEATURES.md) — matricea funcționalităților și noutățile versiunilor.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — prezentare detaliată a mecanismelor circuit breaker, cooldown
  și lockout.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — punctajul și strategiile Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — catalogul complet de instrumente MCP și metodele de transport.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — capabilitățile protocolului A2A și mecanismele de descoperire.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — compresia RTK și Caveman.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — integrări CLI.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (dacă există), [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) — medii-țintă de implementare.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — probleme operaționale frecvente.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — fluxul de lucru al colaboratorilor.
- [CLAUDE.md](../../CLAUDE.md) — regulile depozitului pentru Claude Code (sursa de referință
  pentru multe dintre convențiile de mai sus).
- [AGENTS.md](../../AGENTS.md) — referință arhitecturală mai detaliată, utilizată de agenți.