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

OmniRoute Codebase Documentation (Italiano)

🌐 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 · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Versione: v3.8.51 Ultimo aggiornamento: 2026-06-28 Destinatari: Ingegneri che contribuiscono a OmniRoute o sviluppano integrazioni basate su di esso.

Per i diagrammi dell'architettura di alto livello e le motivazioni alla base di ciascun sottosistema, consultare ARCHITECTURE.md. Per approfondimenti sui singoli sottosistemi (Auto Combo, server MCP, server A2A, Skills, Memory, Cloud Agents, Resilience, Compression, ecc.), consultare i relativi file dedicati in questa directory docs/.

Questo file descrive ciò che è attualmente presente nel repository, affinché un nuovo ingegnere possa orientarsi nella struttura, comprendere la stratificazione del runtime e sapere dove aggiungere codice senza inventare nuovi moduli.

---

1. Stack tecnologico

Ambito	Scelta
Framework web	Next.js 16 (App Router, output autonomo, nessun middleware globale)
Linguaggio	TypeScript 6.0+ — target ES2022, module: esnext, moduleResolution: bundler, strict: false
Runtime	Node.js >=22.22.2 <23 o >=24.0.0 <27 (imposto tramite engines + SUPPORTED_NODE_RANGE)
Database	SQLite tramite better-sqlite3 (singleton, journaling WAL)
Desktop	Electron 41 + electron-builder 26.10 (workspace separato in electron/)
Test	Test runner nativo di Node (unitari/integrazione), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Next.js autonomo tramite scripts/build/build-next-isolated.mjs
Lint/formattazione	Configurazione flat di ESLint + Prettier (lint-staged tramite pre-commit di Husky)
Sistema di moduli	ESM ovunque ("type": "module")
Workspace	Workspace npm — open-sse è l'unico sotto-workspace

Alias dei percorsi (tsconfig.json):

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

Porta HTTP predefinita: 20128 (l'API e la dashboard condividono lo stesso processo). La directory dei dati è definita dalla variabile di ambiente DATA_DIR e, per impostazione predefinita, è ~/.omniroute/.

---

2. Struttura del repository

OmniRoute/
├── src/                  Applicazione Next.js (App Router, librerie, dominio, server, codice condiviso)
├── open-sse/             Workspace del motore di streaming (@omniroute/open-sse)
├── electron/             Wrapper desktop (processo principale Electron 41 + preload)
├── bin/                  Punti di ingresso della CLI (omniroute, reset-password)
├── tests/                Test unitari, di integrazione, e2e, protocols-e2e, del traduttore, di sicurezza e fixture
├── scripts/              Script di build, sincronizzazione, verifica, migrazione e supporto al runtime
├── docs/                 Documentazione pubblica (questa directory)
├── public/               Risorse statiche, manifesto PWA, service worker
├── config/               Esempi di configurazione del runtime
├── images/               Risorse di marketing/screenshot
├── _ideia/, _references/, _mono_repo/, _tasks/   Materiale interno temporaneo / pianificazione (non distribuito)
├── CLAUDE.md             Regole del repository per Claude Code
├── AGENTS.md             Riferimento architetturale più approfondito per gli agenti
├── package.json          v3.8.51, radice del workspace
└── tsconfig.json         Alias dei percorsi + opzioni principali del compilatore

---

3. src/ — Applicazione Next.js

src/
├── app/                  Pagine App Router + route API
├── lib/                  Librerie principali (DB, autenticazione, OAuth, skill, memoria, …)
├── domain/               Livello di dominio puro (policy, fallback, costi, blocco, …)
├── server/               Moduli solo server (autorizzazione, CORS, autenticazione)
├── shared/               Tipi, costanti, validazione, contratti, utilità (sicuri tra i diversi livelli)
├── mitm/                 Helper proxy man-in-the-middle per l'integrazione con la CLI
├── models/               Metadati / alias dei modelli locali
├── sse/                  Gestori SSE legacy ancora presenti in src/ (non open-sse/)
├── store/                Store dello stato lato client
├── middleware/           Utilità middleware a livello di route (non middleware globale di Next.js)
├── scripts/              Script interni all'albero importabili dal codice dell'applicazione
├── types/                Tipi TS ambientali e condivisi
├── i18n/                 Pacchetti delle impostazioni locali
├── instrumentation.ts    Hook di strumentazione Next.js
├── instrumentation-node.ts
└── proxy.ts              Helper di bootstrap del proxy di primo livello

3.1 src/app/ — App Router

L'App Router espone sia l'interfaccia utente della dashboard sia l'API HTTP pubblica/di gestione. Non è presente alcun middleware globale: l'intercettazione viene eseguita per ogni route.

Segmenti di primo livello in src/app/:

Percorso	Scopo
api/	Tutte le route dell'API HTTP (vedere sotto)
a2a/	Endpoint A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Documento di individuazione A2A Agent Card
(dashboard)/	Interfaccia della dashboard (gruppo di route, nessun prefisso URL)
auth/, login/, forgot-password/, callback/	Flussi di autenticazione
landing/	Pagina di marketing/landing
docs/	Visualizzatore incorporato della documentazione API
status/, maintenance/, offline/	Pagine operative
privacy/, terms/	Pagine legali
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Pagine di errore statiche
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Limiti di errore/caricamento del framework
layout.tsx, page.tsx, globals.css, manifest.ts	Struttura radice

3.1.1 src/app/(dashboard)/dashboard/ — Pagine dell'interfaccia utente

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, oltre ai file radice page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Gruppi API di primo livello

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/   Gestione dei servizi incorporati (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API pubblica compatibile con OpenAI
├── v1beta/     Compatibilità in stile Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Gestione dei servizi incorporati

Route per installare, avviare, arrestare e monitorare 9Router e CLIProxyAPI. Tutti i percorsi sono classificati come LOCAL_ONLY (solo loopback, regola rigida n. 17) perché possono richiamare npm install e generare processi figli.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             helper getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install tramite 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 di una versione più recente
│   ├── rotate-key/route.ts POST — genera una nuova chiave API + riavvia
│   ├── status/route.ts     GET  — stato in tempo reale + DB + metadati della versione
│   └── auto-start/route.ts POST — attiva/disattiva il flag auto_start
├── cliproxy/
│   ├── _lib.ts             helper 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 di una versione più recente
│   ├── status/route.ts     GET  — stato in tempo reale + DB + metadati della versione
│   └── auto-start/route.ts POST — attiva/disattiva il flag auto_start
└── [name]/
    └── logs/route.ts       GET  — coda dei log SSE (condivisa da tutti i servizi)

Interfaccia utente corrispondente della dashboard: src/app/(dashboard)/dashboard/providers/services/ — pagina a due schede (CLIProxyAPI + 9Router). Proxy inverso per l'interfaccia utente integrata di 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Approfondimento: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API pubblica compatibile con OpenAI

v1/
├── accounts/[id]/                       ricerca dell'account
├── agents/tasks/[id]/, agents/tasks/    endpoint delle attività in stile A2A
├── api/                                 helper API interni esposti in v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API Batches di OpenAI
├── chat/completions/                    Chat Completions (l'endpoint principale)
├── completions/                         completamenti di testo legacy
├── embeddings/                          incorporamenti
├── files/[id]/, files/                  API Files
├── _helpers/                            helper condivisi delle route (nessun URL pubblico)
├── images/{edits, generations}/         generazione + modifica di immagini
├── issues/                              endpoint helper per il triage
├── management/{proxies}/                route con ambito di gestione all'interno di v1
├── messages/{count_tokens}/             compatibilità con i messaggi in stile Anthropic
├── models/                              elenco dei modelli (`route.ts`, `catalog.ts`)
├── moderations/                         moderazione
├── music/                               generazione musicale
├── providers/[provider]/                operazioni specifiche per provider
├── quotas/{check}                       verifiche delle quote
├── registered-keys/                     amministrazione delle chiavi registrate
├── rerank/                              riordinamento
├── responses/[...path]/                 API Responses di OpenAI (catch-all)
├── search/                              ricerca sul Web
├── videos/                              generazione video
├── ws/                                  bridge WebSocket
└── route.ts                             gestore dell'indice

Ogni file di route segue lo stesso schema:

Route → preflight CORS → convalida del corpo con Zod → autenticazione facoltativa
      → applicazione dei criteri delle chiavi API → delega al gestore (open-sse)

v1beta/ è la superficie di compatibilità in stile Gemini (un wrapper leggero che esegue la traduzione nella stessa pipeline open-sse/handlers/).

3.2 src/lib/ — Librerie principali

Importa sempre dati, sincronizzazione, OAuth, skill, memoria e così via tramite questi moduli. La tabella raggruppa le directory effettive e i file di primo livello degni di nota.

Modulo	Scopo
a2a/	Server del protocollo A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 skill: analisi dei costi, report sullo stato, individuazione dei provider, gestione delle quote, instradamento intelligente, elenco delle funzionalità)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Helper API interni: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (reimpostazione della password / hashing)
batches/	Servizio API OpenAI Batches (service.ts)
catalog/	Sincronizzazione del catalogo OpenRouter (openrouterCatalog.ts)
cloudAgent/	Registro degli agent cloud: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Helper per la risoluzione delle combinazioni
compliance/	Audit + audit dei provider: index.ts, providerAudit.ts
config/	Codice di raccordo per la configurazione del runtime
db/	Moduli di dominio SQLite (vedere §3.2.1)
display/	Helper per l'interfaccia utente/la visualizzazione utilizzati dalle risposte API
embeddings/	Registro dei servizi di embedding
env/	Caricamento + introspezione dell'ambiente
evals/	Runtime di valutazione
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Job in background (autoUpdate.ts, …)
memory/	Memoria persistente: 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/	Moduli OAuth/di importazione dei provider (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, oltre a services/, utils/ e constants/oauth.ts
plugins/	Caricatore di plugin (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Ciclo di vita dei modelli gestiti: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Helper per i provider: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — impostazioni per circuit breaker, cooldown e lockout
runtime/	Rilevamento delle funzionalità del runtime
search/	executeWebSearch.ts
services/	Framework dei servizi incorporati: ServiceSupervisor.ts (supervisore generico dei processi figli con blocco delle operazioni, buffer circolare e controllo dello stato), bootstrap.ts (registrazione a livello di processo e avvio automatico), registry.ts (mappa strumento → supervisore), apiKey.ts (archivio delle chiavi AES-256-GCM), modelSync.ts (sincronizzazione periodica dei modelli), ringBuffer.ts (buffer circolare dei log da 5 MB), healthCheck.ts (sonda HTTP per il controllo dello stato), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Vedere docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Catalogo + generatore di Agent Skills: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → scrive skills/{id}/SKILL.md), openapiParser.ts (estrae gli endpoint REST dalla specifica OpenAPI), cliRegistryParser.ts (estrae i sottocomandi CLI da bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Utilizzato dalle route REST (/api/agent-skills/*), dagli strumenti MCP (omniroute_agent_skills_*) e dalla skill A2A list-capabilities. Vedere AGENT-SKILLS.md.
skills/	Framework delle skill: 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, oltre a builtin/browser.ts
spend/	batchWriter.ts (buffer write-behind)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Helper a livello di sistema
translator/	Codice di raccordo del traduttore di livello superiore (delega a open-sse/translator/)
usage/	Contabilizzazione dell'utilizzo: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Aggiornamento automatico + manifesto delle versioni
ws/	Bridge WebSocket
zed-oauth/	Flusso OAuth dell'editor Zed

File di primo livello in src/lib/:

• Il vecchio barrel localDb.ts è stato rimosso — i consumer importano direttamente moduli src/lib/db/* specifici.
• 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/

Database SQLite singleton (getDbInstance() in core.ts, journaling WAL). Non scrivere mai SQL grezzo nelle route o negli handler — utilizza questi moduli.

Fonte: diagrams/db-schema-overview.mmd

Moduli di dominio (ciascuno gestisce una o più tabelle): 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/ contiene 168 file .sql con versione (idempotenti e transazionali) e viene eseguito da migrationRunner.ts all'avvio.

Tabelle create attraverso le migrazioni (123 in totale):

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 (oltre alle tabelle virtuali FTS5 per la ricerca nei ricordi).

3.3 src/domain/ — Livello di dominio

Logica di business pura, senza I/O. Importata da route e handler.

File	Scopo
policyEngine.ts	Risolutore di policy di primo livello
fallbackPolicy.ts	Albero decisionale di fallback
costRules.ts	Regole di calcolo dei costi
lockoutPolicy.ts	Decisioni di blocco dei modelli
tagRouter.ts	Routing basato sui tag
comboResolver.ts	Risoluzione delle combo dalla richiesta → elenco target
connectionModelRules.ts	Filtri dei modelli per connessione
modelAvailability.ts	Controllo della disponibilità dei modelli
degradation.ts	Transizioni alla modalità degradata
providerExpiration.ts	Rilevamento di account/chiavi scaduti
quotaCache.ts	Decisioni sulle quote memorizzate nella cache
responses.ts, omnirouteResponseMeta.ts	Helper per la struttura delle risposte
configAudit.ts	Audit delle modifiche alla configurazione
assessment/	Valutazione dei modelli (secondo RFC, parzialmente implementata)
types.ts	Tipi di dominio condivisi

3.4 src/server/ — Solo server

Non può essere importato dai componenti client.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Classifica le route come pubbliche o di gestione
│   ├── assertAuth.ts      Helper di asserzione
│   ├── context.ts         Contesto authz per richiesta
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline authz
│   ├── policies/          Policy concrete
│   └── types.ts
└── cors/origins.ts        Elenco delle origini CORS consentite

3.5 src/shared/ — Sicuro da condividere

Suddiviso in sottodirectory specifiche:

• constants/ — providers.ts (catalogo dei provider convalidato tramite Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (elenco di esclusione), 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 schemi Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — contratti API pubblici distribuiti su npm.
• types/ — tipi TS condivisi.
• 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, oltre a hook/componenti della dashboard in services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Workspace del motore di streaming

Workspace npm separato pubblicato come @omniroute/open-sse. Gestisce l'elaborazione delle richieste, gli esecutori, i traduttori, i servizi, il trasformatore e il server MCP.

open-sse/
├── index.ts                Esportazioni pubbliche
├── package.json            Manifest del workspace
├── tsconfig.json
├── types.d.ts
├── config/                 Registri dei provider, profili degli header, identità, …
├── handlers/               Gestori delle richieste (chat, embedding, audio, immagini, …)
├── executors/              108 esecutori HTTP specifici per provider
├── translator/             Conversione dei formati (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Trasformatore di stream Responses API ↔ Chat Completions
├── services/               Oltre 80 moduli di servizio (combinazioni, fallback, quote, identità, …)
├── utils/                  Utilità di streaming, client TLS, AWS SigV4, fetch tramite proxy, …
└── mcp-server/             Server MCP (3 trasporti, 33 ambiti, 110 strumenti)

4.1 open-sse/handlers/

Gestore	Scopo
chatCore.ts	Pipeline principale della chat (cache, limite di frequenza, instradamento delle combinazioni, invio all'esecutore)
responsesHandler.ts	Punto di ingresso dell'API Responses di OpenAI
embeddings.ts	Embedding
imageGeneration.ts	Generazione di immagini
audioSpeech.ts	Sintesi vocale
audioTranscription.ts	Trascrizione vocale
videoGeneration.ts	Generazione di video
musicGeneration.ts	Generazione di musica
rerank.ts	Riordinamento
moderations.ts	Moderazione
search.ts	Ricerca sul Web
sseParser.ts	Parser degli eventi SSE
usageExtractor.ts	Estrae il conteggio dei token dagli stream upstream
responseSanitizer.ts	Rimuove il rumore specifico del provider
responseTranslator.ts	Collegamento tra la risposta del provider e il livello di traduzione

4.2 open-sse/executors/

108 esecutori per provider, ciascuno dei quali estende 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, oltre a claudeIdentity.ts (helper condiviso per l'identità) e index.ts (registro).

Nota: i provider non elencati qui sono gestiti da default.ts mediante l'esecutore generico compatibile con OpenAI. Il catalogo completo dei provider (355 provider) si trova in src/shared/constants/providers.ts.

4.3 open-sse/translator/

Traduzione con architettura hub-and-spoke (OpenAI è l'hub).

• 9 traduttori di richieste (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 traduttori di risposte (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 helper (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, oltre ai test degli helper.
• Helper per le immagini (translator/image/sizeMapper.ts).
• Livello principale: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Convertitore Responses API ↔ Chat Completions basato su TransformStream (utilizzato dal catch-all della route responses/).

4.5 open-sse/services/

Elementi principali (elenco completo in open-sse/services/):

Area	File
Routing combinato	combo.ts (19 strategie), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Motore 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
Resilienza	accountFallback.ts (periodo di attesa + blocco), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Quote	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Memorizzazione cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Routing intelligente	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Gestione dei modelli	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Compressione	compression/ — cablaggio completo del motore di compressione
Token + sessione	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Livello / manifesto	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / rete	ipFilter.ts, webSearchFallback.ts
Batch	batchProcessor.ts
Utilizzo	usage.ts

4.6 open-sse/mcp-server/

• 110 strumenti univoci collegati in server.ts (45 canonici in schemas/tools.ts + moduli di memoria, competenze, competenze GitHub, pool, gamification, plugin, Notion, Obsidian, corpus locale e compressione — unione conteggiata da countUniqueMcpTools).
• 3 trasporti: stdio, HTTP Streamable, SSE.
• 33 ambiti applicati in fase di esecuzione — elenco di base in src/shared/constants/mcpScopes.ts; l'insieme completo è l'unione degli ambiti dichiarati da ciascun modulo degli strumenti.
• Tabella di audit: mcp_tool_audit (popolata da audit.ts).
• File: 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, oltre ai test in __tests__/.
• Consultare MCP-SERVER.md per il catalogo completo degli strumenti.

4.7 open-sse/config/

Registri dei provider (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registri dei modelli per formato (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), utilità per l'identità (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), utilità per le credenziali (credentialLoader.ts, codexClient.ts) e adattatori 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 di streaming e funzioni ausiliarie per i provider: 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                  Processo principale di Electron
├── preload.js               Bridge di preload (contextIsolation abilitato)
├── types.d.ts
├── package.json             Configurazione di electron-builder, versione 3.8.51
├── README.md
├── assets/                  Risorse di build (icone, entitlement, …)
├── node_modules/            node_modules dedicati (better-sqlite3, electron-updater)
└── dist-electron/           Output della build (non incluso nel repository)

Cinque script npm nella radice del workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. L'aggiornamento automatico avviene tramite electron-updater, che punta al feed delle release di GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Entry point principale della CLI (Node ESM)
├── reset-password.mjs      Reimposta la password di gestione dalla CLI
├── mcp-server.mjs          Avviatore del server MCP (stdio)
├── nodeRuntimeSupport.mjs  Controllo della versione di Node
└── cli/
    ├── program.mjs         Generatore del programma Commander
    ├── runtime.mjs         Helper withRuntime (prima il server, con fallback al DB)
    ├── output.mjs          Formattatori dell'output (json/jsonl/table/csv)
    ├── i18n.mjs            Helper t() con localizzazioni
    ├── api.mjs             Helper per le richieste API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Registrazione dei comandi
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (un file per comando/gruppo)

In package.json → bin sono esposti due eseguibili:

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

---

7. tests/

Directory	Tipo
tests/unit/	Test unitari tramite il test runner nativo di Node (1821 file, più le sottodirectory api/, auth/, authz/)
tests/integration/	Test tra moduli e dello stato del DB
tests/e2e/	Test dell'interfaccia utente con Playwright
tests/e2e/protocol-clients.test.ts	Test e2e dei protocolli MCP/A2A
tests/translator/	Test specifici del traduttore
tests/security/	Regressioni di sicurezza
tests/load/	Test di carico/stress
tests/golden-set/	Output di riferimento per le regressioni del traduttore
tests/helpers/, tests/fixtures/, tests/manual/	Supporto

Comandi comuni:

Comando	Cosa esegue
npm run test:unit	Tutti i test tests/unit/*.test.ts tramite il test runner di Node (concorrenza 10)
npm run test:vitest	Suite Vitest (MCP, autoCombo, cache)
npm run test:e2e	Suite dell'interfaccia utente Playwright
npm run test:protocols:e2e	Test e2e dei protocolli MCP + A2A
npm run test:coverage	Soglia di copertura (≥60% di righe/istruzioni/funzioni/rami)
node --import tsx/esm --test tests/unit/<file>.test.ts	Esecuzione di un singolo file

---

8. scripts/

Organizzata in 6 sottocartelle in base allo scopo.

• 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. Pipeline delle richieste (riepilogo)

Fonte: diagrams/request-pipeline.mmd

Richiesta del client
  → /v1/chat/completions (route.ts)
     Verifica preflight CORS
     Validazione Zod (chatCompletionsSchema in shared/validation/schemas.ts)
     Autenticazione (extractApiKey + isValidApiKey OPPURE requireManagementAuth)
     Motore delle policy (src/server/authz/pipeline.ts)
     Misure di protezione (mascheramento PII, prompt injection, bridge per la visione)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Verifica della cache (cache semantica + cache di lettura)
     Limite di frequenza (rateLimitManager, accountSemaphore)
     Instradamento combinato (se il modello viene risolto in una combinazione)
       comboResolver → ciclo per ciascuna destinazione → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       recupero dall'upstream → nuovo tentativo/backoff tramite accountFallback
     translateResponse() (open-sse/translator/response/*)
     Flusso SSE OPPURE risposta JSON
     Se si usa Responses API: TransformStream tramite open-sse/transformer/responsesTransformer.ts
  → Audit di conformità (src/lib/compliance/)
  → Risposta al client

Stato del runtime di resilienza (tre meccanismi)

Meccanismo	Ambito	Dove
Circuit breaker del provider	Intero provider	src/shared/utils/circuitBreaker.ts, persistito in domain_circuit_breakers
Cooldown della connessione	Un account/una chiave	markAccountUnavailable() in src/sse/services/auth.ts; utilizzato da accountFallback.checkFallbackError()
Blocco del modello	Provider + connessione + modello	open-sse/services/accountFallback.ts, persistito in domain_lockout_state

Consulta RESILIENCE_GUIDE.md e la sezione dedicata in CLAUDE.md.

---

10. Come contribuire

Aggiungere un nuovo provider

1. Registrarlo in src/shared/constants/providers.ts (validato con Zod al caricamento).
2. Aggiungere un executor in open-sse/executors/ se è necessaria una logica personalizzata (estendere BaseExecutor).
3. Aggiungere un translator in open-sse/translator/ se non utilizza il formato OpenAI.
4. Se è basato su OAuth, aggiungere la configurazione in src/lib/oauth/providers/ e src/lib/oauth/services/.
5. Registrare i modelli in open-sse/config/providerRegistry.ts (oppure nel registro specifico del formato in open-sse/config/).
6. Scrivere i test in tests/unit/.

Aggiungere una nuova route API

1. Creare src/app/api/your-route/route.ts.
2. Seguire il pattern: CORS → validazione del body con Zod → autenticazione → delega all'handler.
3. Se la struttura della richiesta è nuova: aggiungere lo schema Zod in src/shared/validation/schemas.ts.
4. Se è riservata alla gestione: aggiungere il percorso a src/shared/constants/publicApiRoutes.ts (denylist per la superficie dell'API pubblica).
5. Aggiungere i test in tests/unit/.
6. Aggiornare docs/reference/API_REFERENCE.md e docs/openapi.yaml.

Aggiungere un nuovo modulo DB

1. Creare src/lib/db/yourModule.ts e importare getDbInstance() da ./core.ts.
2. Esportare le funzioni CRUD per il proprio dominio.
3. Se sono presenti nuove tabelle: aggiungere una migrazione in src/lib/db/migrations/, numerata in sequenza, idempotente e transazionale.
4. Gli importatori utilizzano import diretti da @/lib/db/yourModule (nessun barrel: il precedente livello di riesportazione localDb.ts è stato rimosso).
5. Aggiungere i test in tests/unit/.

Aggiungere un nuovo strumento MCP

1. Aggiungere la definizione dello strumento in open-sse/mcp-server/tools/ (oppure estendere open-sse/mcp-server/schemas/tools.ts).
2. Assegnare gli scope appropriati in src/shared/constants/mcpScopes.ts.
3. Registrare lo strumento in open-sse/mcp-server/server.ts.
4. Aggiungere i test in open-sse/mcp-server/__tests__/.
5. Aggiornare MCP-SERVER.md.

Aggiungere una nuova skill A2A

Consultare A2A-SERVER.md § Aggiunta di una nuova skill. Le skill si trovano in src/lib/a2a/skills/ e vengono registrate tramite il task manager A2A.

---

11. Convenzioni

• Stile del codice: indentazione di 2 spazi, virgolette doppie, larghezza di 100 caratteri, punti e virgola, virgole finali es5 — applicati da Prettier tramite lint-staged.
• Import: esterni → interni (@/, @omniroute/open-sse) → relativi.
• Denominazione: file in camelCase o kebab-case, componenti in PascalCase, costanti in UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error ovunque; no-explicit-any = warn in open-sse/ e tests/, errore altrove.
• TypeScript: strict: false (impostazione legacy). Preferire tipi espliciti all'inferenza per i confini tra moduli.
• Database: non scrivere mai SQL grezzo nelle route o negli handler; passare sempre attraverso i moduli in src/lib/db/. Non eseguire mai import da barrel: utilizzare direttamente moduli src/lib/db/* specifici.
• Tipizzazione delle entità DB (#3512): una funzione che scrive o legge la struttura delle righe di una tabella DB deve accettare/restituire un'interfaccia TS con nome che rispecchi le colonne di tale tabella in rapporto 1:1, non any o un tipo anonimo inline nel punto di chiamata. Definire l'interfaccia accanto alla funzione (ad es. export interface UsageEntry in src/lib/usage/usageHistory.ts sopra saveRequestUsage), mantenere i singoli campi opzionali/nullable quando diversi writer popolano la riga in modo incrementale e preferire unknown a any per un campo la cui struttura varia tra i chiamanti (documentandolo nel campo; ad es. UsageEntry.tokens accetta sia i dati di utilizzo grezzi con la struttura del provider sia la struttura normalizzata). Quando il conteggio di any di un file raggiunge lo zero in questo modo, aggiungerlo alla allowlist di check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0), in modo da impedire regressioni. Questa è una convenzione relativa alla prima porzione: la più ampia eliminazione degli any anonimi viene eseguita iterativamente nel resto della codebase.
• Errori: utilizzare try/catch con tipi di errore specifici e registrare i log con il contesto pino. Non ignorare mai silenziosamente gli errori negli stream SSE; utilizzare segnali di interruzione per la pulizia.
• Sicurezza: non utilizzare mai eval() / new Function() / eval impliciti. Validare tutti gli input con Zod. Cifrare le credenziali archiviate (AES-256-GCM). Mantenere la denylist src/shared/constants/upstreamHeaders.ts allineata con il livello di sanitizzazione/validazione.
• Commit: Conventional Commits — feat(scope): subject. Scope consentiti: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branch: prefissi feat/, fix/, refactor/, docs/, test/, chore/. Non eseguire mai commit direttamente su main.
• Husky: il pre-commit esegue lint-staged + check:docs-sync + check:any-budget:t11; il pre-push esegue check:any-budget:t11 + check:tracked-artifacts (controlli rapidi; esclude test:unit).

---

12. Regole inderogabili (da CLAUDE.md)

1. Non eseguire mai il commit di segreti o credenziali.
2. Non usare mai barrel import: utilizzare direttamente i moduli specifici in src/lib/db/*.
3. Non usare mai eval() / new Function() / eval impliciti.
4. Non eseguire mai commit direttamente su main.
5. Non scrivere mai SQL grezzo nelle route: passare sempre attraverso i moduli in src/lib/db/.
6. Non ignorare mai silenziosamente gli errori negli stream SSE.
7. Convalidare sempre gli input con schemi Zod.
8. Includere sempre i test quando si modifica il codice di produzione.
9. La copertura deve rimanere ≥ 60% (istruzioni, righe, funzioni, rami).

---

13. Vedi anche

• ARCHITECTURE.md — architettura di alto livello e responsabilità dei moduli.
• API_REFERENCE.md — documentazione di riferimento delle API pubbliche e di gestione.
• FEATURES.md — matrice delle funzionalità e novità delle versioni.
• RESILIENCE_GUIDE.md — approfondimento su circuit breaker, cooldown e lockout.
• AUTO-COMBO.md — punteggio e strategie di Auto Combo.
• MCP-SERVER.md — catalogo completo degli strumenti MCP e relativi trasporti.
• A2A-SERVER.md — competenze e meccanismi di rilevamento del protocollo A2A.
• COMPRESSION_GUIDE.md — compressione RTK e Caveman.
• CLI-TOOLS.md — integrazioni CLI.
• ELECTRON_GUIDE.md (se presente), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — ambienti di destinazione per il deployment.
• TROUBLESHOOTING.md — problemi operativi comuni.
• CONTRIBUTING.md — flusso di lavoro per i collaboratori.
• CLAUDE.md — regole del repository per Claude Code (la fonte autorevole per molte delle convenzioni sopra indicate).
• AGENTS.md — riferimento architetturale più approfondito utilizzato dagli agenti.