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

OmniRoute Codebase Documentation (Français)

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

---

Version : v3.8.51 Dernière mise à jour : 2026-06-28 Public : Ingénieurs contribuant à OmniRoute ou développant des intégrations par-dessus celui-ci.

Pour consulter les schémas d’architecture généraux et comprendre les choix sous-jacents à chaque sous-système, lisez ARCHITECTURE.md. Pour une analyse approfondie de chaque sous-système (Auto Combo, serveur MCP, serveur A2A, Skills, Memory, Cloud Agents, Resilience, Compression, etc.), consultez les fichiers dédiés dans ce répertoire docs/.

Ce fichier décrit ce qui existe actuellement dans le dépôt afin qu’un nouvel ingénieur puisse parcourir l’arborescence, comprendre les différentes couches d’exécution et savoir où ajouter du code sans inventer de nouveaux modules.

---

1. Pile technologique

Aspect	Choix
Framework web	Next.js 16 (App Router, sortie autonome, aucun middleware global)
Langage	TypeScript 6.0+ — cible ES2022, module: esnext, moduleResolution: bundler, strict: false
Environnement d’exécution	Node.js >=22.22.2 <23 ou >=24.0.0 <27 (imposé via engines + SUPPORTED_NODE_RANGE)
Base de données	SQLite via better-sqlite3 (singleton, journalisation WAL)
Application de bureau	Electron 41 + electron-builder 26.10 (espace de travail distinct dans electron/)
Tests	Outil de test natif de Node (unitaires/intégration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Version autonome de Next.js via scripts/build/build-next-isolated.mjs
Lint/formatage	Configuration à plat ESLint + Prettier (lint-staged via le hook de pré-commit Husky)
Système de modules	ESM partout ("type": "module")
Espaces de travail	Espace de travail npm — open-sse est le seul sous-espace de travail

Alias de chemins (tsconfig.json) :

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

Port HTTP par défaut : 20128 (l’API et le tableau de bord partagent le même processus). Le répertoire de données est défini par la variable d’environnement DATA_DIR et utilise ~/.omniroute/ par défaut.

---

2. Structure du dépôt

OmniRoute/
├── src/                  Application Next.js (App Router, bibliothèques, domaine, serveur, éléments partagés)
├── open-sse/             Espace de travail du moteur de streaming (@omniroute/open-sse)
├── electron/             Enveloppe pour application de bureau (processus principal Electron 41 + preload)
├── bin/                  Points d’entrée de la CLI (omniroute, reset-password)
├── tests/                Tests unitaires, d’intégration, e2e, protocols-e2e, de traduction, de sécurité et fixtures
├── scripts/              Scripts utilitaires de build, synchronisation, vérification, migration et exécution
├── docs/                 Documentation publique (ce répertoire)
├── public/               Ressources statiques, manifeste PWA, service worker
├── config/               Exemples de configuration d’exécution
├── images/               Ressources marketing/captures d’écran
├── _ideia/, _references/, _mono_repo/, _tasks/   Brouillons internes / planification (non distribués)
├── CLAUDE.md             Règles du dépôt pour Claude Code
├── AGENTS.md             Référence d’architecture plus approfondie pour les agents
├── package.json          v3.8.51, racine de l’espace de travail
└── tsconfig.json         Alias de chemins + principales options du compilateur

---

3. src/ — Application Next.js

src/
├── app/                  Pages de l’App Router + routes d’API
├── lib/                  Bibliothèques principales (BDD, authentification, OAuth, compétences, mémoire, …)
├── domain/               Couche de domaine pure (politique, repli, coût, verrouillage, …)
├── server/               Modules réservés au serveur (autorisation, CORS, authentification)
├── shared/               Types, constantes, validation, contrats, utilitaires (compatibles entre les différentes couches)
├── mitm/                 Utilitaires de proxy de type homme-du-milieu pour l’intégration CLI
├── models/               Métadonnées et alias des modèles locaux
├── sse/                  Anciens gestionnaires SSE toujours présents sous src/ (et non open-sse/)
├── store/                Magasins d’état côté client
├── middleware/           Utilitaires de middleware au niveau des routes (et non middleware global Next.js)
├── scripts/              Scripts internes importables par le code de l’application
├── types/                Types TS ambiants et partagés
├── i18n/                 Ressources linguistiques
├── instrumentation.ts    Point d’entrée d’instrumentation Next.js
├── instrumentation-node.ts
└── proxy.ts              Utilitaire d’amorçage du proxy de premier niveau

3.1 src/app/ — App Router

L’App Router expose à la fois l’interface utilisateur du tableau de bord et l’API HTTP publique/de gestion. Il n’existe aucun middleware global — l’interception est effectuée route par route.

Segments de premier niveau sous src/app/ :

Chemin	Objectif
api/	Toutes les routes d’API HTTP (voir le détail ci-dessous)
a2a/	Point de terminaison A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Document de découverte de l’Agent Card A2A
(dashboard)/	Interface utilisateur du tableau de bord (groupe de routes, sans préfixe d’URL)
auth/, login/, forgot-password/, callback/	Flux d’authentification
landing/	Page marketing/d’accueil
docs/	Visionneuse intégrée de la documentation de l’API
status/, maintenance/, offline/	Pages opérationnelles
privacy/, terms/	Pages juridiques
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Pages d’erreur statiques
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Limites d’erreur/de chargement du framework
layout.tsx, page.tsx, globals.css, manifest.ts	Structure racine

3.1.1 src/app/(dashboard)/dashboard/ — Pages de l’interface utilisateur

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, ainsi que les fichiers racines page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Groupes d’API de premier niveau

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/   Gestion des services intégrés (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API publique compatible avec OpenAI
├── v1beta/     Compatibilité de type Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Gestion des services intégrés

Routes permettant d’installer, de démarrer, d’arrêter et de surveiller 9Router et CLIProxyAPI. Tous les chemins sont classés LOCAL_ONLY (boucle locale uniquement, règle stricte nº 17), car ils peuvent invoquer npm install et générer des processus enfants.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             fonction utilitaire getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install via 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 d’une version plus récente
│   ├── rotate-key/route.ts POST — générer une nouvelle clé d’API + redémarrer
│   ├── status/route.ts     GET  — état en direct + état de la BDD + métadonnées de version
│   └── auto-start/route.ts POST — activer/désactiver l’indicateur auto_start
├── cliproxy/
│   ├── _lib.ts             fonction utilitaire 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 d’une version plus récente
│   ├── status/route.ts     GET  — état en direct + état de la BDD + métadonnées de version
│   └── auto-start/route.ts POST — activer/désactiver l’indicateur auto_start
└── [name]/
    └── logs/route.ts       GET  — suivi des journaux via SSE (partagé par tous les services)

Interface utilisateur correspondante du tableau de bord : src/app/(dashboard)/dashboard/providers/services/ — page à deux onglets (CLIProxyAPI + 9Router). Proxy inverse pour l’interface utilisateur intégrée de 9Router : src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Présentation détaillée : docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API publique compatible avec OpenAI

v1/
├── accounts/[id]/                       recherche de compte
├── agents/tasks/[id]/, agents/tasks/    points de terminaison de tâches inspirés d’A2A
├── api/                                 fonctions utilitaires d’API internes exposées sous v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API OpenAI Batches
├── chat/completions/                    Chat Completions (point de terminaison principal)
├── completions/                         complétions de texte héritées
├── embeddings/                          plongements vectoriels
├── files/[id]/, files/                  API Files
├── _helpers/                            fonctions utilitaires de route partagées (aucune URL publique)
├── images/{edits, generations}/         génération + modification d’images
├── issues/                              points de terminaison utilitaires pour le triage
├── management/{proxies}/                routes dédiées à la gestion dans v1
├── messages/{count_tokens}/             compatibilité avec les messages de style Anthropic
├── models/                              liste des modèles (`route.ts`, `catalog.ts`)
├── moderations/                         modération
├── music/                               génération de musique
├── providers/[provider]/                opérations propres à chaque fournisseur
├── quotas/{check}                       sondes de quota
├── registered-keys/                     administration des clés enregistrées
├── rerank/                              reclassement
├── responses/[...path]/                 API OpenAI Responses (route générique)
├── search/                              recherche Web
├── videos/                              génération de vidéos
├── ws/                                  passerelle WebSocket
└── route.ts                             gestionnaire d’index

Chaque fichier de route suit le même modèle :

Route → requête préliminaire CORS → validation du corps avec Zod → authentification facultative
      → application de la politique des clés d’API → délégation au gestionnaire (open-sse)

v1beta/ est l’interface de compatibilité de style Gemini (une fine couche qui traduit vers le même pipeline open-sse/handlers/).

3.2 src/lib/ — Bibliothèques principales

Importez toujours les données, la synchronisation, OAuth, les compétences, la mémoire, etc. par l’intermédiaire de ces modules. Le tableau regroupe les répertoires réels et les fichiers de premier niveau notables.

Module	Objectif
a2a/	Serveur du protocole A2A : taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 compétences : analyse des coûts, rapport d’état, découverte des fournisseurs, gestion des quotas, routage intelligent, list-capabilities)
acp/	Agent-Control-Protocol : index.ts, manager.ts, registry.ts
api/	Utilitaires d’API internes : requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (réinitialisation / hachage du mot de passe)
batches/	Service de l’API Batches d’OpenAI (service.ts)
catalog/	Synchronisation du catalogue OpenRouter (openrouterCatalog.ts)
cloudAgent/	Registre des agents cloud : api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Utilitaires de résolution des combinaisons
compliance/	Audit + audit des fournisseurs : index.ts, providerAudit.ts
config/	Couche d’intégration de la configuration d’exécution
db/	Modules de domaine SQLite (voir §3.2.1)
display/	Utilitaires d’interface et d’affichage utilisés par les réponses de l’API
embeddings/	Registre des services d’embeddings
env/	Chargement + introspection de l’environnement
evals/	Environnement d’exécution des évaluations
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Tâches en arrière-plan (autoUpdate.ts, …)
memory/	Mémoire persistante : 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/	Modules OAuth/d’importation de fournisseurs (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, ainsi que services/, utils/ et constants/oauth.ts
plugins/	Chargeur de plugins (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Cycle de vie des modèles gérés : modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Utilitaires pour les fournisseurs : catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — paramètres du disjoncteur, du délai de récupération et du verrouillage
runtime/	Détection des fonctionnalités d’exécution
search/	executeWebSearch.ts
services/	Framework de services intégrés : ServiceSupervisor.ts (superviseur générique de processus enfant avec verrouillage des opérations, tampon circulaire et vérificateur d’état), bootstrap.ts (enregistrement au niveau du processus et démarrage automatique), registry.ts (association outil → superviseur), apiKey.ts (stockage de clés AES-256-GCM), modelSync.ts (synchronisation périodique des modèles), ringBuffer.ts (tampon circulaire de journaux de 5 Mo), healthCheck.ts (sonde d’état HTTP), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Voir docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Catalogue + générateur de compétences d’agent : catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → écrit dans skills/{id}/SKILL.md), openapiParser.ts (extrait les points de terminaison REST de la spécification OpenAPI), cliRegistryParser.ts (extrait les sous-commandes CLI de bin/cli-registry), schemas.ts (Zod : AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Utilisé par les routes REST (/api/agent-skills/*), les outils MCP (omniroute_agent_skills_*) et la compétence A2A list-capabilities. Voir AGENT-SKILLS.md.
skills/	Framework de compétences : 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, ainsi que builtin/browser.ts
spend/	batchWriter.ts (tampon d’écriture différée)
sync/	bundle.ts, tokens.ts (synchronisation cloud)
system/	Utilitaires au niveau du système
translator/	Couche d’intégration de haut niveau du traducteur (délègue à open-sse/translator/)
usage/	Comptabilisation de l’utilisation : costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Mise à jour automatique + manifeste de version
ws/	Passerelle WebSocket
zed-oauth/	Flux OAuth de l’éditeur Zed

Fichiers de premier niveau dans src/lib/ :

• L’ancien fichier d’agrégation localDb.ts a été supprimé — les consommateurs importent directement les modules src/lib/db/* spécifiques.
• 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/

Base de données SQLite singleton (getDbInstance() dans core.ts, journalisation WAL). N’écrivez jamais de SQL brut dans les routes ou les gestionnaires — passez par ces modules.

Source : diagrams/db-schema-overview.mmd

Modules de domaine (chacun gère une ou plusieurs tables) : 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/ contient 168 fichiers .sql versionnés (idempotents et transactionnels) et est exécuté par migrationRunner.ts au démarrage.

Tables créées au fil des migrations (123 au 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 (ainsi que des tables virtuelles FTS5 pour la recherche dans la mémoire).

3.3 src/domain/ — Couche domaine

Logique métier pure, sans E/S. Importée par les routes et les gestionnaires.

Fichier	Rôle
policyEngine.ts	Résolveur de politiques de haut niveau
fallbackPolicy.ts	Arbre de décision de repli
costRules.ts	Règles de calcul des coûts
lockoutPolicy.ts	Décisions de verrouillage des modèles
tagRouter.ts	Routage basé sur les balises
comboResolver.ts	Résolution des combinaisons de la requête → liste de cibles
connectionModelRules.ts	Filtres de modèles propres à chaque connexion
modelAvailability.ts	Vérification de la disponibilité des modèles
degradation.ts	Transitions vers le mode dégradé
providerExpiration.ts	Détection des comptes/clés expirés
quotaCache.ts	Décisions de quota mises en cache
responses.ts, omnirouteResponseMeta.ts	Utilitaires de mise en forme des réponses
configAudit.ts	Audit des modifications de configuration
assessment/	Évaluation des modèles (selon la RFC, partiellement implémentée)
types.ts	Types de domaine partagés

3.4 src/server/ — Serveur uniquement

Ne peut pas être importé depuis les composants clients.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Classe les routes comme publiques ou de gestion
│   ├── assertAuth.ts      Utilitaire d’assertion
│   ├── context.ts         Contexte d’autorisation propre à chaque requête
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline d’autorisation
│   ├── policies/          Politiques concrètes
│   └── types.ts
└── cors/origins.ts        Liste d’autorisation des origines CORS

3.5 src/shared/ — Partageable sans risque

Divisé en sous-répertoires spécialisés :

• constants/ — providers.ts (catalogue de fournisseurs validé par Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (liste de refus), 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 (environ 80 schémas Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — contrats d’API publique distribués sur npm.
• types/ — types TS partagés.
• 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, ainsi que les hooks/composants du tableau de bord dans services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Espace de travail du moteur de streaming

Espace de travail npm distinct publié sous le nom @omniroute/open-sse. Il gère le traitement des requêtes, les exécuteurs, les traducteurs, les services, le transformateur et le serveur MCP.

open-sse/
├── index.ts                Exports publics
├── package.json            Manifeste de l’espace de travail
├── tsconfig.json
├── types.d.ts
├── config/                 Registres de fournisseurs, profils d’en-têtes, identité, …
├── handlers/               Gestionnaires de requêtes (chat, embeddings, audio, image, …)
├── executors/              108 exécuteurs HTTP propres aux fournisseurs
├── translator/             Conversion de formats (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformateur de flux Responses API ↔ Chat Completions
├── services/               Plus de 80 modules de service (combinaisons, repli, quotas, identité, …)
├── utils/                  Utilitaires de streaming, client TLS, AWS SigV4, récupération via proxy, …
└── mcp-server/             Serveur MCP (3 transports, 33 portées, 110 outils)

4.1 open-sse/handlers/

Gestionnaire	Rôle
chatCore.ts	Pipeline de chat principal (cache, limitation du débit, routage des combinaisons, répartition vers les exécuteurs)
responsesHandler.ts	Point d’entrée de l’API Responses d’OpenAI
embeddings.ts	Embeddings
imageGeneration.ts	Génération d’images
audioSpeech.ts	Synthèse vocale à partir de texte
audioTranscription.ts	Transcription de la parole en texte
videoGeneration.ts	Génération de vidéos
musicGeneration.ts	Génération de musique
rerank.ts	Reclassement
moderations.ts	Modération
search.ts	Recherche sur le Web
sseParser.ts	Analyseur d’événements SSE
usageExtractor.ts	Extraction du nombre de jetons depuis les flux en amont
responseSanitizer.ts	Suppression des données parasites propres aux fournisseurs
responseTranslator.ts	Liaison entre la réponse du fournisseur et la couche de traduction

4.2 open-sse/executors/

108 exécuteurs de fournisseurs, chacun étendant 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, ainsi que claudeIdentity.ts (utilitaire d’identité partagé) et index.ts (registre).

Remarque : les fournisseurs qui ne figurent pas ici sont pris en charge par default.ts au moyen de l’exécuteur générique compatible avec OpenAI. Le catalogue complet des fournisseurs (355 fournisseurs) se trouve dans src/shared/constants/providers.ts.

4.3 open-sse/translator/

Traduction en étoile (OpenAI constitue le centre).

• 9 traducteurs de requêtes (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 traducteurs de réponses (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 utilitaires (translator/helpers/) : claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, ainsi que les tests des utilitaires.
• Utilitaires pour les images (translator/image/sizeMapper.ts).
• À la racine : bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Convertisseur Responses API ↔ Chat Completions basé sur TransformStream (utilisé par la route générique responses/).

4.5 open-sse/services/

Points notables (liste complète dans open-sse/services/) :

Préoccupation	Fichiers
Routage Combo	combo.ts (19 stratégies), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Moteur 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
Résilience	accountFallback.ts (délai de récupération + verrouillage), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Quotas	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Mise en cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Intelligence de routage	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Gestion des modèles	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Compression	compression/ — câblage complet du moteur de compression
Jetons + session	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Niveau / manifeste	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / réseau	ipFilter.ts, webSearchFallback.ts
Lots	batchProcessor.ts
Utilisation	usage.ts

4.6 open-sse/mcp-server/

• 110 outils uniques câblés dans server.ts (45 canoniques dans schemas/tools.ts + modules de mémoire, de compétences, de compétences GitHub, de pool, de ludification, de plugin, Notion, Obsidian, de corpus local et de compression — union dénombrée par countUniqueMcpTools).
• 3 transports : stdio, HTTP Streamable, SSE.
• 33 portées appliquées à l’exécution — liste de base dans src/shared/constants/mcpScopes.ts, l’ensemble complet étant l’union des portées déclarées par chaque module d’outils.
• Table d’audit : mcp_tool_audit (alimentée par audit.ts).
• Fichiers : 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, ainsi que les tests sous __tests__/.
• Consultez MCP-SERVER.md pour le catalogue complet des outils.

4.7 open-sse/config/

Registres de fournisseurs (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registres de modèles par format (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), utilitaires d’identité (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), utilitaires d’identifiants (credentialLoader.ts, codexClient.ts) et adaptateurs 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/

Primitives de streaming et utilitaires pour les fournisseurs : 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/ — Enveloppe de bureau

electron/
├── main.js                  Processus principal Electron
├── preload.js               Pont de préchargement (contextIsolation activé)
├── types.d.ts
├── package.json             Configuration electron-builder, version 3.8.51
├── README.md
├── assets/                  Ressources de build (icônes, droits, …)
├── node_modules/            node_modules dédiés (better-sqlite3, electron-updater)
└── dist-electron/           Sortie de build (non versionnée)

Cinq scripts npm à la racine de l’espace de travail : electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. La mise à jour automatique s’effectue via electron-updater, qui pointe vers le flux des versions publiées sur GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Point d’entrée principal de la CLI (Node ESM)
├── reset-password.mjs      Réinitialise le mot de passe de gestion depuis la CLI
├── mcp-server.mjs          Lanceur du serveur MCP (stdio)
├── nodeRuntimeSupport.mjs  Vérification de la version de Node
└── cli/
    ├── program.mjs         Générateur de programme Commander
    ├── runtime.mjs         Utilitaire withRuntime (serveur en priorité/repli sur la base de données)
    ├── output.mjs          Formateurs de sortie (json/jsonl/table/csv)
    ├── i18n.mjs            Utilitaire t() avec paramètres régionaux
    ├── api.mjs             Utilitaire de requêtes API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Enregistrement des commandes
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (un fichier par commande/groupe)

Deux exécutables sont exposés dans package.json → bin :

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

---

7. tests/

Répertoire	Type
tests/unit/	Tests unitaires via le lanceur de tests natif de Node (1821 fichiers, plus les sous-répertoires api/, auth/, authz/)
tests/integration/	Tests intermodules et de l’état de la base de données
tests/e2e/	Tests d’interface utilisateur Playwright
tests/e2e/protocol-clients.test.ts	Tests e2e des protocoles MCP/A2A
tests/translator/	Tests propres au traducteur
tests/security/	Tests de régression de sécurité
tests/load/	Tests de charge / de stress
tests/golden-set/	Sorties de référence pour les régressions du traducteur
tests/helpers/, tests/fixtures/, tests/manual/	Fichiers de support

Commandes courantes :

Commande	Ce qu’elle exécute
npm run test:unit	Tous les fichiers tests/unit/*.test.ts via le lanceur de tests de Node (concurrence de 10)
npm run test:vitest	Suite Vitest (MCP, autoCombo, cache)
npm run test:e2e	Suite d’interface utilisateur Playwright
npm run test:protocols:e2e	Tests e2e des protocoles MCP + A2A
npm run test:coverage	Seuil de couverture (≥60 % des lignes/instructions/fonctions/branches)
node --import tsx/esm --test tests/unit/<file>.test.ts	Exécution d’un seul fichier

---

8. scripts/

Organisé en 6 sous-dossiers selon leur fonction.

• 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 de requête (résumé)

Source : diagrams/request-pipeline.mmd

Requête du client
  → /v1/chat/completions (route.ts)
     Vérification préalable CORS
     Validation Zod (chatCompletionsSchema dans shared/validation/schemas.ts)
     Authentification (extractApiKey + isValidApiKey OU requireManagementAuth)
     Moteur de politiques (src/server/authz/pipeline.ts)
     Mesures de protection (masquage des PII, injection de prompt, passerelle de vision)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Vérification du cache (cache sémantique + cache de lecture)
     Limitation du débit (rateLimitManager, accountSemaphore)
     Routage combiné (si le modèle correspond à une combinaison)
       comboResolver → boucle par cible → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       récupération en amont → nouvelle tentative/temporisation via accountFallback
     translateResponse() (open-sse/translator/response/*)
     Flux SSE OU réponse JSON
     Si Responses API : TransformStream via open-sse/transformer/responsesTransformer.ts
  → Audit de conformité (src/lib/compliance/)
  → Réponse au client

État d’exécution de la résilience (trois mécanismes)

Mécanisme	Portée	Emplacement
Disjoncteur du fournisseur	Fournisseur entier	src/shared/utils/circuitBreaker.ts, persisté dans domain_circuit_breakers
Délai de récupération de la connexion	Un compte/une clé	markAccountUnavailable() dans src/sse/services/auth.ts ; utilisé par accountFallback.checkFallbackError()
Verrouillage du modèle	Fournisseur + connexion + modèle	open-sse/services/accountFallback.ts, persisté dans domain_lockout_state

Consultez RESILIENCE_GUIDE.md ainsi que la section dédiée dans CLAUDE.md.

---

10. Comment contribuer

Ajouter un nouveau fournisseur

1. Enregistrez-le dans src/shared/constants/providers.ts (validé par Zod au chargement).
2. Ajoutez un exécuteur dans open-sse/executors/ si une logique personnalisée est requise (étendez BaseExecutor).
3. Ajoutez un traducteur dans open-sse/translator/ s'il n'utilise pas le format OpenAI.
4. S'il repose sur OAuth, ajoutez la configuration sous src/lib/oauth/providers/ et src/lib/oauth/services/.
5. Enregistrez les modèles dans open-sse/config/providerRegistry.ts (ou dans le registre propre au format sous open-sse/config/).
6. Écrivez les tests sous tests/unit/.

Ajouter une nouvelle route d'API

1. Créez src/app/api/your-route/route.ts.
2. Suivez le modèle : CORS → validation du corps avec Zod → authentification → délégation au gestionnaire.
3. Pour une nouvelle structure de requête : ajoutez le schéma Zod dans src/shared/validation/schemas.ts.
4. Si la route est réservée à la gestion : ajoutez le chemin à src/shared/constants/publicApiRoutes.ts (liste de refus pour la surface de l'API publique).
5. Ajoutez les tests sous tests/unit/.
6. Mettez à jour docs/reference/API_REFERENCE.md et docs/openapi.yaml.

Ajouter un nouveau module de base de données

1. Créez src/lib/db/yourModule.ts et importez getDbInstance() depuis ./core.ts.
2. Exportez les fonctions CRUD de votre domaine.
3. Pour de nouvelles tables : ajoutez une migration sous src/lib/db/migrations/, numérotée séquentiellement, idempotente et transactionnelle.
4. Les modules importateurs utilisent des imports directs depuis @/lib/db/yourModule (pas de fichier d'agrégation — l'ancienne couche de réexportation localDb.ts a été supprimée).
5. Ajoutez les tests sous tests/unit/.

Ajouter un nouvel outil MCP

1. Ajoutez la définition de l'outil sous open-sse/mcp-server/tools/ (ou étendez open-sse/mcp-server/schemas/tools.ts).
2. Attribuez la ou les portées appropriées dans src/shared/constants/mcpScopes.ts.
3. Enregistrez l'outil dans open-sse/mcp-server/server.ts.
4. Ajoutez les tests sous open-sse/mcp-server/__tests__/.
5. Mettez à jour MCP-SERVER.md.

Ajouter une nouvelle compétence A2A

Consultez A2A-SERVER.md § Ajout d'une nouvelle compétence. Les compétences se trouvent dans src/lib/a2a/skills/ et sont enregistrées par l'intermédiaire du gestionnaire de tâches A2A.

---

11. Conventions

• Style du code : indentation de 2 espaces, guillemets doubles, largeur de 100 caractères, points-virgules, virgules finales es5 — imposés par Prettier via lint-staged.
• Imports : externes → internes (@/, @omniroute/open-sse) → relatifs.
• Nommage : fichiers en camelCase ou kebab-case, composants en PascalCase, constantes en UPPER_SNAKE.
• ESLint : no-eval, no-implied-eval, no-new-func = error partout ; no-explicit-any = warn dans open-sse/ et tests/, erreur ailleurs.
• TypeScript : strict: false (positionnement historique). Préférez les types explicites à l'inférence aux frontières entre modules.
• Base de données : n'écrivez jamais de SQL brut dans les routes ou les gestionnaires — passez toujours par les modules de src/lib/db/. N'effectuez jamais d'import depuis un fichier d'agrégation — utilisez directement les modules src/lib/db/* spécifiques.
• Typage des entités de base de données (#3512) : une fonction qui écrit ou lit la structure d'une ligne de table de base de données doit accepter/renvoyer une interface TS nommée reflétant les colonnes de cette table à l'identique, et non any ou un type anonyme défini directement sur le site d'appel. Placez l'interface à côté de la fonction (par exemple, export interface UsageEntry dans src/lib/usage/usageHistory.ts au-dessus de saveRequestUsage), laissez les champs individuels facultatifs/nullables lorsque différents producteurs remplissent la ligne progressivement, et préférez unknown à any pour un champ dont la structure varie selon les appelants (documentez-le sur le champ ; par exemple, UsageEntry.tokens accepte à la fois les données d'utilisation brutes structurées par le fournisseur et la structure normalisée). Lorsque le nombre de any d'un fichier atteint zéro de cette manière, ajoutez-le à la liste d'autorisation check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) afin d'éviter toute régression. Il s'agit d'une convention initiale et ciblée — le nettoyage plus large visant à éliminer les « any anonymes » est réalisé de manière itérative dans le reste de la base de code.
• Erreurs : utilisez try/catch avec des types d'erreurs spécifiques et journalisez avec le contexte pino. Ne masquez jamais silencieusement les erreurs dans les flux SSE ; utilisez des signaux d'abandon pour le nettoyage.
• Sécurité : n'utilisez jamais eval() / new Function() / d'évaluation implicite. Validez toutes les entrées avec Zod. Chiffrez les identifiants au repos (AES-256-GCM). Maintenez la liste de refus src/shared/constants/upstreamHeaders.ts alignée avec la couche d'assainissement/validation.
• Commits : Conventional Commits — feat(scope): subject. Portées autorisées : db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branches : préfixes feat/, fix/, refactor/, docs/, test/, chore/. Ne faites jamais de commit directement sur main.
• Husky : le hook de pré-commit exécute lint-staged + check:docs-sync + check:any-budget:t11 ; le hook de pré-push exécute check:any-budget:t11 + check:tracked-artifacts (contrôles rapides ; exclut test:unit).

---

12. Règles strictes (issues de CLAUDE.md)

1. Ne validez jamais de secrets ni d’identifiants.
2. N’utilisez jamais d’importation groupée — utilisez directement les modules src/lib/db/* spécifiques.
3. N’utilisez jamais eval() / new Function() / une évaluation implicite.
4. Ne validez jamais directement dans main.
5. N’écrivez jamais de SQL brut dans les routes — passez toujours par les modules src/lib/db/.
6. N’ignorez jamais silencieusement les erreurs dans les flux SSE.
7. Validez toujours les entrées avec des schémas Zod.
8. Incluez toujours des tests lorsque vous modifiez le code de production.
9. La couverture doit rester ≥ 60 % (instructions, lignes, fonctions, branches).

---

13. Voir aussi

• ARCHITECTURE.md — architecture générale et responsabilités des modules.
• API_REFERENCE.md — référence des API publiques et de gestion.
• FEATURES.md — matrice des fonctionnalités et points forts des versions.
• RESILIENCE_GUIDE.md — présentation détaillée du disjoncteur, du délai de récupération et du verrouillage.
• AUTO-COMBO.md — notation et stratégies d’Auto Combo.
• MCP-SERVER.md — catalogue complet des outils MCP et modes de transport.
• A2A-SERVER.md — compétences et découverte du protocole A2A.
• COMPRESSION_GUIDE.md — compression RTK et Caveman.
• CLI-TOOLS.md — intégrations CLI.
• ELECTRON_GUIDE.md (si présent), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — cibles de déploiement.
• TROUBLESHOOTING.md — problèmes opérationnels courants.
• CONTRIBUTING.md — flux de travail des contributeurs.
• CLAUDE.md — règles du dépôt pour Claude Code (la source de référence pour de nombreuses conventions ci-dessus).
• AGENTS.md — référence architecturale plus approfondie utilisée par les agents.