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

OmniRoute Codebase Documentation (Suomi)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇷 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

---

Versio: v3.8.51 Viimeksi päivitetty: 2026-06-28 Kohderyhmä: Insinöörit, jotka osallistuvat OmniRouten kehittämiseen tai rakentavat integraatioita sen päälle.

Ylätason arkkitehtuurikaaviot ja kunkin alijärjestelmän taustalla olevat perustelut löytyvät tiedostosta ARCHITECTURE.md. Yksittäisten alijärjestelmien (Auto Combo, MCP-palvelin, A2A-palvelin, Skills, Memory, Cloud Agents, Resilience, Compression jne.) perusteelliset kuvaukset löytyvät niiden omista tiedostoista tässä docs/-hakemistossa.

Tämä tiedosto kuvaa mitä repositoriossa on tällä hetkellä, jotta uusi insinööri voi tutustua hakemistorakenteeseen, ymmärtää ajonaikaiset kerrokset ja tietää, minne koodia lisätään ilman uusien moduulien keksimistä.

---

1. Teknologiapino

Osa-alue	Valinta
Web-kehys	Next.js 16 (App Router, itsenäinen julkaisu, ei globaalia väliohjelmistoa)
Kieli	TypeScript 6.0+ — kohde ES2022, module: esnext, moduleResolution: bundler, strict: false
Ajoympäristö	Node.js >=22.22.2 <23 tai >=24.0.0 <27 (pakotetaan asetuksilla engines + SUPPORTED_NODE_RANGE)
Tietokanta	SQLite better-sqlite3:n kautta (singleton, WAL-lokikirjaus)
Työpöytä	Electron 41 + electron-builder 26.10 (erillinen työtila hakemistossa electron/)
Testit	Noden natiivi testiajo-ohjelma (yksikkö-/integraatiotestit), Vitest (MCP, autoCombo, välimuisti), Playwright (e2e + protocols-e2e)
Koonti	Next.jsin itsenäinen julkaisu komentosarjalla scripts/build/build-next-isolated.mjs
Linttaus/muotoilu	ESLintin flat config + Prettier (lint-staged Husky pre-commit -koukun kautta)
Moduulijärjestelmä	ESM kaikkialla ("type": "module")
Työtilat	npm-työtila — open-sse on ainoa alityötila

Polkualiakset (tsconfig.json):

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

HTTP-oletusportti: 20128 (API ja hallintapaneeli käyttävät samaa prosessia). Datahakemisto määritetään DATA_DIR-ympäristömuuttujalla, ja sen oletusarvo on ~/.omniroute/.

---

2. Repositorion rakenne

OmniRoute/
├── src/                  Next.js-sovellus (App Router, kirjastot, toimialue, palvelin, jaetut osat)
├── open-sse/             Suoratoistomoottorin työtila (@omniroute/open-sse)
├── electron/             Työpöytäsovelluksen kääre (Electron 41:n pääprosessi + preload)
├── bin/                  CLI-käynnistyspisteet (omniroute, reset-password)
├── tests/                Yksikkö-, integraatio-, e2e-, protocols-e2e-, kääntäjä- ja tietoturvatestit sekä testiaineistot
├── scripts/              Koontiin, synkronointiin, tarkistuksiin, migraatioihin ja ajonaikaiseen käyttöön tarkoitetut apukomentosarjat
├── docs/                 Julkinen dokumentaatio (tämä hakemisto)
├── public/               Staattiset resurssit, PWA-manifesti, service worker
├── config/               Esimerkit ajonaikaisista määrityksistä
├── images/               Markkinointi- ja kuvakaappausresurssit
├── _ideia/, _references/, _mono_repo/, _tasks/   Sisäiset luonnokset / suunnittelu (ei sisälly julkaisuun)
├── CLAUDE.md             Repositorion säännöt Claude Codelle
├── AGENTS.md             Syvällisempi arkkitehtuuriviite agenteille
├── package.json          v3.8.51, työtilan juuri
└── tsconfig.json         Polkualiaset + kääntäjän keskeiset asetukset

---

3. src/ — Next.js-sovellus

src/
├── app/                  App Router -sivut + API-reitit
├── lib/                  Ydinkirjastot (tietokanta, todennus, OAuth, taidot, muisti, …)
├── domain/               Puhdas toimialuekerros (käytännöt, varajärjestelyt, kustannukset, lukitus, …)
├── server/               Vain palvelimella käytettävät moduulit (käyttöoikeudet, CORS, todennus)
├── shared/               Tyypit, vakiot, validointi, sopimukset, apuohjelmat (turvallisia rajapintojen yli)
├── mitm/                 Välikäsipalvelimen apuvälineet CLI-integraatiota varten
├── models/               Paikallisten mallien metatiedot / aliasointi
├── sse/                  Vanhat SSE-käsittelijät, jotka sijaitsevat edelleen hakemistossa src/ (eivät open-sse/)
├── store/                Asiakaspuolen tilasäilöt
├── middleware/           Reittitason väliohjelmistoapuohjelmat (ei Next.js:n globaali väliohjelmisto)
├── scripts/              Lähdekoodipuussa olevat sovelluskoodin tuotavissa olevat komentosarjat
├── types/                Ympäröivät ja jaetut TS-tyypit
├── i18n/                 Kielialuepaketit
├── instrumentation.ts    Next.js:n instrumentointikoukku
├── instrumentation-node.ts
└── proxy.ts              Ylätason välityspalvelimen alustuksen apuohjelma

3.1 src/app/ — App Router

App Router tarjoaa sekä hallintapaneelin käyttöliittymän että julkisen ja hallinnollisen HTTP-API:n. Globaalia väliohjelmistoa ei ole — pyynnöt siepataan reittikohtaisesti.

Ylätason segmentit hakemistossa src/app/:

Polku	Tarkoitus
api/	Kaikki HTTP-API-reitit (katso erittely jäljempänä)
a2a/	A2A JSON-RPC 2.0 -päätepiste (POST /a2a)
.well-known/agent.json/	A2A Agent Card -etsintäasiakirja
(dashboard)/	Hallintapaneelin käyttöliittymä (reittiryhmä, ei URL-etuliitettä)
auth/, login/, forgot-password/, callback/	Todennuskulut
landing/	Markkinointi-/aloitussivu
docs/	Upotettu API-dokumentaation katselin
status/, maintenance/, offline/	Operatiiviset sivut
privacy/, terms/	Oikeudelliset sivut
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Staattiset virhesivut
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Kehyksen virhe- ja latausrajat
layout.tsx, page.tsx, globals.css, manifest.ts	Juuritason runko

3.1.1 src/app/(dashboard)/dashboard/ — Käyttöliittymäsivut

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 sekä juuritason page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Ylätason API-ryhmät

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/   Upotettujen palveluiden hallinta (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-yhteensopiva julkinen API
├── v1beta/     Gemini-tyylinen yhteensopivuus
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Upotettujen palveluiden hallinta

Reitit 9Routerin ja CLIProxyAPI:n asentamiseen, käynnistämiseen, pysäyttämiseen ja valvontaan. Kaikki polut on luokiteltu LOCAL_ONLY-luokkaan (vain loopback, ehdoton sääntö #17), koska ne voivat suorittaa npm install -komennon ja käynnistää aliprosesseja.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor()-apufunktio
│   ├── install/route.ts    POST — npm-asennus execFile-komennolla
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — uudemman version npm-asennus
│   ├── rotate-key/route.ts POST — luo uusi API-avain + käynnistä uudelleen
│   ├── status/route.ts     GET  — reaaliaikainen + tietokannan tila + version metatiedot
│   └── auto-start/route.ts POST — vaihda auto_start-lippu
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor()-apufunktio
│   ├── install/route.ts    POST — npm-asennus
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — uudemman version npm-asennus
│   ├── status/route.ts     GET  — reaaliaikainen + tietokannan tila + version metatiedot
│   └── auto-start/route.ts POST — vaihda auto_start-lippu
└── [name]/
    └── logs/route.ts       GET  — SSE-lokin loppupää (kaikkien palveluiden yhteinen)

Vastaava koontinäytön käyttöliittymä: src/app/(dashboard)/dashboard/providers/services/ — kahden välilehden sivu (CLIProxyAPI + 9Router). Käänteinen välityspalvelin upotetulle 9Router-käyttöliittymälle: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Syvällinen kuvaus: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-yhteensopiva julkinen API

v1/
├── accounts/[id]/                       tilin haku
├── agents/tasks/[id]/, agents/tasks/    A2A-tyyliset tehtäväpäätepisteet
├── api/                                 sisäiset API-apufunktiot, jotka on julkaistu polussa v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    keskustelutäydennykset (pääasiallinen päätepiste)
├── completions/                         vanhat tekstin täydennykset
├── embeddings/                          upotukset
├── files/[id]/, files/                  Files API
├── _helpers/                            jaetut reittien apufunktiot (ei julkista URL-osoitetta)
├── images/{edits, generations}/         kuvien generointi + muokkaus
├── issues/                              luokittelun apupäätepisteet
├── management/{proxies}/                hallinnan laajuiset reitit v1:n sisällä
├── messages/{count_tokens}/             Anthropic-tyylinen viestiyhteensopivuus
├── models/                              mallien luettelo (`route.ts`, `catalog.ts`)
├── moderations/                         moderointi
├── music/                               musiikin generointi
├── providers/[provider]/                palveluntarjoajakohtaiset toiminnot
├── quotas/{check}                       kiintiöiden tarkistukset
├── registered-keys/                     rekisteröityjen avainten hallinta
├── rerank/                              uudelleensijoittelu
├── responses/[...path]/                 OpenAI Responses API (kaiken kattava)
├── search/                              verkkohaku
├── videos/                              videoiden generointi
├── ws/                                  WebSocket-silta
└── route.ts                             indeksikäsittelijä

Jokainen reittitiedosto noudattaa samaa mallia:

Reitti → CORS-esitarkistus → Zod-rungon validointi → valinnainen todennus
       → API-avainkäytännön toimeenpano → delegointi käsittelijälle (open-sse)

v1beta/ on Gemini-tyylinen yhteensopivuuspinta (ohut kääre, joka muuntaa pyynnöt samaan open-sse/handlers/-käsittelyketjuun).

3.2 src/lib/ — Ydinkirjastot

Tuo data-, synkronointi-, OAuth-, taito- ja muistitoiminnot sekä muut vastaavat aina näiden moduulien kautta. Taulukossa on ryhmitelty varsinaiset hakemistot ja huomionarvoiset ylätason tiedostot.

Moduuli	Tarkoitus
a2a/	A2A-protokollapalvelin: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 taitoa: kustannusanalyysi, kuntoraportti, palveluntarjoajien etsintä, kiintiöiden hallinta, älykäs reititys, ominaisuuksien luettelointi)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Sisäisen API:n apufunktiot: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (salasanan nollaus / hajautus)
batches/	OpenAI Batches API -palvelu (service.ts)
catalog/	OpenRouter-luettelon synkronointi (openrouterCatalog.ts)
cloudAgent/	Pilviagenttirekisteri: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Yhdistelmien selvittämisen apufunktiot
compliance/	Auditointi + palveluntarjoajien auditointi: index.ts, providerAudit.ts
config/	Ajonaikaisen määrityksen yhdyskerros
db/	SQLiten toimialuemoduulit (katso §3.2.1)
display/	API-vastauksissa käytettävät käyttöliittymä- ja näyttöapufunktiot
embeddings/	Upotuspalvelurekisteri
env/	Ympäristömuuttujien lataus + introspektio
evals/	Arviointien ajoympäristö
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Taustatyöt (autoUpdate.ts, …)
memory/	Pysyvä muisti: 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-/tuontipalveluntarjoajamoduulit (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 sekä services/, utils/ ja constants/oauth.ts
plugins/	Liitännäisten lataaja (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Hallittujen mallien elinkaari: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Palveluntarjoajien apufunktiot: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — katkaisijan, jäähdytysajan ja lukituksen asetukset
runtime/	Ajonaikaisten ominaisuuksien tunnistus
search/	executeWebSearch.ts
services/	Upotettujen palvelujen kehys: ServiceSupervisor.ts (yleinen aliprosessien valvoja, jossa on toimintolukko, rengaspuskuri ja kunnon tarkistus), bootstrap.ts (prosessitason rekisteröinti ja automaattinen käynnistys), registry.ts (työkalu → valvoja -kartta), apiKey.ts (AES-256-GCM-avainsäilö), modelSync.ts (mallien säännöllinen synkronointi), ringBuffer.ts (5 MB:n kiertävä lokipuskuri), healthCheck.ts (HTTP-kuntotarkistus), types.ts, embedWsProxy.ts (WebSocket-välityspalvelin), installers/{ninerouter,cliproxy}.ts. Katso docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Agent Skills -luettelo + generaattori: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → kirjoittaa tiedostoon skills/{id}/SKILL.md), openapiParser.ts (poimii REST-päätepisteet OpenAPI-määrityksestä), cliRegistryParser.ts (poimii CLI-alikomennot kohteesta bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Käytössä REST-reiteissä (/api/agent-skills/*), MCP-työkaluissa (omniroute_agent_skills_*) ja A2A-taidossa list-capabilities. Katso AGENT-SKILLS.md.
skills/	Taitokehys: 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 sekä builtin/browser.ts
spend/	batchWriter.ts (viivästetyn kirjoituksen puskuri)
sync/	bundle.ts, tokens.ts (pilvisynkronointi)
system/	Järjestelmätason apufunktiot
translator/	Ylimmän tason käännösyhdyskerros (delegoi hakemistoon open-sse/translator/)
usage/	Käytön laskenta: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automaattinen päivitys + versioilmentymä
ws/	WebSocket-silta
zed-oauth/	Zed-editorin OAuth-kulku

Ylimmän tason tiedostot hakemistossa src/lib/:

• Vanha localDb.ts-koontimoduuli poistettiin — käyttäjät tuovat tietyt src/lib/db/*-moduulit suoraan.
• 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-tietokanta (getDbInstance() tiedostossa core.ts, WAL-lokikirjaus). Älä koskaan kirjoita raakaa SQL:ää reitteihin tai käsittelijöihin — käytä näitä moduuleja.

Lähde: diagrams/db-schema-overview.mmd

Toimialuemoduulit (kukin hallitsee yhtä tai useampaa taulua): 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/ sisältää 168 versioitua .sql-tiedostoa (idempotentteja ja transaktionaalisia), ja migrationRunner.ts suorittaa ne käynnistyksen yhteydessä.

Migraatioissa luodut taulut (yhteensä 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 (sekä FTS5-virtuaalitaulut muistihakua varten).

3.3 src/domain/ — Toimialuekerros

Puhdasta liiketoimintalogiikkaa ilman I/O:ta. Reitit ja käsittelijät tuovat näitä moduuleja.

Tiedosto	Tarkoitus
policyEngine.ts	Ylimmän tason käytäntöratkaisija
fallbackPolicy.ts	Varavalintojen päätöspuu
costRules.ts	Kustannusten laskentasäännöt
lockoutPolicy.ts	Mallien lukituspäätökset
tagRouter.ts	Tunnistepohjainen reititys
comboResolver.ts	Yhdistelmän ratkaisu pyynnöstä → kohdeluetteloon
connectionModelRules.ts	Yhteyskohtaiset mallisuodattimet
modelAvailability.ts	Mallin saatavuuden tarkistus
degradation.ts	Heikennetyn tilan siirtymät
providerExpiration.ts	Vanhentuneiden tilien/avainten tunnistus
quotaCache.ts	Välimuistiin tallennetut kiintiöpäätökset
responses.ts, omnirouteResponseMeta.ts	Vastausrakenteen apufunktiot
configAudit.ts	Määritysmuutosten auditointi
assessment/	Mallien arviointi (RFC:n mukainen, osittain toteutettu)
types.ts	Jaetut toimialuetyypit

3.4 src/server/ — Vain palvelimelle

Ei voida tuoda asiakaskomponenteista.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Luokittelee reitit julkisiksi tai hallintareiteiksi
│   ├── assertAuth.ts      Vahvistuksen apufunktio
│   ├── context.ts         Pyyntökohtainen käyttöoikeuskonteksti
│   ├── headers.ts
│   ├── pipeline.ts        Käyttöoikeusputki
│   ├── policies/          Konkreettiset käytännöt
│   └── types.ts
└── cors/origins.ts        CORS-alkuperien sallittujen luettelo

3.5 src/shared/ — Turvallisesti jaettava

Jaettu kohdennettuihin alihakemistoihin:

• constants/ — providers.ts (Zod-validoitu palveluntarjoajaluettelo), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (estolista), 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 (noin 80 Zod-skeemaa), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — npm:ään julkaistavat julkiset API-sopimukset.
• types/ — jaetut TS-tyypit.
• 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 sekä koontinäytön hookit/komponentit hakemistoissa services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Suoratoistomoottorin työtila

Erillinen npm-työtila, joka julkaistaan nimellä @omniroute/open-sse. Vastaa pyyntöjen käsittelystä, suorittimista, muuntimista, palveluista, transformaattorista ja MCP-palvelimesta.

open-sse/
├── index.ts                Julkiset viennit
├── package.json            Työtilan manifesti
├── tsconfig.json
├── types.d.ts
├── config/                 Palveluntarjoajarekisterit, otsakeprofiilit, identiteetti, …
├── handlers/               Pyyntökäsittelijät (keskustelu, upotukset, ääni, kuva, …)
├── executors/              108 palveluntarjoajakohtaista HTTP-suoritinta
├── translator/             Muotomuunnokset (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions -suoratoistotransformaattori
├── services/               Yli 80 palvelumoduulia (yhdistelmät, varajärjestelyt, kiintiöt, identiteetti, …)
├── utils/                  Suoratoiston apuohjelmat, TLS-asiakas, AWS SigV4, välityspalvelinnouto, …
└── mcp-server/             MCP-palvelin (3 siirtotapaa, 33 käyttöaluetta, 110 työkalua)

4.1 open-sse/handlers/

Käsittelijä	Tarkoitus
chatCore.ts	Keskustelun pääkäsittelyketju (välimuisti, nopeusrajoitus, yhdistelmäreititys, suorittimen käynnistys)
responsesHandler.ts	OpenAI Responses API:n käsittelyn aloituspiste
embeddings.ts	Upotukset
imageGeneration.ts	Kuvien generointi
audioSpeech.ts	Tekstistä puheeksi
audioTranscription.ts	Puheesta tekstiksi
videoGeneration.ts	Videoiden generointi
musicGeneration.ts	Musiikin generointi
rerank.ts	Uudelleenjärjestäminen
moderations.ts	Moderointi
search.ts	Verkkohaku
sseParser.ts	SSE-tapahtumien jäsennin
usageExtractor.ts	Tokenmäärien poiminta ylävirran suoratoistoista
responseSanitizer.ts	Palveluntarjoajakohtaisen kohinan poistaminen
responseTranslator.ts	Palveluntarjoajan vastauksen ja muunnoskerroksen välinen liitos

4.2 open-sse/executors/

108 palveluntarjoajasuoritinta, joista jokainen laajentaa BaseExecutor-luokkaa (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 sekä claudeIdentity.ts (jaettu identiteetin apuohjelma) ja index.ts (rekisteri).

Huomautus: palveluntarjoajia, joita ei ole lueteltu tässä, palvelee default.ts yleisen OpenAI-yhteensopivan suorittimen avulla. Täysi palveluntarjoajaluettelo (355 palveluntarjoajaa) sijaitsee tiedostossa src/shared/constants/providers.ts.

4.3 open-sse/translator/

Keskitin ja säteet -mallinen muuntaminen (OpenAI toimii keskittimenä).

• 9 pyyntömuunninta (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 vastausmuunninta (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 apuohjelmaa (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper sekä apuohjelmien testit.
• Kuva-apuohjelmat (translator/image/sizeMapper.ts).
• Päätaso: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — TransformStream-pohjainen Responses API ↔ Chat Completions -muunnin (jota responses/-reitin yleiskäsittelijä käyttää).

4.5 open-sse/services/

Poimintoja (täysi luettelo hakemistossa open-sse/services/):

Osa-alue	Tiedostot
Yhdistelmäreititys	combo.ts (19 strategiaa), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Auto Combo -moottori	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
Häiriönsietokyky	accountFallback.ts (jäähdytysaika + lukitus), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Kiintiöt	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Välimuistit	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Älykäs reititys	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Mallien käsittely	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Pakkaus	compression/ — pakkausmoottorin täydellinen kytkentä
Tunniste + istunto	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Taso / manifesti	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / verkko	ipFilter.ts, webSearchFallback.ts
Erät	batchProcessor.ts
Käyttö	usage.ts

4.6 open-sse/mcp-server/

• 110 yksilöllistä työkalua kytketty tiedostossa server.ts (45 kanonista työkalua tiedostossa schemas/tools.ts + muisti-, taito-, GitHub-taito-, pooli-, pelillistämis-, liitännäis-, Notion-, Obsidian-, paikalliskorpus- ja pakkausmoduulit — yhdisteen määrä lasketaan funktiolla countUniqueMcpTools).
• 3 siirtotapaa: stdio, suoratoistettava HTTP, SSE.
• 33 käyttöaluetta pakotetaan suorituksen aikana — perusluettelo on tiedostossa src/shared/constants/mcpScopes.ts, ja täydellinen joukko on kunkin työkalumoduulin ilmoittamien käyttöalueiden yhdiste.
• Auditointitaulu: mcp_tool_audit (täytetään tiedoston audit.ts avulla).
• Tiedostot: 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, sekä testit hakemistossa __tests__/.
• Täydellinen työkaluluettelo on tiedostossa MCP-SERVER.md.

4.7 open-sse/config/

Palveluntarjoajarekisterit (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), muotokohtaiset mallirekisterit (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), identiteetin apuohjelmat (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), tunnistetietojen apuohjelmat (credentialLoader.ts, codexClient.ts) ja pilvi- sovittimet (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/

Suoratoiston perustoiminnot ja palveluntarjoajien apuohjelmat: 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/ — Työpöytäsovelluksen kääre

electron/
├── main.js                  Electronin pääprosessi
├── preload.js               Esilataussilta (contextIsolation käytössä)
├── types.d.ts
├── package.json             electron-builder-määritykset, versio 3.8.51
├── README.md
├── assets/                  Koontiresurssit (kuvakkeet, käyttöoikeudet, …)
├── node_modules/            Erillinen node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Koontituloste (ei sisälly versionhallintaan)

Työtilan juuressa on viisi npm-komentosarjaa: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Automaattinen päivitys käyttää electron-updater-pakettia, joka osoittaa GitHubin julkaisuvirtaan.

---

6. bin/ — Komentorivityökalu

bin/
├── omniroute.mjs           Komentorivityökalun pääkäynnistystiedosto (Node ESM)
├── reset-password.mjs      Hallintasalasanan nollaus komentoriviltä
├── mcp-server.mjs          MCP-palvelimen käynnistin (stdio)
├── nodeRuntimeSupport.mjs  Node-versiotarkistus
└── cli/
    ├── program.mjs         Commander-ohjelman rakentaja
    ├── runtime.mjs         withRuntime-aputoiminto (ensin palvelin, varalla tietokanta)
    ├── output.mjs          Tulosteen muotoilijat (json/jsonl/table/csv)
    ├── i18n.mjs            t()-aputoiminto kielialueineen
    ├── api.mjs             API-noutojen aputoiminto
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Komentojen rekisteröinti
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (yksi tiedosto komentoa tai ryhmää kohden)

package.json → bin määrittää kaksi suoritettavaa tiedostoa:

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

---

7. tests/

Hakemisto	Tyyppi
tests/unit/	Yksikkötestit Noden omalla testiajourilla (1821 tiedostoa sekä api/-, auth/- ja authz/-alihakemistot)
tests/integration/	Moduulien väliset ja tietokannan tilaa koskevat testit
tests/e2e/	Playwright-käyttöliittymätestit
tests/e2e/protocol-clients.test.ts	MCP/A2A-protokollien päästä päähän -testit
tests/translator/	Kääntäjäkohtaiset testit
tests/security/	Tietoturvan regressiotestit
tests/load/	Kuormitus- ja rasitustestit
tests/golden-set/	Kääntäjän regressiotestien vertailutulosteet
tests/helpers/, tests/fixtures/, tests/manual/	Tukitiedostot

Yleiset komennot:

Komento	Mitä se suorittaa
npm run test:unit	Kaikki tests/unit/*.test.ts-testit Noden testiajourilla (rinnakkaisuus 10)
npm run test:vitest	Vitest-testikokonaisuus (MCP, autoCombo, välimuisti)
npm run test:e2e	Playwright-käyttöliittymätestikokonaisuus
npm run test:protocols:e2e	MCP- ja A2A-protokollien päästä päähän -testit
npm run test:coverage	Kattavuusraja (≥60 % riveistä/lauseista/funktioista/haaroista)
node --import tsx/esm --test tests/unit/<file>.test.ts	Yksittäisen tiedoston suoritus

---

8. scripts/

Järjestetty käyttötarkoituksen mukaan kuuteen alikansioon.

• 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. Pyyntöputki (yhteenveto)

Lähde: diagrams/request-pipeline.mmd

Asiakaspyyntö
  → /v1/chat/completions (route.ts)
     CORS-esitarkistus
     Zod-validointi (chatCompletionsSchema tiedostossa shared/validation/schemas.ts)
     Todennus (extractApiKey + isValidApiKey TAI requireManagementAuth)
     Käytäntömoottori (src/server/authz/pipeline.ts)
     Suojaukset (henkilötietojen peittäjä, kehotesyötteen manipuloinnin esto, kuvasyötteen silta)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Välimuistin tarkistus (semanttinen välimuisti + lukuvälimuisti)
     Nopeusrajoitus (rateLimitManager, accountSemaphore)
     Yhdistelmäreititys (jos malli ratkaistaan yhdistelmäksi)
       comboResolver → silmukka kohteittain → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       pyyntö ylävirtaan → uudelleenyritys/eksponentiaalinen viive accountFallback-mekanismin kautta
     translateResponse() (open-sse/translator/response/*)
     SSE-virta TAI JSON-vastaus
     Jos Responses API: TransformStream tiedoston open-sse/transformer/responsesTransformer.ts kautta
  → Vaatimustenmukaisuuden auditointi (src/lib/compliance/)
  → Vastaus asiakkaalle

Vikasietoisuuden ajonaikainen tila (kolme mekanismia)

Mekanismi	Laajuus	Sijainti
Palveluntarjoajan katkaisija	Koko palveluntarjoaja	src/shared/utils/circuitBreaker.ts, tallennetaan kohteeseen domain_circuit_breakers
Yhteyden jäähdytysaika	Yksi tili/avain	markAccountUnavailable() tiedostossa src/sse/services/auth.ts; accountFallback.checkFallbackError() käyttää sitä
Mallin lukitus	Palveluntarjoaja + yhteys + malli	open-sse/services/accountFallback.ts, tallennetaan kohteeseen domain_lockout_state

Katso RESILIENCE_GUIDE.md ja erillinen osio tiedostossa CLAUDE.md.

---

10. Osallistuminen

Uuden palveluntarjoajan lisääminen

1. Rekisteröi palveluntarjoaja tiedostossa src/shared/constants/providers.ts (Zod validoi sen latauksen yhteydessä).
2. Lisää suorittaja hakemistoon open-sse/executors/, jos mukautettua logiikkaa tarvitaan (laajenna BaseExecutor-luokkaa).
3. Lisää muunnin hakemistoon open-sse/translator/, jos palveluntarjoaja ei käytä OpenAI-muotoa.
4. Jos palveluntarjoaja perustuu OAuthiin, lisää määritykset hakemistoihin src/lib/oauth/providers/ ja src/lib/oauth/services/.
5. Rekisteröi mallit tiedostossa open-sse/config/providerRegistry.ts (tai muotokohtaisessa rekisterissä hakemistossa open-sse/config/).
6. Kirjoita testit hakemistoon tests/unit/.

Uuden API-reitin lisääminen

1. Luo src/app/api/your-route/route.ts.
2. Noudata mallia: CORS → pyynnön rungon Zod-validointi → todennus → käsittelijälle delegointi.
3. Jos pyynnön rakenne on uusi, lisää Zod-skeema tiedostoon src/shared/validation/schemas.ts.
4. Jos reitti on tarkoitettu vain hallintaan, lisää polku tiedostoon src/shared/constants/publicApiRoutes.ts (julkisen API-pinnan estolista).
5. Lisää testit hakemistoon tests/unit/.
6. Päivitä docs/reference/API_REFERENCE.md ja docs/openapi.yaml.

Uuden tietokantamoduulin lisääminen

1. Luo src/lib/db/yourModule.ts ja tuo getDbInstance() tiedostosta ./core.ts.
2. Vie toimialueesi CRUD-funktiot.
3. Jos lisäät uusia tauluja, lisää migraatio hakemistoon src/lib/db/migrations/. Migraatioiden tulee olla numeroitu peräkkäin sekä toteutettu idempotentisti ja transaktionaalisesti.
4. Tuojat käyttävät suoria tuonteja moduulista @/lib/db/yourModule (ei koontimoduulia — vanha localDb.ts-jälleenvientikerros on poistettu).
5. Lisää testit hakemistoon tests/unit/.

Uuden MCP-työkalun lisääminen

1. Lisää työkalun määrittely hakemistoon open-sse/mcp-server/tools/ (tai laajenna tiedostoa open-sse/mcp-server/schemas/tools.ts).
2. Määritä asianmukaiset käyttöoikeusalueet tiedostossa src/shared/constants/mcpScopes.ts.
3. Rekisteröi työkalu tiedostossa open-sse/mcp-server/server.ts.
4. Lisää testit hakemistoon open-sse/mcp-server/__tests__/.
5. Päivitä MCP-SERVER.md.

Uuden A2A-taidon lisääminen

Katso A2A-SERVER.md § Uuden taidon lisääminen. Taidot sijaitsevat hakemistossa src/lib/a2a/skills/, ja ne rekisteröidään A2A-tehtävähallinnan kautta.

---

11. Käytännöt

• Koodityyli: 2 välilyönnin sisennys, lainausmerkkeinä kaksoislainausmerkit, 100 merkin rivinleveys, puolipisteet, es5-tyyliset loppupilkut — Prettier valvoo näitä lint-staged-työkalun kautta.
• Tuonnit: ulkoiset → sisäiset (@/, @omniroute/open-sse) → suhteelliset.
• Nimeäminen: tiedostot camelCase- tai kebab-case-muodossa, komponentit PascalCase-muodossa, vakiot UPPER_SNAKE-muodossa.
• ESLint: no-eval, no-implied-eval, no-new-func = error kaikkialla; no-explicit-any = warn hakemistoissa open-sse/ ja tests/, muualla error.
• TypeScript: strict: false (perintöjärjestelmän käytäntö). Suosi eksplisiittisiä tyyppejä päättelyn sijaan moduulirajoilla.
• Tietokanta: älä koskaan kirjoita raakaa SQL:ää reitteihin tai käsittelijöihin — käytä aina src/lib/db/-moduuleja. Älä koskaan tuo koontimoduulista — käytä suoraan tiettyjä src/lib/db/*-moduuleja.
• Tietokantaentiteettien tyypitys (#3512): funktion, joka kirjoittaa tietokantataulun rivirakenteen tai lukee sen, tulee vastaanottaa/palauttaa nimetty TS-rajapinta, joka vastaa kyseisen taulun sarakkeita yksi yhteen, ei any-tyyppiä tai kutsukohdassa määriteltyä nimetöntä sisäistä tyyppiä. Sijoita rajapinta funktion viereen (esim. export interface UsageEntry tiedostossa src/lib/usage/usageHistory.ts ennen saveRequestUsage-funktiota), pidä yksittäiset kentät valinnaisina/nollattavina, kun eri kirjoittajat täyttävät riviä asteittain, ja suosi unknown-tyyppiä any-tyypin sijaan kentissä, joiden rakenne vaihtelee kutsujien välillä (dokumentoi tämä kentässä; esimerkiksi UsageEntry.tokens hyväksyy sekä palveluntarjoajan raakamuotoisen käyttöaineiston että normalisoidun rakenteen). Kun tiedoston any-esiintymien määrä saavuttaa tällä tavoin nollan, lisää se check:any-budget:t11-sallittujen listaan (scripts/check/check-t11-any-budget.mjs, maxAny: 0), jotta tilanne ei voi taantua. Tämä on ensimmäistä osa-aluetta koskeva käytäntö — laajempi nimettömien any-tyyppien poistaminen toteutetaan iteratiivisesti muualla koodikannassa.
• Virheet: käytä try/catch-rakennetta ja täsmällisiä virhetyyppejä sekä kirjaa pino-kontekstin avulla. Älä koskaan ohita virheitä hiljaisesti SSE-virroissa; käytä keskeytyssignaaleja siivoamiseen.
• Tietoturva: älä koskaan käytä eval() / new Function() / epäsuoraa eval-suoritusta. Validoi kaikki syötteet Zodilla. Salaa tunnistetiedot levossa (AES-256-GCM). Pidä tiedoston src/shared/constants/upstreamHeaders.ts estolista yhdenmukaisena puhdistus-/validointikerroksen kanssa.
• Commitit: Conventional Commits — feat(scope): subject. Sallitut kohdealueet: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Haarat: etuliitteet feat/, fix/, refactor/, docs/, test/, chore/. Älä koskaan commitoi suoraan main-haaraan.
• Husky: pre-commit suorittaa lint-staged + check:docs-sync + check:any-budget:t11; pre-push suorittaa check:any-budget:t11 + check:tracked-artifacts (nopeat tarkistukset; test:unit ei sisälly).

---

12. Ehdottomat säännöt (tiedostosta CLAUDE.md)

1. Älä koskaan commitoi salaisuuksia tai tunnistetietoja.
2. Älä koskaan käytä barrel-tuonteja — käytä suoraan yksittäisiä src/lib/db/*-moduuleja.
3. Älä koskaan käytä eval()- / new Function() -kutsuja tai epäsuoraa eval-toimintoa.
4. Älä koskaan committoi suoraan main-haaraan.
5. Älä koskaan kirjoita raakaa SQL:ää reitteihin — käytä aina src/lib/db/-moduuleja.
6. Älä koskaan jätä SSE-virtojen virheitä hiljaisesti käsittelemättä.
7. Validoi syötteet aina Zod-skeemoilla.
8. Sisällytä aina testit, kun muutat tuotantokoodia.
9. Testikattavuuden on pysyttävä vähintään 60 %:ssa (lauseet, rivit, funktiot ja haarat).

---

13. Katso myös

• ARCHITECTURE.md — yleiskuva arkkitehtuurista ja moduulien vastuista.
• API_REFERENCE.md — julkisen ja hallinta-API:n viite.
• FEATURES.md — ominaisuusmatriisi ja versioiden tärkeimmät uudistukset.
• RESILIENCE_GUIDE.md — perusteellinen katsaus circuit breaker-, cooldown- ja lockout-toimintoihin.
• AUTO-COMBO.md — Auto Combo -pisteytys ja -strategiat.
• MCP-SERVER.md — kattava MCP-työkaluluettelo ja siirtotavat.
• A2A-SERVER.md — A2A-protokollan taidot ja palvelun löytäminen.
• COMPRESSION_GUIDE.md — RTK- ja Caveman-pakkaus.
• CLI-TOOLS.md — CLI-integraatiot.
• ELECTRON_GUIDE.md (jos saatavilla), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — käyttöönottokohteet.
• TROUBLESHOOTING.md — yleiset käyttöongelmat.
• CONTRIBUTING.md — osallistujien työnkulku.
• CLAUDE.md — Claude Coden repositoriosäännöt (ensisijainen lähde monille yllä oleville käytännöille).
• AGENTS.md — agenttien käyttämä yksityiskohtaisempi arkkitehtuuriviite.