pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-21 06:12:17 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
db5ae3c33d0fe21b93bc4e353e8a9e94ee2d2ada
OmniRoute/docs/i18n/nl/docs/architecture/CODEBASE_DOCUMENTATION.md
Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940) 
1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732
2026-09-17 02:55:31 -03:00

853 lines
81 KiB
Markdown
Raw Blame History

# OmniRoute Codebase Documentation (Nederlands)
🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)
---
> **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](./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](../frameworks/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.
![Overzicht van het databaseschema (geselecteerde kerntabellen)](../diagrams/exported/db-schema-overview.svg)
> Bron: [diagrams/db-schema-overview.mmd](../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](../frameworks/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)
![Aanvraagpipeline (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)
> Bron: [diagrams/request-pipeline.mmd](../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](./RESILIENCE_GUIDE.md) en de betreffende sectie in
[CLAUDE.md](../../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](../frameworks/MCP-SERVER.md) bij.
### Een nieuwe A2A-skill toevoegen
Zie [A2A-SERVER.md § Een nieuwe skill toevoegen](../frameworks/A2A-SERVER.md). 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](./ARCHITECTURE.md) — architectuur op hoofdlijnen en
moduleverantwoordelijkheden.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — referentie voor de openbare en beheer-API.
- [FEATURES.md](../guides/FEATURES.md) — functiematrix en hoogtepunten per versie.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — diepgaande uitleg over circuitbreaker, cooldown
en lockout.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — scores en strategieën voor Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — volledige catalogus van MCP-tools en transports.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — vaardigheden en detectie van het A2A-protocol.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK- en Caveman-compressie.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI-integraties.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (indien aanwezig), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — implementatiedoelen.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — veelvoorkomende operationele problemen.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — workflow voor bijdragers.
- [CLAUDE.md](../../CLAUDE.md) — repositoryregels voor Claude Code (de gezaghebbende bron
voor veel van de bovenstaande conventies).
- [AGENTS.md](../../AGENTS.md) — diepgaandere architectuurreferentie die door agents wordt gebruikt.
Reference in New Issue View Git Blame Copy Permalink