# OmniRoute Codebase Documentation (Deutsch)

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [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)

---

> **Version:** v3.8.51
> **Zuletzt aktualisiert:** 2026-06-28
> **Zielgruppe:** Entwickler, die zu OmniRoute beitragen oder darauf aufbauende Integrationen erstellen.
>
> Übergeordnete Architekturdiagramme und die Begründung hinter jedem Subsystem finden Sie in
> [ARCHITECTURE.md](./ARCHITECTURE.md). Ausführliche Erläuterungen zu einzelnen Subsystemen
> (Auto Combo, MCP-Server, A2A-Server, Skills, Memory, Cloud Agents, Resilience,
> Compression usw.) finden Sie in den jeweils zugehörigen Dateien in diesem `docs/`-Verzeichnis.

Diese Datei beschreibt, **was heute im Repository vorhanden ist**, damit sich neue Entwickler
in der Verzeichnisstruktur zurechtfinden, die Laufzeitschichten verstehen und wissen, wo Code
hinzugefügt werden muss, ohne neue Module zu erfinden.

---

## 1. Technologie-Stack

| Bereich       | Auswahl                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Web-Framework | **Next.js 16** (App Router, eigenständige Ausgabe, keine globale Middleware)                                              |
| Sprache       | **TypeScript 6.0+** — Ziel `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                       |
| Laufzeit      | **Node.js** `>=22.22.2 <23` oder `>=24.0.0 <27` (durch `engines` + `SUPPORTED_NODE_RANGE` erzwungen)                      |
| Datenbank     | **SQLite** über `better-sqlite3` (Singleton, WAL-Journaling)                                                              |
| Desktop       | **Electron 41** + `electron-builder` 26.10 (separater Workspace unter `electron/`)                                        |
| Tests         | **Nativer Node-Test-Runner** (Unit/Integration), **Vitest** (MCP, autoCombo, Cache), **Playwright** (e2e + protocols-e2e) |
| Build         | Eigenständiges Next.js-Build über `scripts/build/build-next-isolated.mjs`                                                 |
| Lint/Format   | ESLint-Flat-Config + Prettier (`lint-staged` über Husky-Pre-Commit)                                                       |
| Modulsystem   | Durchgehend ESM (`"type": "module"`)                                                                                      |
| Workspaces    | npm-Workspace — `open-sse` ist der einzige Sub-Workspace                                                                  |

Pfadaliase (`tsconfig.json`):

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

Standardmäßiger HTTP-Port: **`20128`** (API und Dashboard nutzen denselben Prozess). Das
Datenverzeichnis wird durch die Umgebungsvariable `DATA_DIR` festgelegt und verwendet standardmäßig
`~/.omniroute/`.

---

## 2. Repository-Struktur

```
OmniRoute/
├── src/                  Next.js-Anwendung (App Router, Bibliotheken, Domäne, Server, gemeinsam genutzter Code)
├── open-sse/             Workspace der Streaming-Engine (@omniroute/open-sse)
├── electron/             Desktop-Wrapper (Electron-41-Hauptprozess + Preload)
├── bin/                  CLI-Einstiegspunkte (omniroute, reset-password)
├── tests/                Unit-, Integrations-, e2e-, protocols-e2e-, Übersetzer- und Sicherheitstests sowie Fixtures
├── scripts/              Hilfsskripte für Build, Synchronisierung, Prüfung, Migration und Laufzeit
├── docs/                 Öffentliche Dokumentation (dieses Verzeichnis)
├── public/               Statische Assets, PWA-Manifest, Service Worker
├── config/               Beispiele für die Laufzeitkonfiguration
├── images/               Marketing-/Screenshot-Assets
├── _ideia/, _references/, _mono_repo/, _tasks/   Interne Entwürfe/Planung (nicht ausgeliefert)
├── CLAUDE.md             Repository-Regeln für Claude Code
├── AGENTS.md             Ausführlichere Architekturreferenz für Agenten
├── package.json          v3.8.51, Workspace-Stammverzeichnis
└── tsconfig.json         Pfadaliase + zentrale Compiler-Optionen
```

---

## 3. `src/` — Next.js-Anwendung

```
src/
├── app/                  App-Router-Seiten + API-Routen
├── lib/                  Kernbibliotheken (DB, Authentifizierung, OAuth, Skills, Speicher, …)
├── domain/               Reine Domänenschicht (Richtlinien, Fallback, Kosten, Sperrung, …)
├── server/               Ausschließlich serverseitige Module (Autorisierung, CORS, Authentifizierung)
├── shared/               Typen, Konstanten, Validierung, Verträge, Hilfsfunktionen (grenzübergreifend sicher)
├── mitm/                 Man-in-the-Middle-Proxy-Hilfsfunktionen für die CLI-Integration
├── models/               Lokale Modellmetadaten/Aliaszuordnung
├── sse/                  Ältere SSE-Handler, die sich weiterhin unter src/ befinden (nicht open-sse/)
├── store/                Clientseitige Zustandsspeicher
├── middleware/           Middleware-Hilfsfunktionen auf Routenebene (keine globale Next.js-Middleware)
├── scripts/              Im Projektbaum enthaltene, durch Anwendungscode importierbare Skripte
├── types/                Globale und gemeinsam genutzte TS-Typen
├── i18n/                 Lokalisierungspakete
├── instrumentation.ts    Next.js-Instrumentierungs-Hook
├── instrumentation-node.ts
└── proxy.ts              Übergeordnete Proxy-Bootstrap-Hilfsfunktion
```

### 3.1 `src/app/` — App Router

Der App Router stellt sowohl die Dashboard-Benutzeroberfläche als auch die öffentliche beziehungsweise administrative HTTP-API bereit.
Es gibt **keine globale Middleware** — die Abfanglogik wird pro Route implementiert.

Übergeordnete Segmente unter `src/app/`:

| Pfad                                                                          | Zweck                                                        |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `api/`                                                                        | Alle HTTP-API-Routen (siehe Aufschlüsselung unten)           |
| `a2a/`                                                                        | A2A-JSON-RPC-2.0-Endpunkt (`POST /a2a`)                      |
| `.well-known/agent.json/`                                                     | A2A-Agent-Card-Erkennungsdokument                            |
| `(dashboard)/`                                                                | Dashboard-Benutzeroberfläche (Routengruppe, kein URL-Präfix) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | Authentifizierungsabläufe                                    |
| `landing/`                                                                    | Marketing-/Landingpage                                       |
| `docs/`                                                                       | Eingebettete API-Dokumentationsansicht                       |
| `status/`, `maintenance/`, `offline/`                                         | Betriebsseiten                                               |
| `privacy/`, `terms/`                                                          | Rechtliche Seiten                                            |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | Statische Fehlerseiten                                       |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Framework-Grenzen für Fehler und Ladevorgänge                |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | Grundgerüst                                                  |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — Benutzeroberflächenseiten

`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` sowie die Stammdateien `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — Übergeordnete API-Gruppen

```
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/   Verwaltung eingebetteter Dienste (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-kompatible öffentliche API
├── v1beta/     Gemini-ähnliche Kompatibilität
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — Verwaltung eingebetteter Dienste

Routen zum Installieren, Starten, Stoppen und Überwachen von 9Router und CLIProxyAPI.
Alle Pfade sind als **LOCAL_ONLY** klassifiziert (nur Loopback, feste Regel Nr. 17), da sie
`npm install` aufrufen und untergeordnete Prozesse starten können.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             Hilfsfunktion getOrInitSupervisor()
│   ├── install/route.ts    POST — npm-Installation über execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — neuere Version mit npm installieren
│   ├── rotate-key/route.ts POST — neuen API-Schlüssel generieren + neu starten
│   ├── status/route.ts     GET  — Live- und DB-Status + Versionsmetadaten
│   └── auto-start/route.ts POST — auto_start-Flag umschalten
├── cliproxy/
│   ├── _lib.ts             Hilfsfunktion getOrInitSupervisor()
│   ├── install/route.ts    POST — npm-Installation
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — neuere Version mit npm installieren
│   ├── status/route.ts     GET  — Live- und DB-Status + Versionsmetadaten
│   └── auto-start/route.ts POST — auto_start-Flag umschalten
└── [name]/
    └── logs/route.ts       GET  — SSE-Log-Tail (von allen Diensten gemeinsam genutzt)
```

Zugehörige Dashboard-Benutzeroberfläche:
`src/app/(dashboard)/dashboard/providers/services/` — Seite mit zwei Tabs (CLIProxyAPI + 9Router).
Reverse-Proxy für die eingebettete Benutzeroberfläche von 9Router:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

Ausführliche Erläuterung: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — OpenAI-kompatible öffentliche API

```
v1/
├── accounts/[id]/                       Kontosuche
├── agents/tasks/[id]/, agents/tasks/    A2A-orientierte Aufgabenendpunkte
├── api/                                 interne API-Hilfsfunktionen, die unter v1/api verfügbar sind
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (der Hauptendpunkt)
├── completions/                         ältere Textvervollständigungen
├── embeddings/                          Einbettungen
├── files/[id]/, files/                  Files API
├── _helpers/                            gemeinsam genutzte Routen-Hilfsfunktionen (keine öffentliche URL)
├── images/{edits, generations}/         Bildgenerierung + -bearbeitung
├── issues/                              Hilfsendpunkte zur Triage
├── management/{proxies}/                Routen mit Verwaltungsbereich innerhalb von v1
├── messages/{count_tokens}/             Anthropic-kompatible Nachrichten
├── models/                              Modellauflistung (`route.ts`, `catalog.ts`)
├── moderations/                         Moderation
├── music/                               Musikgenerierung
├── providers/[provider]/                anbieterspezifische Operationen
├── quotas/{check}                       Kontingentprüfungen
├── registered-keys/                     Verwaltung registrierter Schlüssel
├── rerank/                              Neusortierung
├── responses/[...path]/                 OpenAI Responses API (Catch-all)
├── search/                              Websuche
├── videos/                              Videogenerierung
├── ws/                                  WebSocket-Bridge
└── route.ts                             Index-Handler
```

Jede Routendatei folgt demselben Muster:

```
Route → CORS-Preflight → Zod-Validierung des Bodys → optionale Authentifizierung
      → Durchsetzung der API-Schlüsselrichtlinie → Delegierung an Handler (open-sse)
```

`v1beta/` ist die Gemini-kompatible Oberfläche (ein dünner Wrapper, der in
dieselbe `open-sse/handlers/`-Pipeline übersetzt).

### 3.2 `src/lib/` — Kernbibliotheken

Daten, Synchronisierung, OAuth, Skills, Speicher usw. immer über diese Module importieren. Die
Tabelle gruppiert die tatsächlichen Verzeichnisse und erwähnenswerte Dateien auf oberster Ebene.

| Modul             | Zweck                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | A2A-Protokollserver: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 Skills: Kostenanalyse, Zustandsbericht, Anbietererkennung, Kontingentverwaltung, intelligentes Routing, list-capabilities)                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `acp/`            | Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `api/`            | Interne API-Hilfsfunktionen: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `auth/`           | `managementPassword.ts` (Zurücksetzen/Hashing von Passwörtern)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `batches/`        | Dienst für die OpenAI Batches API (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `catalog/`        | OpenRouter-Katalogsynchronisierung (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `cloudAgent/`     | Cloud-Agent-Registry: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `combos/`         | Hilfsfunktionen zur Combo-Auflösung                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `compliance/`     | Audit + Anbieteraudit: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `config/`         | Bindeglied für die Laufzeitkonfiguration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `db/`             | SQLite-Domänenmodule (siehe §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `display/`        | Von API-Antworten verwendete UI-/Anzeigehilfsfunktionen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `embeddings/`     | Registry für Embedding-Dienste                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `env/`            | Laden + Introspektion der Umgebung                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `evals/`          | Eval-Laufzeit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `jobs/`           | Hintergrundjobs (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `memory/`         | Persistenter Speicher: `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-/Import-Anbietermodule (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/` und `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                                             |
| `plugins/`        | Plugin-Loader (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `providerModels/` | Lebenszyklusverwaltung verwalteter Modelle: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `providers/`      | Anbieterhilfsfunktionen: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `resilience/`     | `settings.ts` — Einstellungen für Leistungsschalter, Abklingzeit und Sperrung                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `runtime/`        | Erkennung von Laufzeitfunktionen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `services/`       | Framework für eingebettete Dienste: `ServiceSupervisor.ts` (generischer Supervisor für untergeordnete Prozesse mit Operationssperre, Ringpuffer und Zustandsprüfung), `bootstrap.ts` (Registrierung auf Prozessebene und automatischer Start), `registry.ts` (Zuordnung von Tool → Supervisor), `apiKey.ts` (AES-256-GCM-Schlüsselspeicher), `modelSync.ts` (periodische Modellsynchronisierung), `ringBuffer.ts` (zirkulärer 5-MB-Protokollpuffer), `healthCheck.ts` (HTTP-Zustandsprüfung), `types.ts`, `embedWsProxy.ts` (WebSocket-Proxy), `installers/{ninerouter,cliproxy}.ts`. Siehe `docs/frameworks/EMBEDDED-SERVICES.md`                                                                        |
| `agentSkills/`    | Agent-Skills-Katalog + Generator: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → schreibt `skills/{id}/SKILL.md`), `openapiParser.ts` (extrahiert REST-Endpunkte aus der OpenAPI-Spezifikation), `cliRegistryParser.ts` (extrahiert CLI-Unterbefehle aus bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Verwendet von REST-Routen (`/api/agent-skills/*`), MCP-Tools (`omniroute_agent_skills_*`) und dem A2A-Skill `list-capabilities`. Siehe [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | Skill-Framework: `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-Puffer)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sync/`           | `bundle.ts`, `tokens.ts` (Cloud-Synchronisierung)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `system/`         | Hilfsfunktionen auf Systemebene                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `translator/`     | Übergeordnetes Bindeglied für Übersetzer (delegiert an `open-sse/translator/`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `usage/`          | Nutzungsabrechnung: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `versionManager/` | Automatische Aktualisierung + Versionsmanifest                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `ws/`             | WebSocket-Bridge                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `zed-oauth/`      | OAuth-Ablauf für den Zed-Editor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

Dateien auf oberster Ebene in `src/lib/`:

- Das alte Barrel `localDb.ts` wurde entfernt — Verbraucher importieren spezifische `src/lib/db/*`-Module direkt.
- `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-Datenbank (`getDbInstance()` in `core.ts`, WAL-Journaling).
**Niemals rohes SQL in Routen oder Handlern schreiben** — stattdessen diese Module verwenden.

![Übersicht des Datenbankschemas (ausgewählte Kerntabellen)](../diagrams/exported/db-schema-overview.svg)

> Quelle: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

Domänenmodule (jedes ist für eine oder mehrere Tabellen zuständig): `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/` enthält 168 versionierte `.sql`-Dateien (idempotent, transaktional) und wird
beim Start von `migrationRunner.ts` ausgeführt.

Über die Migrationen hinweg erstellte Tabellen (insgesamt 123):

`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` (zuzüglich virtueller FTS5-Tabellen für die Speichersuche).

### 3.3 `src/domain/` — Domänenschicht

Reine Geschäftslogik ohne I/O. Wird von Routen und Handlern importiert.

| Datei                                      | Zweck                                            |
| ------------------------------------------ | ------------------------------------------------ |
| `policyEngine.ts`                          | Übergeordnete Richtlinienauflösung               |
| `fallbackPolicy.ts`                        | Entscheidungsbaum für Fallbacks                  |
| `costRules.ts`                             | Regeln zur Kostenberechnung                      |
| `lockoutPolicy.ts`                         | Entscheidungen zur Modellsperrung                |
| `tagRouter.ts`                             | Tag-basiertes Routing                            |
| `comboResolver.ts`                         | Combo-Auflösung von Anfrage → Zielliste          |
| `connectionModelRules.ts`                  | Modellspezifische Filter pro Verbindung          |
| `modelAvailability.ts`                     | Prüfung der Modellverfügbarkeit                  |
| `degradation.ts`                           | Übergänge in den eingeschränkten Betriebsmodus   |
| `providerExpiration.ts`                    | Erkennung abgelaufener Konten/Schlüssel          |
| `quotaCache.ts`                            | Zwischengespeicherte Kontingententscheidungen    |
| `responses.ts`, `omnirouteResponseMeta.ts` | Hilfsfunktionen für Antwortstrukturen            |
| `configAudit.ts`                           | Prüfung von Konfigurationsänderungen             |
| `assessment/`                              | Modellbewertung (gemäß RFC, teilweise umgesetzt) |
| `types.ts`                                 | Gemeinsam genutzte Domänentypen                  |

### 3.4 `src/server/` — Nur serverseitig

Darf nicht aus Client-Komponenten importiert werden.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Klassifiziert Routen als öffentlich oder administrativ
│   ├── assertAuth.ts      Hilfsfunktion für Assertions
│   ├── context.ts         Authz-Kontext pro Anfrage
│   ├── headers.ts
│   ├── pipeline.ts        Authz-Pipeline
│   ├── policies/          Konkrete Richtlinien
│   └── types.ts
└── cors/origins.ts        Positivliste zulässiger CORS-Ursprünge
```

### 3.5 `src/shared/` — Sicher gemeinsam nutzbar

In zweckgebundene Unterverzeichnisse aufgeteilt:

- `constants/` — `providers.ts` (Zod-validierter Anbieterkatalog), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (Sperrliste), `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-Schemas), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — öffentliche API-Verträge, die auf npm veröffentlicht werden.
- `types/` — gemeinsam genutzte 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` sowie Dashboard-Hooks/-Komponenten unter `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/`.

---

## 4. `open-sse/` — Arbeitsbereich der Streaming-Engine

Separater npm-Arbeitsbereich, der als `@omniroute/open-sse` veröffentlicht wird. Verantwortlich für Anfrageverarbeitung, Executors, Übersetzer, Dienste, Transformer und den MCP-Server.

```
open-sse/
├── index.ts                Öffentliche Exporte
├── package.json            Arbeitsbereichsmanifest
├── tsconfig.json
├── types.d.ts
├── config/                 Provider-Registrierungen, Header-Profile, Identität, …
├── handlers/               Anfrage-Handler (Chat, Embeddings, Audio, Bilder, …)
├── executors/              150 Provider-Executor-Module (Executor-Klassen + Provider-spezifische Hilfsfunktionen)
├── translator/             Formatkonvertierung (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Stream-Transformer für Responses API ↔ Chat Completions
├── services/               Über 80 Dienstmodule (Kombinationen, Fallback, Kontingente, Identität, …)
├── utils/                  Streaming-Hilfsfunktionen, TLS-Client, AWS SigV4, Proxy-Abruf, …
└── mcp-server/             MCP-Server (3 Transportarten, 33 Geltungsbereiche, 110 Werkzeuge)
```

### 4.1 `open-sse/handlers/`

| Handler                 | Zweck                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `chatCore.ts`           | Zentrale Chat-Pipeline (Cache, Ratenbegrenzung, Kombinationsrouting, Executor-Dispatch) |
| `responsesHandler.ts`   | Einstiegspunkt der OpenAI Responses API                                                 |
| `embeddings.ts`         | Embeddings                                                                              |
| `imageGeneration.ts`    | Bilderzeugung                                                                           |
| `audioSpeech.ts`        | Text-zu-Sprache                                                                         |
| `audioTranscription.ts` | Sprache-zu-Text                                                                         |
| `videoGeneration.ts`    | Videoerzeugung                                                                          |
| `musicGeneration.ts`    | Musikerzeugung                                                                          |
| `rerank.ts`             | Neusortierung                                                                           |
| `moderations.ts`        | Moderation                                                                              |
| `search.ts`             | Websuche                                                                                |
| `sseParser.ts`          | SSE-Ereignisparser                                                                      |
| `usageExtractor.ts`     | Extrahiert Token-Anzahlen aus Upstream-Streams                                          |
| `responseSanitizer.ts`  | Entfernt Provider-spezifisches Rauschen                                                 |
| `responseTranslator.ts` | Bindeglied zwischen Provider-Antwort und Übersetzungsschicht                            |

### 4.2 `open-sse/executors/`

150 Executor-Module auf oberster Ebene (`*.ts` ohne `base.ts`, `index.ts` und Tests — diese Anzahl wird von
`npm run check:docs-counts` ermittelt). Jede Executor-Klasse erweitert `BaseExecutor` (`base.ts`),
entweder direkt oder über `DefaultExecutor` beziehungsweise einen anderen Executor; bei den übrigen Modulen handelt es sich um Provider-spezifische
Hilfsfunktionen (Werkzeugschemata, Fetch-/TTS-Adapter, Handler für Besonderheiten). Zu den Executors gehören:

`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` sowie `claudeIdentity.ts`
(gemeinsame Hilfsfunktion für Identitäten) und `index.ts` (Registrierung).

> Hinweis: Hier nicht aufgeführte Provider werden von `default.ts` mithilfe des generischen
> OpenAI-kompatiblen Executors bedient. Der vollständige Provider-Katalog (372 Provider) befindet sich in
> `src/shared/constants/providers.ts`.

### 4.3 `open-sse/translator/`

Hub-and-Spoke-Übersetzung (OpenAI ist der Hub).

- **9 Anfrageübersetzer** (`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 Antwortübersetzer** (`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 Hilfsfunktionen** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper` sowie
  Tests für Hilfsfunktionen.
- **Bild-Hilfsfunktionen** (`translator/image/sizeMapper.ts`).
- Oberste Ebene: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

### 4.4 `open-sse/transformer/`

- `responsesTransformer.ts` — Auf `TransformStream` basierender Konverter für Responses API ↔ Chat
  Completions (wird vom Catch-all der Route `responses/` verwendet).

### 4.5 `open-sse/services/`

Highlights (vollständige Liste unter `open-sse/services/`):

| Bereich             | Dateien                                                                                                                                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo-Routing       | `combo.ts` (19 Strategien), `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`             |
| Resilienz           | `accountFallback.ts` (Abklingzeit + Sperrung), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                     |
| Kontingente         | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| Caching             | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Routing-Intelligenz | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| Modellverarbeitung  | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| Komprimierung       | `compression/` — vollständige Verdrahtung der Komprimierungs-Engine                                                                                                                                                                                      |
| Token + Sitzung     | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| Stufe / Manifest    | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / Netzwerk       | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| Batches             | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Nutzung             | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **110 eindeutige Tools**, verdrahtet in `server.ts` (45 kanonische in `schemas/tools.ts` +
  Module für Speicher, Skills, GitHub-Skills, Pool, Gamification, Plugins, Notion, Obsidian,
  lokalen Korpus und Komprimierung — die Vereinigungsmenge wird von `countUniqueMcpTools` gezählt).
- **3 Transporte**: stdio, HTTP Streamable, SSE.
- **33 Geltungsbereiche**, die zur Laufzeit durchgesetzt werden — die Basisliste befindet sich in `src/shared/constants/mcpScopes.ts`; die vollständige Menge ist die Vereinigungsmenge der von jedem Tool-Modul deklarierten Geltungsbereiche.
- Audit-Tabelle: `mcp_tool_audit` (befüllt durch `audit.ts`).
- Dateien: `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`
  sowie Tests unter `__tests__/`.
- Den vollständigen Tool-Katalog finden Sie unter [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### 4.7 `open-sse/config/`

Provider-Registrys (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), formatspezifische Modell-Registrys (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
Identitäts-Hilfsfunktionen (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
Anmeldedaten-Hilfsfunktionen (`credentialLoader.ts`, `codexClient.ts`) und Cloud-
Adapter (`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/`

Streaming-Grundelemente und Provider-Hilfsfunktionen: `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/` — Desktop-Wrapper

```
electron/
├── main.js                  Electron-Hauptprozess
├── preload.js               Preload-Bridge (contextIsolation aktiviert)
├── types.d.ts
├── package.json             electron-builder-Konfiguration, Version 3.8.51
├── README.md
├── assets/                  Build-Ressourcen (Symbole, Berechtigungen, …)
├── node_modules/            Dedizierte node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Build-Ausgabe (nicht committet)
```

Fünf npm-Skripte im Workspace-Stammverzeichnis: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. Automatische Updates erfolgen über
`electron-updater`, das auf den GitHub-Release-Feed verweist.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           Haupt-Einstiegspunkt der CLI (Node ESM)
├── reset-password.mjs      Verwaltungskennwort über die CLI zurücksetzen
├── mcp-server.mjs          MCP-Server-Starter (stdio)
├── nodeRuntimeSupport.mjs  Prüfung der Node-Version
└── cli/
    ├── program.mjs         Builder für das Commander-Programm
    ├── runtime.mjs         withRuntime-Hilfsfunktion (zuerst Server, DB als Fallback)
    ├── output.mjs          Ausgabeformatierer (json/jsonl/table/csv)
    ├── i18n.mjs            t()-Hilfsfunktion mit Locales
    ├── api.mjs             Hilfsfunktion für API-Abrufe
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Befehlsregistrierung
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (eine Datei pro Befehl/Gruppe)
```

In `package.json` → `bin` werden zwei Binärdateien bereitgestellt:

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

---

## 7. `tests/`

| Verzeichnis                                          | Typ                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | Unit-Tests über den nativen Node-Test-Runner (1821 Dateien plus die Unterverzeichnisse `api/`, `auth/`, `authz/`) |
| `tests/integration/`                                 | Modulübergreifende Tests und Tests des DB-Zustands                                                                |
| `tests/e2e/`                                         | Playwright-UI-Tests                                                                                               |
| `tests/e2e/protocol-clients.test.ts`                 | MCP/A2A-Protokoll-E2E                                                                                             |
| `tests/translator/`                                  | Übersetzerspezifische Tests                                                                                       |
| `tests/security/`                                    | Sicherheitstests zur Vermeidung von Regressionen                                                                  |
| `tests/load/`                                        | Last-/Stresstests                                                                                                 |
| `tests/golden-set/`                                  | Referenzausgaben für Übersetzerregressionen                                                                       |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Hilfsressourcen                                                                                                   |

Häufig verwendete Befehle:

| Befehl                                                   | Ausführung                                                              |
| -------------------------------------------------------- | ----------------------------------------------------------------------- |
| `npm run test:unit`                                      | Alle `tests/unit/*.test.ts` über den Node-Test-Runner (Parallelität 10) |
| `npm run test:vitest`                                    | Vitest-Suite (MCP, autoCombo, Cache)                                    |
| `npm run test:e2e`                                       | Playwright-UI-Suite                                                     |
| `npm run test:protocols:e2e`                             | MCP- und A2A-Protokoll-E2E                                              |
| `npm run test:coverage`                                  | Abdeckungsgrenzwert (≥60 % Zeilen/Anweisungen/Funktionen/Verzweigungen) |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | Ausführung einer einzelnen Datei                                        |

---

## 8. `scripts/`

Nach Zweck in 6 Unterordner gegliedert.

- **`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. Anfrage-Pipeline (Zusammenfassung)

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

> Quelle: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
Client-Anfrage
  → /v1/chat/completions (route.ts)
     CORS-Preflight-Prüfung
     Zod-Validierung (chatCompletionsSchema in shared/validation/schemas.ts)
     Authentifizierung (extractApiKey + isValidApiKey ODER requireManagementAuth)
     Richtlinien-Engine (src/server/authz/pipeline.ts)
     Schutzmaßnahmen (PII-Maskierung, Prompt-Injection, Vision-Bridge)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Cache-Prüfung (semantischer Cache + Lese-Cache)
     Ratenbegrenzung (rateLimitManager, accountSemaphore)
     Kombinations-Routing (wenn das Modell in eine Kombination aufgelöst wird)
       comboResolver → Schleife pro Ziel → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       Upstream abrufen → Wiederholung/Backoff über accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE-Stream ODER JSON-Antwort
     Bei Responses API: TransformStream über open-sse/transformer/responsesTransformer.ts
  → Compliance-Audit (src/lib/compliance/)
  → Antwort an den Client
```

### Laufzeitstatus der Resilienzmechanismen (drei Mechanismen)

| Mechanismus              | Geltungsbereich                | Ort                                                                                                            |
| ------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Provider-Circuit-Breaker | Gesamter Provider              | `src/shared/utils/circuitBreaker.ts`, persistiert in `domain_circuit_breakers`                                 |
| Verbindungs-Cooldown     | Ein Konto/Schlüssel            | `markAccountUnavailable()` in `src/sse/services/auth.ts`; verwendet von `accountFallback.checkFallbackError()` |
| Modellsperre             | Provider + Verbindung + Modell | `open-sse/services/accountFallback.ts`, persistiert in `domain_lockout_state`                                  |

Siehe [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) und den entsprechenden Abschnitt in
[CLAUDE.md](../../CLAUDE.md).

---

## 10. Mitwirken

### Einen neuen Provider hinzufügen

1. In `src/shared/constants/providers.ts` registrieren (beim Laden mit Zod validiert).
2. Falls benutzerdefinierte Logik erforderlich ist, einen Executor in `open-sse/executors/` hinzufügen
   (`BaseExecutor` erweitern).
3. Falls das OpenAI-Format nicht unterstützt wird, einen Übersetzer in `open-sse/translator/` hinzufügen.
4. Bei OAuth-basierten Providern eine Konfiguration unter `src/lib/oauth/providers/` und
   `src/lib/oauth/services/` hinzufügen.
5. Modelle in `open-sse/config/providerRegistry.ts` registrieren (oder in der formatspezifischen
   Registry unter `open-sse/config/`).
6. Tests unter `tests/unit/` erstellen.

### Eine neue API-Route hinzufügen

1. `src/app/api/your-route/route.ts` erstellen.
2. Dem Muster folgen: CORS → Zod-Body-Validierung → Authentifizierung → Delegierung an den Handler.
3. Bei einer neuen Anfragestruktur das Zod-Schema in `src/shared/validation/schemas.ts` hinzufügen.
4. Falls nur für die Verwaltung vorgesehen, den Pfad zu `src/shared/constants/publicApiRoutes.ts`
   hinzufügen (Sperrliste für die öffentliche API-Oberfläche).
5. Tests unter `tests/unit/` hinzufügen.
6. `docs/reference/API_REFERENCE.md` und `docs/openapi.yaml` aktualisieren.

### Ein neues DB-Modul hinzufügen

1. `src/lib/db/yourModule.ts` erstellen und `getDbInstance()` aus `./core.ts` importieren.
2. CRUD-Funktionen für die betreffende Domäne exportieren.
3. Bei neuen Tabellen eine Migration unter `src/lib/db/migrations/` hinzufügen, fortlaufend
   nummeriert, idempotent und transaktional.
4. Importierende Module verwenden direkte Importe aus `@/lib/db/yourModule` (kein Barrel — die alte Reexport-Schicht `localDb.ts` wurde entfernt).
5. Tests unter `tests/unit/` hinzufügen.

### Ein neues MCP-Tool hinzufügen

1. Die Tool-Definition unter `open-sse/mcp-server/tools/` hinzufügen (oder
   `open-sse/mcp-server/schemas/tools.ts` erweitern).
2. Die entsprechenden Berechtigungsbereiche in `src/shared/constants/mcpScopes.ts` zuweisen.
3. Das Tool in `open-sse/mcp-server/server.ts` registrieren.
4. Tests unter `open-sse/mcp-server/__tests__/` hinzufügen.
5. [MCP-SERVER.md](../frameworks/MCP-SERVER.md) aktualisieren.

### Einen neuen A2A-Skill hinzufügen

Siehe [A2A-SERVER.md § Hinzufügen eines neuen Skills](../frameworks/A2A-SERVER.md). Skills befinden sich in
`src/lib/a2a/skills/` und werden über den A2A-Task-Manager registriert.

---

## 11. Konventionen

- **Codestil**: Einrückung mit 2 Leerzeichen, doppelte Anführungszeichen, Zeilenbreite von 100 Zeichen, Semikolons,
  nachgestellte Kommas gemäß `es5` — durch Prettier über `lint-staged` erzwungen.
- **Importe**: extern → intern (`@/`, `@omniroute/open-sse`) → relativ.
- **Benennung**: Dateien in `camelCase` oder `kebab-case`, Komponenten in `PascalCase`,
  Konstanten in `UPPER_SNAKE`.
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = überall `error`;
  `no-explicit-any` = `warn` in `open-sse/` und `tests/`, andernorts `error`.
- **TypeScript**: `strict: false` (historisch bedingt). An modulübergreifenden Grenzen explizite Typen
  gegenüber Typinferenz bevorzugen.
- **Datenbank**: Niemals Roh-SQL in Routen oder Handlern schreiben — immer über
  Module in `src/lib/db/` arbeiten. Niemals Barrel-Importe verwenden — stattdessen bestimmte `src/lib/db/*`-Module direkt importieren.
- **Typisierung von DB-Entitäten (#3512)**: Eine Funktion, die die Zeilenstruktur einer DB-Tabelle
  schreibt oder liest, sollte eine benannte TS-Schnittstelle annehmen/zurückgeben, die die Spalten
  dieser Tabelle 1:1 abbildet, und nicht `any` oder einen anonymen Inline-Typ an der Aufrufstelle. Die
  Schnittstelle direkt bei der Funktion definieren (z. B. `export interface UsageEntry` in
  `src/lib/usage/usageHistory.ts` oberhalb von `saveRequestUsage`), einzelne
  Felder optional/nullable halten, wenn verschiedene schreibende Funktionen die Zeile
  schrittweise befüllen, und `unknown` gegenüber `any` für ein Feld bevorzugen, dessen Struktur
  je nach Aufrufer variiert (am Feld dokumentiert, z. B. akzeptiert `UsageEntry.tokens`
  sowohl rohe, vom Provider vorgegebene Nutzungsdaten als auch die normalisierte Struktur). Sobald die
  Anzahl der `any`-Vorkommen einer Datei auf diese Weise null erreicht, diese zur
  Zulassungsliste von `check:any-budget:t11` hinzufügen (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`), damit keine Regression möglich ist. Dies ist eine Konvention für einen ersten Teilbereich — die
  umfassendere Bereinigung „keine anonymen `any`“ erfolgt iterativ im restlichen
  Codebestand.
- **Fehler**: try/catch mit spezifischen Fehlertypen verwenden und mit pino-Kontext protokollieren. Fehler in
  SSE-Streams niemals stillschweigend unterdrücken; Abort-Signale zur Bereinigung verwenden.
- **Sicherheit**: Niemals `eval()` / `new Function()` / implizites eval verwenden. Alle
  Eingaben mit Zod validieren. Zugangsdaten im Ruhezustand verschlüsseln (AES-256-GCM). Die
  Sperrliste in `src/shared/constants/upstreamHeaders.ts` mit der
  Bereinigungs-/Validierungsschicht synchron halten.
- **Commits**: Conventional Commits — `feat(scope): subject`. Zulässige Bereiche:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Branches**: Präfixe `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/`. Niemals direkt nach `main` committen.
- **Husky**: Vor dem Commit werden `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11` ausgeführt; vor dem Push werden `check:any-budget:t11` + `check:tracked-artifacts` ausgeführt (schnelle Prüfungen; `test:unit` ist ausgeschlossen).

---

## 12. Verbindliche Regeln (aus CLAUDE.md)

1. Niemals Geheimnisse oder Zugangsdaten committen.
2. Niemals Barrel-Imports verwenden — stattdessen direkt die spezifischen `src/lib/db/*`-Module verwenden.
3. Niemals `eval()` / `new Function()` / implizites eval verwenden.
4. Niemals direkt nach `main` committen.
5. Niemals rohes SQL in Routen schreiben — immer die Module unter `src/lib/db/` verwenden.
6. Fehler in SSE-Streams niemals stillschweigend verschlucken.
7. Eingaben immer mit Zod-Schemas validieren.
8. Bei Änderungen am Produktionscode immer Tests hinzufügen.
9. Die Testabdeckung muss bei ≥ 60 % bleiben (Anweisungen, Zeilen, Funktionen, Verzweigungen).

---

## 13. Siehe auch

- [ARCHITECTURE.md](./ARCHITECTURE.md) — allgemeine Architektur und Verantwortlichkeiten
  der Module.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — Referenz für die öffentliche und die Verwaltungs-API.
- [FEATURES.md](../guides/FEATURES.md) — Funktionsübersicht und Versionshighlights.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — ausführliche Erläuterung von Circuit Breaker, Cooldown
  und Lockout.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Bewertung und Strategien für Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — vollständiger MCP-Toolkatalog und Transportmechanismen.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — Fähigkeiten und Erkennung des A2A-Protokolls.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK- und Caveman-Komprimierung.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI-Integrationen.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (falls vorhanden), [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) — Bereitstellungsziele.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — häufige betriebliche Probleme.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — Arbeitsablauf für Mitwirkende.
- [CLAUDE.md](../../CLAUDE.md) — Repository-Regeln für Claude Code (die maßgebliche Quelle
  für viele der oben genannten Konventionen).
- [AGENTS.md](../../AGENTS.md) — ausführlichere, von Agenten verwendete Architekturübersicht.