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

OmniRoute Codebase Documentation (Nederlands)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇴 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

---

Versie: v3.8.51 Laatst bijgewerkt: 2026-06-28 Doelgroep: Engineers die bijdragen aan OmniRoute of daarop integraties bouwen.

Lees voor architectuurdiagrammen op hoofdlijnen en de overwegingen achter elk subsysteem ARCHITECTURE.md. Raadpleeg voor diepgaande informatie over afzonderlijke subsystemen (Auto Combo, MCP-server, A2A-server, Skills, Memory, Cloud Agents, Resilience, Compression enz.) de bijbehorende bestanden in deze docs/-directory.

Dit bestand beschrijft wat er momenteel in de repository aanwezig is, zodat een nieuwe engineer door de structuur kan navigeren, de gelaagdheid van de runtime kan begrijpen en weet waar code moet worden toegevoegd zonder nieuwe modules te bedenken.

---

1. Technologiestack

Aandachtsgebied	Keuze
Webframework	Next.js 16 (App Router, zelfstandige uitvoer, geen globale middleware)
Taal	TypeScript 6.0+ — target ES2022, module: esnext, moduleResolution: bundler, strict: false
Runtime	Node.js >=22.22.2 <23 of >=24.0.0 <27 (afgedwongen via engines + SUPPORTED_NODE_RANGE)
Database	SQLite via better-sqlite3 (singleton, WAL-journaling)
Desktop	Electron 41 + electron-builder 26.10 (afzonderlijke workspace in electron/)
Tests	Ingebouwde Node-testrunner (unit/integratie), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Zelfstandige Next.js-build via scripts/build/build-next-isolated.mjs
Lint/format	Platte ESLint-configuratie + Prettier (lint-staged via Husky pre-commit)
Modulesysteem	Overal ESM ("type": "module")
Workspaces	npm-workspace — open-sse is de enige subworkspace

Padaliassen (tsconfig.json):

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

Standaard-HTTP-poort: 20128 (API en dashboard delen hetzelfde proces). De gegevensdirectory wordt bepaald door de omgevingsvariabele DATA_DIR en is standaard ~/.omniroute/.

---

2. Repositorystructuur

OmniRoute/
├── src/                  Next.js-applicatie (App Router, bibliotheken, domein, server, gedeelde code)
├── open-sse/             Workspace voor de streaming-engine (@omniroute/open-sse)
├── electron/             Desktopwrapper (Electron 41-hoofdproces + preload)
├── bin/                  CLI-toegangspunten (omniroute, reset-password)
├── tests/                Unit-, integratie-, e2e-, protocols-e2e-, vertaler- en beveiligingstests en fixtures
├── scripts/              Hulp-scripts voor builds, synchronisatie, controles, migraties en runtime
├── docs/                 Openbare documentatie (deze directory)
├── public/               Statische assets, PWA-manifest, service worker
├── config/               Voorbeelden van runtimeconfiguratie
├── images/               Marketing- en schermafbeeldingsassets
├── _ideia/, _references/, _mono_repo/, _tasks/   Interne klad- en planningsbestanden (niet meegeleverd)
├── CLAUDE.md             Repositoryregels voor Claude Code
├── AGENTS.md             Uitgebreidere architectuurreferentie voor agents
├── package.json          v3.8.51, hoofdmap van de workspace
└── tsconfig.json         Padaliassen + kernopties voor de compiler

---

3. src/ — Next.js-applicatie

src/
├── app/                  App Router-pagina's + API-routes
├── lib/                  Kernbibliotheken (DB, auth, OAuth, skills, geheugen, …)
├── domain/               Zuivere domeinlaag (beleid, fallback, kosten, vergrendeling, …)
├── server/               Alleen-servermodules (authz, cors, auth)
├── shared/               Typen, constanten, validatie, contracten, hulpprogramma's (veilig over grenzen heen)
├── mitm/                 Man-in-the-middle-proxyhelpers voor CLI-integratie
├── models/               Lokale modelmetadata / aliassen
├── sse/                  Verouderde SSE-handlers die nog onder src/ staan (niet open-sse/)
├── store/                Statusopslag aan clientzijde
├── middleware/           Middleware-hulpprogramma's op routeniveau (geen globale Next.js-middleware)
├── scripts/              Scripts in de bronstructuur die door applicatiecode kunnen worden geïmporteerd
├── types/                Ambient en gedeelde TS-typen
├── i18n/                 Localisatiebundels
├── instrumentation.ts    Next.js-instrumentatiehook
├── instrumentation-node.ts
└── proxy.ts              Bootstraphelper voor de proxy op het hoogste niveau

3.1 src/app/ — App Router

De App Router biedt zowel de dashboard-UI als de openbare/beheer-HTTP-API. Er is geen globale middleware — interceptie gebeurt per route.

Segmenten op het hoogste niveau onder src/app/:

Pad	Doel
api/	Alle HTTP-API-routes (zie uitsplitsing hieronder)
a2a/	A2A JSON-RPC 2.0-eindpunt (POST /a2a)
.well-known/agent.json/	A2A Agent Card-detectiedocument
(dashboard)/	Dashboard-UI (routegroep, geen URL-prefix)
auth/, login/, forgot-password/, callback/	Authenticatiestromen
landing/	Marketing-/landingspagina
docs/	Ingesloten API-documentatieweergave
status/, maintenance/, offline/	Operationele pagina's
privacy/, terms/	Juridische pagina's
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Statische foutpagina's
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Frameworkgrenzen voor fouten/laden
layout.tsx, page.tsx, globals.css, manifest.ts	Rootshell

3.1.1 src/app/(dashboard)/dashboard/ — UI-pagina's

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 root page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — API-groepen op het hoogste 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/   Beheer van ingesloten services (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-compatibele openbare API
├── v1beta/     Compatibiliteit in Gemini-stijl
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Beheer van ingesloten services

Routes voor het installeren, starten, stoppen en bewaken van 9Router en CLIProxyAPI. Alle paden zijn geclassificeerd als LOCAL_ONLY (alleen loopback, harde regel #17), omdat ze npm install kunnen aanroepen en onderliggende processen kunnen starten.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor()-helper
│   ├── install/route.ts    POST — npm-installatie via execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — nieuwere versie installeren met npm
│   ├── rotate-key/route.ts POST — nieuwe API-sleutel genereren + opnieuw starten
│   ├── status/route.ts     GET  — live- en DB-status + versiemetadata
│   └── auto-start/route.ts POST — auto_start-vlag omschakelen
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor()-helper
│   ├── install/route.ts    POST — npm-installatie
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — nieuwere versie installeren met npm
│   ├── status/route.ts     GET  — live- en DB-status + versiemetadata
│   └── auto-start/route.ts POST — auto_start-vlag omschakelen
└── [name]/
    └── logs/route.ts       GET  — SSE-logstaart (gedeeld door alle services)

Bijbehorende dashboardinterface: src/app/(dashboard)/dashboard/providers/services/ — pagina met twee tabbladen (CLIProxyAPI + 9Router). Reverse proxy voor de ingebedde interface van 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Verdieping: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-compatibele openbare API

v1/
├── accounts/[id]/                       account opzoeken
├── agents/tasks/[id]/, agents/tasks/    taakendpoints in A2A-stijl
├── api/                                 interne API-helpers beschikbaar onder v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (het belangrijkste endpoint)
├── completions/                         verouderde tekstaanvullingen
├── embeddings/                          embeddings
├── files/[id]/, files/                  Files API
├── _helpers/                            gedeelde routehelpers (geen openbare URL)
├── images/{edits, generations}/         afbeeldingen genereren + bewerken
├── issues/                              helperendpoints voor triage
├── management/{proxies}/                beheergerichte routes binnen v1
├── messages/{count_tokens}/             compatibiliteit met berichten in Anthropic-stijl
├── models/                              modellenlijst (`route.ts`, `catalog.ts`)
├── moderations/                         moderatie
├── music/                               muziek genereren
├── providers/[provider]/                bewerkingen per provider
├── quotas/{check}                       quotacontroles
├── registered-keys/                     beheer van geregistreerde sleutels
├── rerank/                              opnieuw rangschikken
├── responses/[...path]/                 OpenAI Responses API (catch-all)
├── search/                              zoeken op het web
├── videos/                              video's genereren
├── ws/                                  WebSocket-bridge
└── route.ts                             indexhandler

Elk routebestand volgt hetzelfde patroon:

Route → CORS-preflight → Zod-validatie van body → optionele authenticatie
      → afdwinging van API-sleutelbeleid → delegatie aan handler (open-sse)

v1beta/ is de Gemini-compatibiliteitslaag (een dunne wrapper die vertaalt naar dezelfde open-sse/handlers/-pipeline).

3.2 src/lib/ — Kernbibliotheken

Importeer gegevens, synchronisatie, OAuth, vaardigheden, geheugen enzovoort altijd via deze modules. De tabel groepeert de daadwerkelijke mappen en vermeldenswaardige bestanden op het hoogste niveau.

Module	Doel
a2a/	A2A-protocolserver: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 vaardigheden: kostenanalyse, statusrapport, providerdetectie, quotabeheer, slimme routering, mogelijkheden weergeven)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Interne API-hulpfuncties: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (wachtwoord opnieuw instellen/hashen)
batches/	OpenAI Batches API-service (service.ts)
catalog/	Synchronisatie van de OpenRouter-catalogus (openrouterCatalog.ts)
cloudAgent/	Cloudagentregister: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Hulpfuncties voor comboresolutie
compliance/	Audit + provideraudit: index.ts, providerAudit.ts
config/	Koppeling voor runtimeconfiguratie
db/	SQLite-domeinmodules (zie §3.2.1)
display/	UI-/weergavehulpfuncties die door API-responses worden gebruikt
embeddings/	Register voor embeddingservices
env/	Laden + inspecteren van omgevingsvariabelen
evals/	Eval-runtime
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Achtergrondtaken (autoUpdate.ts, …)
memory/	Persistent geheugen: 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/	OAuth-/importmodules voor providers (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/ en constants/oauth.ts
plugins/	Pluginlader (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Beheerde levenscyclus van modellen: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Providerhulpfuncties: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — instellingen voor circuitonderbreker, afkoelperiode en blokkering
runtime/	Detectie van runtimefunctionaliteit
search/	executeWebSearch.ts
services/	Framework voor ingebedde services: ServiceSupervisor.ts (generieke supervisor voor onderliggende processen met bewerkingsvergrendeling, ringbuffer en statuscontrole), bootstrap.ts (registratie op procesniveau en automatisch starten), registry.ts (koppeling van tool → supervisor), apiKey.ts (AES-256-GCM-sleutelopslag), modelSync.ts (periodieke modelsynchronisatie), ringBuffer.ts (circulaire logbuffer van 5 MB), healthCheck.ts (HTTP-statuscontrole), types.ts, embedWsProxy.ts (WebSocket-proxy), installers/{ninerouter,cliproxy}.ts. Zie docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Catalogus + generator voor agentvaardigheden: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → schrijft skills/{id}/SKILL.md), openapiParser.ts (extraheert REST-eindpunten uit de OpenAPI-specificatie), cliRegistryParser.ts (extraheert CLI-subcommando's uit bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Gebruikt door REST-routes (/api/agent-skills/*), MCP-tools (omniroute_agent_skills_*) en A2A-vaardigheid list-capabilities. Zie AGENT-SKILLS.md.
skills/	Vaardighedenframework: 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 (write-behind-buffer)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Hulpfuncties op systeemniveau
translator/	Koppeling voor de vertaler op het hoogste niveau (delegeert naar open-sse/translator/)
usage/	Gebruiksregistratie: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automatisch bijwerken + versiemanifest
ws/	WebSocket-bridge
zed-oauth/	OAuth-flow voor de Zed-editor

Bestanden op het hoogste niveau in src/lib/:

• Het oude barrelbestand localDb.ts is verwijderd — gebruikers importeren specifieke src/lib/db/*-modules rechtstreeks.
• 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/

Singleton SQLite-database (getDbInstance() in core.ts, WAL-journaling). Schrijf nooit ruwe SQL in routes of handlers — gebruik hiervoor deze modules.

Bron: diagrams/db-schema-overview.mmd

Domeinmodules (elke module beheert een of meer tabellen): 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/ bevat 168 geversioneerde .sql-bestanden (idempotent en transactioneel) en wordt tijdens het opstarten uitgevoerd door migrationRunner.ts.

Tabellen die via de migraties worden aangemaakt (123 in totaal):

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 virtuele FTS5-tabellen voor het doorzoeken van het geheugen).

3.3 src/domain/ — Domeinlaag

Zuivere bedrijfslogica, zonder I/O. Wordt geïmporteerd door routes en handlers.

Bestand	Doel
policyEngine.ts	Beleidsresolver op het hoogste niveau
fallbackPolicy.ts	Beslisboom voor fallbacks
costRules.ts	Regels voor kostenberekening
lockoutPolicy.ts	Beslissingen over modelblokkering
tagRouter.ts	Routering op basis van tags
comboResolver.ts	Combo-resolutie van verzoek → lijst met doelen
connectionModelRules.ts	Modelfilters per verbinding
modelAvailability.ts	Controle van modelbeschikbaarheid
degradation.ts	Overgangen naar gedegradeerde modus
providerExpiration.ts	Detectie van verlopen accounts/sleutels
quotaCache.ts	Gecachte quotabeslissingen
responses.ts, omnirouteResponseMeta.ts	Helpers voor responsstructuren
configAudit.ts	Audit van configuratiewijzigingen
assessment/	Modelbeoordeling (volgens RFC, deels geïmplementeerd)
types.ts	Gedeelde domeintypen

3.4 src/server/ — Alleen voor de server

Kan niet vanuit clientcomponenten worden geïmporteerd.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Classificeert routes als openbaar of voor beheer
│   ├── assertAuth.ts      Assertiehelper
│   ├── context.ts         Authz-context per verzoek
│   ├── headers.ts
│   ├── pipeline.ts        Authz-pipeline
│   ├── policies/          Concrete beleidsregels
│   └── types.ts
└── cors/origins.ts        Allowlist voor CORS-oorsprongen

3.5 src/shared/ — Veilig om te delen

Opgesplitst in gerichte submappen:

• constants/ — providers.ts (met Zod gevalideerde providercatalogus), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (blokkeerlijst), 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 Zod-schema's), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — openbare API-contracten die naar npm worden gepubliceerd.
• types/ — gedeelde TS-typen.
• 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 dashboardhooks/-componenten onder services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Werkruimte voor de streaming-engine

Afzonderlijke npm-werkruimte die als @omniroute/open-sse wordt gepubliceerd. Beheert de verwerking van aanvragen, executors, translators, services, de transformer en de MCP-server.

open-sse/
├── index.ts                Publieke exports
├── package.json            Werkruimtemanifest
├── tsconfig.json
├── types.d.ts
├── config/                 Providerregisters, headerprofielen, identiteit, …
├── handlers/               Aanvraaghandlers (chat, embeddings, audio, afbeeldingen, …)
├── executors/              108 providerspecifieke HTTP-executors
├── translator/             Formaatconversie (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions-streamtransformer
├── services/               Meer dan 80 servicemodules (combinaties, fallback, quota's, identiteit, …)
├── utils/                  Streaminghelpers, TLS-client, AWS SigV4, proxy-fetch, …
└── mcp-server/             MCP-server (3 transporttypen, 33 scopes, 110 tools)

4.1 open-sse/handlers/

Handler	Doel
chatCore.ts	Hoofdpijplijn voor chat (cache, snelheidslimiet, combinatieroutering, dispatch naar executor)
responsesHandler.ts	Toegangspunt voor de OpenAI Responses API
embeddings.ts	Embeddings
imageGeneration.ts	Afbeeldingen genereren
audioSpeech.ts	Tekst-naar-spraak
audioTranscription.ts	Spraak-naar-tekst
videoGeneration.ts	Video's genereren
musicGeneration.ts	Muziek genereren
rerank.ts	Opnieuw rangschikken
moderations.ts	Moderatie
search.ts	Zoeken op het web
sseParser.ts	Parser voor SSE-events
usageExtractor.ts	Aantallen tokens uit upstream-streams extraheren
responseSanitizer.ts	Providerspecifieke ruis verwijderen
responseTranslator.ts	Koppeling tussen providerrespons en de translator-laag

4.2 open-sse/executors/

108 provider-executors, die elk BaseExecutor (base.ts) uitbreiden:

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 (gedeelde identiteitshelper) en index.ts (register).

Opmerking: providers die hier niet worden vermeld, worden bediend door default.ts met behulp van de generieke OpenAI-compatibele executor. De volledige providercatalogus (355 providers) bevindt zich in src/shared/constants/providers.ts.

4.3 open-sse/translator/

Hub-and-spoke-vertaling (OpenAI is de hub).

• 9 aanvraagtranslators (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 responsetranslators (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 helpers (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, plus tests voor helpers.
• Afbeeldingshelpers (translator/image/sizeMapper.ts).
• Op het hoogste niveau: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — op TransformStream gebaseerde converter tussen de Responses API en Chat Completions (gebruikt door de catch-all van de responses/-route).

4.5 open-sse/services/

Hoogtepunten (volledige lijst onder open-sse/services/):

Aandachtspunt	Bestanden
Comboroutering	combo.ts (19 strategieën), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Auto Combo-engine	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
Veerkracht	accountFallback.ts (afkoelperiode + vergrendeling), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Quota's	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Caching	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Routeringslogica	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Modelafhandeling	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Compressie	compression/ — volledige bedrading van de compressie-engine
Token + sessie	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Niveau / manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / netwerk	ipFilter.ts, webSearchFallback.ts
Batches	batchProcessor.ts
Gebruik	usage.ts

4.6 open-sse/mcp-server/

• 110 unieke tools gekoppeld in server.ts (45 canonieke tools in schemas/tools.ts + geheugen-, vaardigheids-, GitHub-vaardigheids-, pool-, gamificatie-, plug-in-, Notion-, Obsidian-, lokale-corpus- en compressiemodules — unie geteld door countUniqueMcpTools).
• 3 transporten: stdio, HTTP Streamable, SSE.
• 33 scopes afgedwongen tijdens runtime — basislijst in src/shared/constants/mcpScopes.ts; de volledige set is de unie van de scopes die door elke toolmodule worden gedeclareerd.
• Audittabel: mcp_tool_audit (gevuld door audit.ts).
• Bestanden: 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 tests onder __tests__/.
• Zie MCP-SERVER.md voor de volledige toolcatalogus.

4.7 open-sse/config/

Providerregisters (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), modelregisters per indeling (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), identiteitshulpmiddelen (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), referentiehulpmiddelen (credentialLoader.ts, codexClient.ts) en cloud- adapters (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/

Streamingprimitieven en providerhelpers: 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/ — Desktopwrapper

electron/
├── main.js                  Electron-hoofdproces
├── preload.js               Preload-bridge (contextIsolation ingeschakeld)
├── types.d.ts
├── package.json             electron-builder-configuratie, versie 3.8.51
├── README.md
├── assets/                  Buildresources (pictogrammen, entitlements, …)
├── node_modules/            Afzonderlijke node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Buildoutput (niet gecommit)

Vijf npm-scripts in de hoofdmap van de workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Automatisch bijwerken verloopt via electron-updater, dat naar de GitHub-releasefeed verwijst.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Primair CLI-ingangspunt (Node ESM)
├── reset-password.mjs      Het beheerwachtwoord opnieuw instellen via de CLI
├── mcp-server.mjs          MCP-serverstarter (stdio)
├── nodeRuntimeSupport.mjs  Controle van de Node-versie
└── cli/
    ├── program.mjs         Opbouwfunctie voor het Commander-programma
    ├── runtime.mjs         withRuntime-helper (eerst server, database als terugvaloptie)
    ├── output.mjs          Uitvoerformatters (json/jsonl/table/csv)
    ├── i18n.mjs            t()-helper met locales
    ├── api.mjs             Helper voor API-fetches
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Registratie van opdrachten
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (één bestand per opdracht/groep)

In package.json → bin worden twee uitvoerbare bestanden beschikbaar gesteld:

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

---

7. tests/

Map	Type
tests/unit/	Unittests via de ingebouwde Node-testrunner (1821 bestanden, plus de submappen api/, auth/, authz/)
tests/integration/	Tests van interacties tussen modules en databasestatussen
tests/e2e/	Playwright-UI-tests
tests/e2e/protocol-clients.test.ts	End-to-endtests voor MCP/A2A-protocollen
tests/translator/	Vertalerspecifieke tests
tests/security/	Beveiligingsregressies
tests/load/	Belastings-/stresstests
tests/golden-set/	Referentie-uitvoer voor vertalerregressies
tests/helpers/, tests/fixtures/, tests/manual/	Ondersteuning

Veelgebruikte opdrachten:

Opdracht	Wat er wordt uitgevoerd
npm run test:unit	Alle tests/unit/*.test.ts via de Node-testrunner (gelijktijdigheid 10)
npm run test:vitest	Vitest-testsuite (MCP, autoCombo, cache)
npm run test:e2e	Playwright-UI-testsuite
npm run test:protocols:e2e	End-to-endtests voor MCP- en A2A-protocollen
npm run test:coverage	Dekkingsdrempel (≥60% regels/instructies/functies/vertakkingen)
node --import tsx/esm --test tests/unit/<file>.test.ts	Uitvoering van één bestand

---

8. scripts/

Georganiseerd in 6 submappen op basis van doel.

• 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. Aanvraagpipeline (samenvatting)

Bron: diagrams/request-pipeline.mmd

Clientaanvraag
  → /v1/chat/completions (route.ts)
     CORS-preflightcontrole
     Zod-validatie (chatCompletionsSchema in shared/validation/schemas.ts)
     Authenticatie (extractApiKey + isValidApiKey OF requireManagementAuth)
     Beleidsengine (src/server/authz/pipeline.ts)
     Beveiligingsmaatregelen (PII-maskering, promptinjectie, vision-bridge)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Cachecontrole (semantische cache + leescache)
     Frequentielimiet (rateLimitManager, accountSemaphore)
     Combinatieroutering (als het model naar een combinatie wordt herleid)
       comboResolver → lus per doel → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       upstream ophalen → opnieuw proberen/exponentiële wachttijd via accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE-stream OF JSON-respons
     Bij Responses API: TransformStream via open-sse/transformer/responsesTransformer.ts
  → Compliance-audit (src/lib/compliance/)
  → Respons naar client

Runtimestatus voor veerkracht (drie mechanismen)

Mechanisme	Bereik	Waar
Circuitbreaker van provider	Volledige provider	src/shared/utils/circuitBreaker.ts, opgeslagen in domain_circuit_breakers
Afkoelperiode van verbinding	Eén account/sleutel	markAccountUnavailable() in src/sse/services/auth.ts; gebruikt door accountFallback.checkFallbackError()
Modelblokkering	Provider + verbinding + model	open-sse/services/accountFallback.ts, opgeslagen in domain_lockout_state

Zie RESILIENCE_GUIDE.md en de betreffende sectie in CLAUDE.md.

---

10. Bijdragen

Een nieuwe provider toevoegen

1. Registreer deze in src/shared/constants/providers.ts (bij het laden gevalideerd met Zod).
2. Voeg indien aangepaste logica vereist is een executor toe in open-sse/executors/ (breid BaseExecutor uit).
3. Voeg een translator toe in open-sse/translator/ als de provider niet de OpenAI-indeling gebruikt.
4. Voeg bij gebruik van OAuth configuratie toe onder src/lib/oauth/providers/ en src/lib/oauth/services/.
5. Registreer modellen in open-sse/config/providerRegistry.ts (of in het indelingsspecifieke register onder open-sse/config/).
6. Schrijf tests onder tests/unit/.

Een nieuwe API-route toevoegen

1. Maak src/app/api/your-route/route.ts.
2. Volg het patroon: CORS → Zod-validatie van de body → authenticatie → delegatie aan de handler.
3. Voeg bij een nieuwe aanvraagstructuur het Zod-schema toe in src/shared/validation/schemas.ts.
4. Voeg bij een route die uitsluitend voor beheer is bedoeld het pad toe aan src/shared/constants/publicApiRoutes.ts (blokkeerlijst voor het openbare API-oppervlak).
5. Voeg tests toe onder tests/unit/.
6. Werk docs/reference/API_REFERENCE.md en docs/openapi.yaml bij.

Een nieuwe DB-module toevoegen

1. Maak src/lib/db/yourModule.ts en importeer getDbInstance() uit ./core.ts.
2. Exporteer CRUD-functies voor je domein.
3. Voeg bij nieuwe tabellen een migratie toe onder src/lib/db/migrations/, doorlopend genummerd, idempotent en transactioneel.
4. Importeurs gebruiken directe imports uit @/lib/db/yourModule (geen barrel — de oude re-exportlaag localDb.ts is verwijderd).
5. Voeg tests toe onder tests/unit/.

Een nieuwe MCP-tool toevoegen

1. Voeg de tooldefinitie toe onder open-sse/mcp-server/tools/ (of breid open-sse/mcp-server/schemas/tools.ts uit).
2. Wijs de juiste scope(s) toe in src/shared/constants/mcpScopes.ts.
3. Registreer de tool in open-sse/mcp-server/server.ts.
4. Voeg tests toe onder open-sse/mcp-server/__tests__/.
5. Werk MCP-SERVER.md bij.

Een nieuwe A2A-skill toevoegen

Zie A2A-SERVER.md § Een nieuwe skill toevoegen. Skills bevinden zich in src/lib/a2a/skills/ en worden geregistreerd via de A2A-taakbeheerder.

---

11. Conventies

• Codestijl: inspringing van 2 spaties, dubbele aanhalingstekens, regelbreedte van 100 tekens, puntkomma's, afsluitende komma's volgens es5 — afgedwongen door Prettier via lint-staged.
• Imports: extern → intern (@/, @omniroute/open-sse) → relatief.
• Naamgeving: bestanden camelCase of kebab-case, componenten PascalCase, constanten UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = overal error; no-explicit-any = warn in open-sse/ en tests/, elders error.
• TypeScript: strict: false (vanwege verouderde code). Geef voor grenzen tussen modules de voorkeur aan expliciete typen boven type-inferentie.
• Database: schrijf nooit onbewerkte SQL in routes of handlers — gebruik altijd modules uit src/lib/db/. Importeer nooit via een barrel — gebruik specifieke src/lib/db/*-modules rechtstreeks.
• Typen van DB-entiteiten (#3512): een functie die de rijstructuur van een DB-tabel schrijft of leest, moet een benoemde TS-interface accepteren/retourneren die de kolommen van die tabel 1-op-1 weerspiegelt, en geen any of een inline anoniem type op de aanroeplocatie. Plaats de interface naast de functie (bijv. export interface UsageEntry in src/lib/usage/usageHistory.ts boven saveRequestUsage), houd afzonderlijke velden optioneel/nullable wanneer verschillende schrijvers de rij stapsgewijs vullen, en geef de voorkeur aan unknown boven any voor een veld waarvan de structuur tussen aanroepers varieert (gedocumenteerd bij het veld; zo accepteert UsageEntry.tokens zowel onbewerkte gebruiksgegevens in providerspecifieke vorm als de genormaliseerde vorm). Zodra het aantal any-gevallen in een bestand op deze manier nul bereikt, voeg je het toe aan de allowlist van check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0), zodat dit niet kan terugvallen. Dit is een conventie voor een eerste deel — de bredere opschoning van „geen anonieme any” wordt iteratief in de rest van de codebase uitgevoerd.
• Fouten: gebruik try/catch met specifieke fouttypen en log met pino-context. Slik fouten in SSE-streams nooit stilzwijgend in; gebruik abort-signalen voor het opschonen.
• Beveiliging: gebruik nooit eval() / new Function() / impliciete eval. Valideer alle invoer met Zod. Versleutel inloggegevens in rusttoestand (AES-256-GCM). Houd de blokkeerlijst src/shared/constants/upstreamHeaders.ts afgestemd op de opschonings-/validatielaag.
• Commits: Conventional Commits — feat(scope): subject. Toegestane scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branches: voorvoegsels feat/, fix/, refactor/, docs/, test/, chore/. Commit nooit rechtstreeks naar main.
• Husky: pre-commit voert lint-staged + check:docs-sync + check:any-budget:t11 uit; pre-push voert check:any-budget:t11 + check:tracked-artifacts uit (snelle controles; exclusief test:unit).

---

12. Strikte regels (uit CLAUDE.md)

1. Commit nooit geheimen of inloggegevens.
2. Gebruik nooit barrel-imports — gebruik rechtstreeks specifieke src/lib/db/*-modules.
3. Gebruik nooit eval() / new Function() / impliciete eval.
4. Commit nooit rechtstreeks naar main.
5. Schrijf nooit ruwe SQL in routes — werk altijd via modules in src/lib/db/.
6. Negeer fouten in SSE-streams nooit stilzwijgend.
7. Valideer invoer altijd met Zod-schema's.
8. Voeg altijd tests toe wanneer je productiecode wijzigt.
9. De testdekking moet ≥ 60% blijven (instructies, regels, functies, vertakkingen).

---

13. Zie ook

• ARCHITECTURE.md — architectuur op hoofdlijnen en moduleverantwoordelijkheden.
• API_REFERENCE.md — referentie voor de openbare en beheer-API.
• FEATURES.md — functiematrix en hoogtepunten per versie.
• RESILIENCE_GUIDE.md — diepgaande uitleg over circuitbreaker, cooldown en lockout.
• AUTO-COMBO.md — scores en strategieën voor Auto Combo.
• MCP-SERVER.md — volledige catalogus van MCP-tools en transports.
• A2A-SERVER.md — vaardigheden en detectie van het A2A-protocol.
• COMPRESSION_GUIDE.md — RTK- en Caveman-compressie.
• CLI-TOOLS.md — CLI-integraties.
• ELECTRON_GUIDE.md (indien aanwezig), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — implementatiedoelen.
• TROUBLESHOOTING.md — veelvoorkomende operationele problemen.
• CONTRIBUTING.md — workflow voor bijdragers.
• CLAUDE.md — repositoryregels voor Claude Code (de gezaghebbende bron voor veel van de bovenstaande conventies).
• AGENTS.md — diepgaandere architectuurreferentie die door agents wordt gebruikt.