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

OmniRoute Codebase Documentation (Svenska)

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

---

Version: v3.8.51 Senast uppdaterad: 2026-06-28 Målgrupp: Ingenjörer som bidrar till OmniRoute eller bygger integrationer ovanpå det.

För övergripande arkitekturdiagram och resonemanget bakom varje delsystem, läs ARCHITECTURE.md. För djupdykningar i enskilda delsystem (Auto Combo, MCP-server, A2A-server, Skills, Memory, Cloud Agents, Resilience, Compression osv.) finns deras dedikerade filer i denna docs/-katalog.

Den här filen beskriver vad som finns i kodförrådet i dag, så att en ny ingenjör kan navigera i trädet, förstå lagren under körning och veta var kod ska läggas till utan att skapa nya moduler.

---

1. Teknikstack

Område	Val
Webbramverk	Next.js 16 (App Router, fristående utdata, ingen global mellanprogramvara)
Språk	TypeScript 6.0+ — mål ES2022, module: esnext, moduleResolution: bundler, strict: false
Körtidsmiljö	Node.js >=22.22.2 <23 eller >=24.0.0 <27 (framtvingas via engines + SUPPORTED_NODE_RANGE)
Databas	SQLite via better-sqlite3 (singleton, WAL-journalföring)
Skrivbord	Electron 41 + electron-builder 26.10 (separat arbetsyta i electron/)
Tester	Nodes inbyggda testkörare (enhets-/integrationstester), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Bygge	Fristående Next.js via scripts/build/build-next-isolated.mjs
Lint/format	Platt ESLint-konfiguration + Prettier (lint-staged via Husky före incheckning)
Modulsystem	ESM överallt ("type": "module")
Arbetsytor	npm-arbetsyta — open-sse är den enda underarbetsytan

Sökvägsalias (tsconfig.json):

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

Standardport för HTTP: 20128 (API:t och instrumentpanelen delar samma process). Data- katalogen anges med miljövariabeln DATA_DIR och är som standard ~/.omniroute/.

---

2. Kodförrådets struktur

OmniRoute/
├── src/                  Next.js-applikation (App Router, bibliotek, domän, server, delat)
├── open-sse/             Arbetsyta för strömningsmotorn (@omniroute/open-sse)
├── electron/             Skrivbordsomslag (Electron 41, huvudprocess + förinläsning)
├── bin/                  CLI-startpunkter (omniroute, reset-password)
├── tests/                Enhets-, integrations-, e2e-, protocols-e2e-, översättnings- och säkerhetstester samt fixturer
├── scripts/              Hjälpskript för bygge, synkronisering, kontroller, migrering och körning
├── docs/                 Offentlig dokumentation (den här katalogen)
├── public/               Statiska resurser, PWA-manifest, service worker
├── config/               Exempel på körtidskonfiguration
├── images/               Marknadsförings-/skärmbildsresurser
├── _ideia/, _references/, _mono_repo/, _tasks/   Internt kladdmaterial/intern planering (levereras inte)
├── CLAUDE.md             Kodförrådsregler för Claude Code
├── AGENTS.md             Djupare arkitekturreferens för agenter
├── package.json          v3.8.51, arbetsytans rot
└── tsconfig.json         Sökvägsalias + centrala kompilatoralternativ

---

3. src/ — Next.js-applikation

src/
├── app/                  App Router-sidor + API-rutter
├── lib/                  Kärnbibliotek (DB, autentisering, OAuth, färdigheter, minne, …)
├── domain/               Rent domänlager (policy, reservlösning, kostnad, låsning, …)
├── server/               Moduler endast för servern (auktorisering, CORS, autentisering)
├── shared/               Typer, konstanter, validering, kontrakt, verktyg (säkra över systemgränser)
├── mitm/                 Hjälpfunktioner för mellanliggande proxy för CLI-integration
├── models/               Metadata/alias för lokala modeller
├── sse/                  Äldre SSE-hanterare som fortfarande finns under src/ (inte open-sse/)
├── store/                Tillståndslager på klientsidan
├── middleware/           Middleware-verktyg på ruttnivå (inte global Next.js-middleware)
├── scripts/              Inbyggda skript som kan importeras av applikationskod
├── types/                Omgivande och delade TS-typer
├── i18n/                 Språkpaket
├── instrumentation.ts    Next.js-hook för instrumentering
├── instrumentation-node.ts
└── proxy.ts              Proxyhjälp på toppnivå för initiering

3.1 src/app/ — App Router

App Router exponerar både instrumentpanelens användargränssnitt och det offentliga HTTP-API:et samt hanterings-API:et. Det finns ingen global middleware — avlyssning görs per rutt.

Segment på toppnivå under src/app/:

Sökväg	Syfte
api/	Alla HTTP API-rutter (se uppdelningen nedan)
a2a/	A2A JSON-RPC 2.0-slutpunkt (POST /a2a)
.well-known/agent.json/	Identifieringsdokument för A2A Agent Card
(dashboard)/	Instrumentpanelens gränssnitt (ruttgrupp, inget URL-prefix)
auth/, login/, forgot-password/, callback/	Autentiseringsflöden
landing/	Marknadsförings-/landningssida
docs/	Inbäddad visare för API-dokumentation
status/, maintenance/, offline/	Driftsidor
privacy/, terms/	Juridiska sidor
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Statiska felsidor
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Ramverkets gränser för fel/inläsning
layout.tsx, page.tsx, globals.css, manifest.ts	Rotskal

3.1.1 src/app/(dashboard)/dashboard/ — Gränssnittssidor

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, samt page.tsx, HomePageClient.tsx och BootstrapBanner.tsx i roten.

3.1.2 src/app/api/ — API-grupper på toppnivå

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/   Hantering av inbäddade tjänster (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-kompatibelt offentligt API
├── v1beta/     Gemini-liknande kompatibilitet
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Hantering av inbäddade tjänster

Rutter för att installera, starta, stoppa och övervaka 9Router och CLIProxyAPI. Alla sökvägar klassificeras som LOCAL_ONLY (endast loopback, strikt regel #17) eftersom de kan anropa npm install och skapa underordnade processer.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             hjälpfunktionen getOrInitSupervisor()
│   ├── install/route.ts    POST — npm-installation via execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm-installation av nyare version
│   ├── rotate-key/route.ts POST — generera ny API-nyckel + starta om
│   ├── status/route.ts     GET  — live- + DB-status + versionsmetadata
│   └── auto-start/route.ts POST — växla flaggan auto_start
├── cliproxy/
│   ├── _lib.ts             hjälpfunktionen 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 — npm-installation av nyare version
│   ├── status/route.ts     GET  — live- + DB-status + versionsmetadata
│   └── auto-start/route.ts POST — växla flaggan auto_start
└── [name]/
    └── logs/route.ts       GET  — SSE-loggsvans (delas av alla tjänster)

Motsvarande användargränssnitt i kontrollpanelen: src/app/(dashboard)/dashboard/providers/services/ — sida med två flikar (CLIProxyAPI + 9Router). Omvänd proxy för 9Routers inbäddade användargränssnitt: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Fördjupning: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-kompatibelt offentligt API

v1/
├── accounts/[id]/                       kontosökning
├── agents/tasks/[id]/, agents/tasks/    A2A-inspirerade slutpunkter för uppgifter
├── api/                                 interna API-hjälpfunktioner exponerade under v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (huvudslutpunkten)
├── completions/                         Äldre textkompletteringar
├── embeddings/                          Inbäddningar
├── files/[id]/, files/                  Files API
├── _helpers/                            Delade rutthjälpfunktioner (ingen offentlig URL)
├── images/{edits, generations}/         Bildgenerering + redigering
├── issues/                              Hjälpslutpunkter för prioritering
├── management/{proxies}/                Hanteringsspecifika rutter inom v1
├── messages/{count_tokens}/             Kompatibilitet med meddelanden i Anthropic-stil
├── models/                              Modellistning (`route.ts`, `catalog.ts`)
├── moderations/                         Moderering
├── music/                               Musikgenerering
├── providers/[provider]/                Åtgärder per leverantör
├── quotas/{check}                       Kvotkontroller
├── registered-keys/                     Administration av registrerade nycklar
├── rerank/                              Omrankning
├── responses/[...path]/                 OpenAI Responses API (uppsamlingsrutt)
├── search/                              Webbsökning
├── videos/                              Videogenerering
├── ws/                                  WebSocket-brygga
└── route.ts                             Indexhanterare

Varje ruttfil följer samma mönster:

Rutt → CORS-förkontroll → Zod-validering av begärandetext → valfri autentisering
     → tillämpning av API-nyckelpolicy → delegering till hanterare (open-sse)

v1beta/ är kompatibilitetsytan i Gemini-stil (ett tunt omslag som översätter till samma pipeline i open-sse/handlers/).

3.2 src/lib/ — Kärnbibliotek

Importera alltid data, synkronisering, OAuth, färdigheter, minne osv. via dessa moduler. Tabellen grupperar de faktiska katalogerna och betydande filer på toppnivå.

Modul	Syfte
a2a/	A2A-protokollserver: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 färdigheter: kostnadsanalys, hälsorapport, leverantörsidentifiering, kvothantering, smart dirigering, listning av funktioner)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Interna API-hjälpfunktioner: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (återställning/hashning av lösenord)
batches/	Tjänst för OpenAI Batches API (service.ts)
catalog/	Synkronisering av OpenRouter-katalogen (openrouterCatalog.ts)
cloudAgent/	Register över molnagenter: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Hjälpfunktioner för upplösning av kombinationer
compliance/	Granskning + leverantörsgranskning: index.ts, providerAudit.ts
config/	Sammanbindande kod för körningskonfiguration
db/	SQLite-domänmoduler (se §3.2.1)
display/	UI-/visningshjälpfunktioner som används av API-svar
embeddings/	Register över inbäddningstjänster
env/	Inläsning + inspektion av miljövariabler
evals/	Körningsmiljö för utvärderingar
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Bakgrundsjobb (autoUpdate.ts, …)
memory/	Beständigt minne: 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-/importmoduler för leverantörer (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, samt services/, utils/ och constants/oauth.ts
plugins/	Insticksmodulinläsare (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Hanterad livscykel för modeller: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Hjälpfunktioner för leverantörer: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — inställningar för kretsbrytare, nedkylningsperiod och spärr
runtime/	Identifiering av körningsfunktioner
search/	executeWebSearch.ts
services/	Ramverk för inbäddade tjänster: ServiceSupervisor.ts (generisk övervakare av underordnade processer med åtgärdslås, ringbuffert och hälsokontroll), bootstrap.ts (registrering och automatisk start på processnivå), registry.ts (verktyg → övervakare-mappning), apiKey.ts (AES-256-GCM-nyckellager), modelSync.ts (periodisk modellsynkronisering), ringBuffer.ts (5 MB cirkulär loggbuffert), healthCheck.ts (HTTP-hälsokontroll), types.ts, embedWsProxy.ts (WebSocket-proxy), installers/{ninerouter,cliproxy}.ts. Se docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalog + generator för agentfärdigheter: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → skriver skills/{id}/SKILL.md), openapiParser.ts (extraherar REST-slutpunkter från OpenAPI-specifikationen), cliRegistryParser.ts (extraherar CLI-underkommandon från bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Används av REST-rutter (/api/agent-skills/*), MCP-verktyg (omniroute_agent_skills_*) och A2A-färdigheten list-capabilities. Se AGENT-SKILLS.md.
skills/	Färdighetsramverk: 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, samt builtin/browser.ts
spend/	batchWriter.ts (efterskrivningsbuffert)
sync/	bundle.ts, tokens.ts (molnsynkronisering)
system/	Hjälpfunktioner på systemnivå
translator/	Sammanbindande kod för översättning på toppnivå (delegerar till open-sse/translator/)
usage/	Användningsredovisning: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automatisk uppdatering + versionsmanifest
ws/	WebSocket-brygga
zed-oauth/	OAuth-flöde för Zed-redigeraren

Filer på toppnivå i src/lib/:

• Den gamla barrel-filen localDb.ts togs bort — konsumenter importerar specifika src/lib/db/*-moduler 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-databas (getDbInstance() i core.ts, WAL-journalföring). Skriv aldrig rå SQL i routes eller handlers — gå via dessa moduler.

Källa: diagrams/db-schema-overview.mmd

Domänmoduler (var och en ansvarar för en eller flera tabeller): 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/ innehåller 168 versionshanterade .sql-filer (idempotenta, transaktionella) och körs av migrationRunner.ts vid uppstart.

Tabeller som skapas i migreringarna (totalt 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 (plus virtuella FTS5-tabeller för minnessökning).

3.3 src/domain/ — Domänlager

Ren affärslogik, ingen I/O. Importeras av routes och handlers.

Fil	Syfte
policyEngine.ts	Övergripande policyresolver
fallbackPolicy.ts	Beslutsträd för fallback
costRules.ts	Regler för kostnadsberäkning
lockoutPolicy.ts	Beslut om modellspärrning
tagRouter.ts	Taggbaserad routing
comboResolver.ts	Kombinationslösning från begäran → mållista
connectionModelRules.ts	Modellfilter per anslutning
modelAvailability.ts	Kontroll av modelltillgänglighet
degradation.ts	Övergångar till degraderat läge
providerExpiration.ts	Identifiering av utgångna konton/nycklar
quotaCache.ts	Cachade kvotbeslut
responses.ts, omnirouteResponseMeta.ts	Hjälpfunktioner för svarsformat
configAudit.ts	Granskning av konfigurationsändringar
assessment/	Modellutvärdering (enligt RFC, delvis implementerad)
types.ts	Delade domäntyper

3.4 src/server/ — Endast server

Kan inte importeras från klientkomponenter.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Klassificerar routes som publika eller administrativa
│   ├── assertAuth.ts      Hjälpfunktion för verifiering
│   ├── context.ts         Authz-kontext per begäran
│   ├── headers.ts
│   ├── pipeline.ts        Authz-pipeline
│   ├── policies/          Konkreta policyer
│   └── types.ts
└── cors/origins.ts        Tillåtelselista för CORS-ursprung

3.5 src/shared/ — Säker att dela

Uppdelad i fokuserade underkataloger:

• constants/ — providers.ts (Zod-validerad leverantörskatalog), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (spärrlista), 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-scheman), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — offentliga API-kontrakt som distribueras till npm.
• types/ — delade TS-typer.
• 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, samt hooks/komponenter för instrumentpanelen under services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Arbetsyta för strömningsmotorn

Separat npm-arbetsyta publicerad som @omniroute/open-sse. Ansvarar för bearbetning av förfrågningar, exekverare, översättare, tjänster, transformeraren och MCP-servern.

open-sse/
├── index.ts                Publika exporter
├── package.json            Arbetsytemanifest
├── tsconfig.json
├── types.d.ts
├── config/                 Leverantörsregister, rubrikprofiler, identitet, …
├── handlers/               Förfrågningshanterare (chatt, inbäddningar, ljud, bild, …)
├── executors/              108 leverantörsspecifika HTTP-exekverare
├── translator/             Formatkonvertering (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Strömtransformerare för Responses API ↔ Chat Completions
├── services/               Över 80 tjänstemoduler (kombinationer, reservlösningar, kvoter, identitet, …)
├── utils/                  Strömningshjälpare, TLS-klient, AWS SigV4, proxyhämtning, …
└── mcp-server/             MCP-server (3 transporter, 33 omfång, 110 verktyg)

4.1 open-sse/handlers/

Hanterare	Syfte
chatCore.ts	Huvudsaklig chattpipeline (cache, hastighetsbegränsning, kombinationsdirigering, exekverardispatch)
responsesHandler.ts	Startpunkt för OpenAI Responses API
embeddings.ts	Inbäddningar
imageGeneration.ts	Bildgenerering
audioSpeech.ts	Text-till-tal
audioTranscription.ts	Tal-till-text
videoGeneration.ts	Videogenerering
musicGeneration.ts	Musikgenerering
rerank.ts	Omrankning
moderations.ts	Moderering
search.ts	Webbsökning
sseParser.ts	SSE-händelseparser
usageExtractor.ts	Hämtar tokenantal från uppströmsflöden
responseSanitizer.ts	Tar bort leverantörsspecifikt brus
responseTranslator.ts	Koppling mellan leverantörssvaret och översättningslagret

4.2 open-sse/executors/

108 leverantörsexekverare som var och en utökar BaseExecutor (base.ts):

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop, samt claudeIdentity.ts (delad identitetshjälpare) och index.ts (register).

Obs! Leverantörer som inte listas här hanteras av default.ts med den generiska OpenAI-kompatibla exekveraren. Den fullständiga leverantörskatalogen (355 leverantörer) finns i src/shared/constants/providers.ts.

4.3 open-sse/translator/

Nav-och-ekrar-översättning (OpenAI är navet).

• 9 förfrågningsöversättare (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 svarsöversättare (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 hjälpare (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, samt hjälptester.
• Bildhjälpare (translator/image/sizeMapper.ts).
• På toppnivå: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — TransformStream-baserad konverterare för Responses API ↔ Chat Completions (används av reservrutten responses/).

4.5 open-sse/services/

Höjdpunkter (fullständig lista under open-sse/services/):

Område	Filer
Kombinationsroutning	combo.ts (19 strategier), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Automatisk kombinationsmotor	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
Feltålighet	accountFallback.ts (nedkylning + låsning), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Kvoter	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Cachelagring	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Intelligent routning	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Modellhantering	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Komprimering	compression/ — fullständig inkoppling av komprimeringsmotorn
Token + session	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Nivå/manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP/nätverk	ipFilter.ts, webSearchFallback.ts
Batchar	batchProcessor.ts
Användning	usage.ts

4.6 open-sse/mcp-server/

• 110 unika verktyg inkopplade i server.ts (45 kanoniska i schemas/tools.ts + minnes-, färdighets-, GitHub-färdighets-, pool-, spelifierings-, plugin-, Notion-, Obsidian-, lokalkorpus- och komprimeringsmoduler — unionen räknas av countUniqueMcpTools).
• 3 transporter: stdio, HTTP Streamable, SSE.
• 33 behörighetsomfång tillämpas vid körning — baslistan finns i src/shared/constants/mcpScopes.ts, och den fullständiga uppsättningen är unionen av de behörighetsomfång som deklareras av varje verktygsmodul.
• Granskningstabell: mcp_tool_audit (fylls i av audit.ts).
• Filer: 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, samt tester under __tests__/.
• Se MCP-SERVER.md för den fullständiga verktygskatalogen.

4.7 open-sse/config/

Leverantörsregister (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), modellspecifika register per format (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), identitetshjälpare (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), autentiseringsuppgiftshjälpare (credentialLoader.ts, codexClient.ts) och moln- adaptrar (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/

Strömningsprimitiver och leverantörshjälpare: 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/ — Skrivbordsomslag

electron/
├── main.js                  Electron-huvudprocess
├── preload.js               Preload-brygga (contextIsolation aktiverat)
├── types.d.ts
├── package.json             electron-builder-konfiguration, version 3.8.51
├── README.md
├── assets/                  Byggresurser (ikoner, rättigheter, …)
├── node_modules/            Dedikerad node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Byggutdata (inte incheckat)

Fem npm-skript i arbetsytans rot: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Automatisk uppdatering sker via electron-updater, som pekar på GitHub-flödet för utgåvor.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Huvudsaklig CLI-startpunkt (Node ESM)
├── reset-password.mjs      Återställ hanteringslösenordet från CLI
├── mcp-server.mjs          Startprogram för MCP-server (stdio)
├── nodeRuntimeSupport.mjs  Kontroll av Node-version
└── cli/
    ├── program.mjs         Programbyggare för Commander
    ├── runtime.mjs         withRuntime-hjälpare (server först/databas som reserv)
    ├── output.mjs          Utdataformaterare (json/jsonl/table/csv)
    ├── i18n.mjs            t()-hjälpare med språkinställningar
    ├── api.mjs             Hjälpare för API-anrop
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Kommandoregistrering
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (en fil per kommando/grupp)

Två binärfiler exponeras i package.json → bin:

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

---

7. tests/

Katalog	Typ
tests/unit/	Enhetstester via Nodes inbyggda testkörare (1821 filer, plus underkatalogerna api/, auth/, authz/)
tests/integration/	Tester över flera moduler samt tester av databastillstånd
tests/e2e/	Playwright-UI-tester
tests/e2e/protocol-clients.test.ts	E2E-tester för MCP/A2A-protokoll
tests/translator/	Översättarspecifika tester
tests/security/	Säkerhetsregressioner
tests/load/	Belastnings-/stresstester
tests/golden-set/	Referensutdata för översättningsregressioner
tests/helpers/, tests/fixtures/, tests/manual/	Stöd

Vanliga kommandon:

Kommando	Vad det kör
npm run test:unit	Alla tests/unit/*.test.ts via Nodes testkörare (samtidighet 10)
npm run test:vitest	Vitest-sviten (MCP, autoCombo, cache)
npm run test:e2e	Playwright-UI-sviten
npm run test:protocols:e2e	E2E-tester för MCP- och A2A-protokollen
npm run test:coverage	Täckningsgräns (≥60 % rader/satser/funktioner/grenar)
node --import tsx/esm --test tests/unit/<file>.test.ts	Körning av en enskild fil

---

8. scripts/

Organiserad i 6 undermappar efter syfte.

• scripts/build/ — build-next-isolated.mjs, prepublish.ts, prepare-electron-standalone.mjs, pack-artifact-policy.ts, validate-pack-artifact.ts, postinstall.mjs, postinstallSupport.mjs, uninstall.mjs, bootstrap-env.mjs, runtime-env.mjs, native-binary-compat.mjs.
• scripts/dev/ — run-next.mjs, run-next-playwright.mjs, run-standalone.mjs, standalone-server-ws.mjs, responses-ws-proxy.mjs, v1-ws-bridge.mjs, smoke-electron-packaged.mjs, run-playwright-tests.mjs, run-ecosystem-tests.mjs, run-protocol-clients-tests.mjs, sync-env.mjs, healthcheck.mjs, system-info.mjs.
• scripts/check/ — check-cycles.mjs, check-docs-sync.mjs, check-docs-counts-sync.mjs, check-env-doc-sync.mjs, check-deprecated-versions.mjs, check-route-validation.mjs, check-t11-any-budget.mjs, check-pr-test-policy.mjs, check-supported-node-runtime.ts, test-report-summary.mjs.
• scripts/docs/ — generate-docs-index.mjs, gen-provider-reference.ts.
• scripts/i18n/ — generate-multilang.mjs, run-visual-qa.mjs, generate-qa-checklist.mjs, apply-priority-overrides.mjs, validate_translation.py, check_translations.py, i18n_autotranslate.py, untranslatable-keys.json.
• scripts/ad-hoc/ — cursor-tap.cjs, sync-cursor-models.mjs, migrate-env.mjs, dbsetup.js.

---

9. Pipeline för begäranden (sammanfattning)

Källa: diagrams/request-pipeline.mmd

Klientbegäran
  → /v1/chat/completions (route.ts)
     CORS-preflightkontroll
     Zod-validering (chatCompletionsSchema i shared/validation/schemas.ts)
     Autentisering (extractApiKey + isValidApiKey ELLER requireManagementAuth)
     Policymotor (src/server/authz/pipeline.ts)
     Skyddsmekanismer (PII-maskerare, promptinjektion, bildbrygga)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Cachekontroll (semantisk cache + läscache)
     Hastighetsbegränsning (rateLimitManager, accountSemaphore)
     Kombinationsroutning (om modellen matchar en kombination)
       comboResolver → slinga per mål → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       hämtning från uppströmskälla → nytt försök/exponentiell väntetid via accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE-ström ELLER JSON-svar
     Om Responses API: TransformStream via open-sse/transformer/responsesTransformer.ts
  → Efterlevnadsgranskning (src/lib/compliance/)
  → Svar till klienten

Resiliensens körtidstillstånd (tre mekanismer)

Mekanism	Omfattning	Var
Kretsbrytare för leverantör	Hela leverantören	src/shared/utils/circuitBreaker.ts, beständigt lagrad i domain_circuit_breakers
Nedkylningsperiod för anslutning	Ett konto/en nyckel	markAccountUnavailable() i src/sse/services/auth.ts; används av accountFallback.checkFallbackError()
Modellspärr	Leverantör + anslutning + modell	open-sse/services/accountFallback.ts, beständigt lagrad i domain_lockout_state

Se RESILIENCE_GUIDE.md och det särskilda avsnittet i CLAUDE.md.

---

10. Så bidrar du

Lägg till en ny leverantör

1. Registrera i src/shared/constants/providers.ts (Zod-valideras vid inläsning).
2. Lägg till en exekverare i open-sse/executors/ om anpassad logik krävs (utöka BaseExecutor).
3. Lägg till en översättare i open-sse/translator/ om leverantören inte använder OpenAI-formatet.
4. Om OAuth används, lägg till konfiguration under src/lib/oauth/providers/ och src/lib/oauth/services/.
5. Registrera modeller i open-sse/config/providerRegistry.ts (eller i det formatspecifika registret under open-sse/config/).
6. Skriv tester under tests/unit/.

Lägg till en ny API-rutt

1. Skapa src/app/api/your-route/route.ts.
2. Följ mönstret: CORS → Zod-validering av body → autentisering → delegering till hanterare.
3. Vid en ny struktur för begäran: lägg till Zod-schemat i src/shared/validation/schemas.ts.
4. Om rutten endast är avsedd för administration: lägg till sökvägen i src/shared/constants/publicApiRoutes.ts (spärrlista för den offentliga API-ytan).
5. Lägg till tester under tests/unit/.
6. Uppdatera docs/reference/API_REFERENCE.md och docs/openapi.yaml.

Lägg till en ny DB-modul

1. Skapa src/lib/db/yourModule.ts och importera getDbInstance() från ./core.ts.
2. Exportera CRUD-funktioner för din domän.
3. Vid nya tabeller: lägg till en migrering under src/lib/db/migrations/, numrerad i ordningsföljd, idempotent och transaktionell.
4. Importerande moduler använder direktimporter från @/lib/db/yourModule (ingen barrel-fil — det gamla återexportlagret localDb.ts har tagits bort).
5. Lägg till tester under tests/unit/.

Lägg till ett nytt MCP-verktyg

1. Lägg till verktygsdefinitionen under open-sse/mcp-server/tools/ (eller utöka open-sse/mcp-server/schemas/tools.ts).
2. Tilldela lämpligt/lämpliga scope i src/shared/constants/mcpScopes.ts.
3. Registrera verktyget i open-sse/mcp-server/server.ts.
4. Lägg till tester under open-sse/mcp-server/__tests__/.
5. Uppdatera MCP-SERVER.md.

Lägg till en ny A2A-färdighet

Se A2A-SERVER.md § Lägga till en ny färdighet. Färdigheter finns i src/lib/a2a/skills/ och registreras via A2A-uppgiftshanteraren.

---

11. Konventioner

• Kodstil: indrag med 2 blanksteg, dubbla citattecken, radbredd på 100 tecken, semikolon, avslutande kommatecken enligt es5 — framtvingas av Prettier via lint-staged.
• Importer: externa → interna (@/, @omniroute/open-sse) → relativa.
• Namngivning: filer använder camelCase eller kebab-case, komponenter PascalCase, konstanter UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error överallt; no-explicit-any = warn i open-sse/ och tests/, annars error.
• TypeScript: strict: false (äldre förhållningssätt). Föredra explicita typer framför inferens vid gränser mellan moduler.
• Databas: skriv aldrig rå SQL i rutter eller hanterare — gå alltid via moduler i src/lib/db/. Använd aldrig barrel-importer — använd specifika src/lib/db/*-moduler direkt.
• Typning av DB-entiteter (#3512): en funktion som skriver eller läser en DB-tabells radstruktur ska ta/emot eller returnera ett namngivet TS-gränssnitt som avspeglar tabellens kolumner 1:1, inte any eller en anonym inline-typ vid anropsplatsen. Placera gränssnittet intill funktionen (t.ex. export interface UsageEntry i src/lib/usage/usageHistory.ts ovanför saveRequestUsage), låt enskilda fält vara valfria/nullbara när olika skrivare fyller i raden stegvis och föredra unknown framför any för ett fält vars struktur varierar mellan anropare (dokumentera detta på fältet, t.ex. att UsageEntry.tokens accepterar både rå användningsdata i leverantörens format och den normaliserade strukturen). När antalet any i en fil når noll på detta sätt ska du lägga till den i tillåtelselistan för check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) så att den inte kan försämras. Detta är en konvention för den första etappen — den bredare upprensningen av ”inga anonyma any” sker iterativt i resten av kodbasen.
• Fel: använd try/catch med specifika feltyper och logga med pino-kontext. Ignorera aldrig fel i SSE-strömmar utan åtgärd; använd avbrottssignaler för rensning.
• Säkerhet: använd aldrig eval() / new Function() / implicit eval. Validera alla indata med Zod. Kryptera autentiseringsuppgifter vid lagring (AES-256-GCM). Håll spärrlistan i src/shared/constants/upstreamHeaders.ts synkroniserad med sanerings-/valideringslagret.
• Commits: Conventional Commits — feat(scope): subject. Tillåtna scope: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Grenar: prefixen feat/, fix/, refactor/, docs/, test/, chore/. Gör aldrig commits direkt till main.
• Husky: pre-commit kör lint-staged + check:docs-sync + check:any-budget:t11; pre-push kör check:any-budget:t11 + check:tracked-artifacts (snabba kontroller; exkluderar test:unit).

---

12. Strikta regler (från CLAUDE.md)

1. Checka aldrig in hemligheter eller autentiseringsuppgifter.
2. Använd aldrig barrel-importer — använd specifika moduler i src/lib/db/* direkt.
3. Använd aldrig eval() / new Function() / implicit eval.
4. Checka aldrig in direkt till main.
5. Skriv aldrig rå SQL i routes — gå alltid via moduler i src/lib/db/.
6. Ignorera aldrig fel i SSE-strömmar utan att rapportera dem.
7. Validera alltid indata med Zod-scheman.
8. Inkludera alltid tester när produktionskod ändras.
9. Täckningsgraden måste förbli ≥ 60 % (satser, rader, funktioner, grenar).

---

13. Se även

• ARCHITECTURE.md — övergripande arkitektur och modulernas ansvarsområden.
• API_REFERENCE.md — referens för publika API:er och hanterings-API:er.
• FEATURES.md — funktionsmatris och versionshöjdpunkter.
• RESILIENCE_GUIDE.md — djupgående information om kretsbrytare, cooldown och lockout.
• AUTO-COMBO.md — poängsättning och strategier för Auto Combo.
• MCP-SERVER.md — fullständig katalog över MCP-verktyg och transporter.
• A2A-SERVER.md — färdigheter och identifiering i A2A-protokollet.
• COMPRESSION_GUIDE.md — RTK- och Caveman-komprimering.
• CLI-TOOLS.md — CLI-integrationer.
• ELECTRON_GUIDE.md (om den finns), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — distributionsmål.
• TROUBLESHOOTING.md — vanliga driftsproblem.
• CONTRIBUTING.md — arbetsflöde för bidragsgivare.
• CLAUDE.md — regler för Claude Code i kodförrådet (den auktoritativa källan för många av konventionerna ovan).
• AGENTS.md — mer djupgående arkitekturreferens som används av agenter.