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

OmniRoute Codebase Documentation (Deutsch)

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

---

Version: v3.8.51 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. 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.
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.

Quelle: 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/ — Workspace für die Streaming-Engine

Separater npm-Workspace, der als @omniroute/open-sse veröffentlicht wird. Verantwortlich für die Anfrageverarbeitung, Executoren, Übersetzer, Services, den Transformer und den MCP-Server.

open-sse/
├── index.ts                Öffentliche Exporte
├── package.json            Workspace-Manifest
├── tsconfig.json
├── types.d.ts
├── config/                 Provider-Registrierungen, Header-Profile, Identität, …
├── handlers/               Anfrage-Handler (Chat, Embeddings, Audio, Bilder, …)
├── executors/              108 providerspezifische HTTP-Executoren
├── translator/             Formatkonvertierung (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions Stream-Transformer
├── services/               Über 80 Service-Module (Kombinationen, Fallback, Kontingente, Identität, …)
├── utils/                  Streaming-Hilfsfunktionen, TLS-Client, AWS SigV4, Proxy-Fetch, …
└── mcp-server/             MCP-Server (3 Transporte, 33 Bereiche, 110 Tools)

4.1 open-sse/handlers/

Handler	Zweck
chatCore.ts	Zentrale Chat-Pipeline (Cache, Ratenbegrenzung, Kombinations-Routing, 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 providerspezifisches Rauschen
responseTranslator.ts	Bindeglied zwischen Provider-Antwort und Übersetzungsschicht

4.2 open-sse/executors/

108 Provider-Executoren, die jeweils BaseExecutor (base.ts) erweitern:

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 Identitäts-Hilfsfunktion) und index.ts (Registrierung).

Hinweis: Hier nicht aufgeführte Provider werden von default.ts über den generischen OpenAI-kompatiblen Executor bedient. Der vollständige Provider-Katalog (355 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 Responses API ↔ Chat Completions-Konverter (verwendet vom Catch-all der Route responses/).

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
Ausfallsicherheit	accountFallback.ts (Abkühlphase + Sperrung), errorClassifier.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, 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 Einbindung 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, eingebunden 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 Bereiche, die zur Laufzeit erzwungen werden — die Basisliste befindet sich in src/shared/constants/mcpScopes.ts; die vollständige Menge ist die Vereinigungsmenge der von den einzelnen Tool-Modulen deklarierten Bereiche.
• Audit-Tabelle: mcp_tool_audit (wird von audit.ts befüllt).
• 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.

4.7 open-sse/config/

Provider-Registrierungen (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), formatspezifische Modellregistrierungen (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-Primitive 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)

Quelle: 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 und den entsprechenden Abschnitt in 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 aktualisieren.

Einen neuen A2A-Skill hinzufügen

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