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

OmniRoute Codebase Documentation (Magyar)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇦🇲 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

---

Verzió: v3.8.51 Utolsó frissítés: 2026-06-28 Célközönség: Az OmniRoute fejlesztésében közreműködő vagy arra épülő integrációkat készítő mérnökök.

A magas szintű architekturális diagramokért és az egyes alrendszerek mögötti tervezési megfontolásokért olvassa el az ARCHITECTURE.md fájlt. Az egyes alrendszerek részletes ismertetését (Auto Combo, MCP-kiszolgáló, A2A-kiszolgáló, Skills, Memory, Cloud Agents, Resilience, Compression stb.) a docs/ könyvtárban található, nekik szentelt fájlokban találja.

Ez a fájl azt ismerteti, mi található jelenleg az adattárban, hogy egy új mérnök eligazodhasson a könyvtárstruktúrában, megérthesse a futásidejű rétegződést, és tudja, hová kell kódot hozzáadnia új modulok kitalálása nélkül.

---

1. Technológiai környezet

Terület	Választás
Webes keretrendszer	Next.js 16 (App Router, önálló kimenet, globális middleware nélkül)
Nyelv	TypeScript 6.0+ — cél: ES2022, module: esnext, moduleResolution: bundler, strict: false
Futtatókörnyezet	Node.js >=22.22.2 <23 vagy >=24.0.0 <27 (az engines + SUPPORTED_NODE_RANGE kényszeríti ki)
Adatbázis	SQLite a better-sqlite3 használatával (singleton, WAL-naplózás)
Asztali alkalmazás	Electron 41 + electron-builder 26.10 (külön munkaterület az electron/ könyvtárban)
Tesztek	Node natív tesztfuttató (egység-/integrációs), Vitest (MCP, autoCombo, gyorsítótár), Playwright (e2e + protocols-e2e)
Build	Önálló Next.js-build a scripts/build/build-next-isolated.mjs használatával
Lint/formázás	ESLint flat config + Prettier (lint-staged a Husky pre-commit hookján keresztül)
Modulrendszer	Mindenhol ESM ("type": "module")
Munkaterületek	npm-munkaterület — az open-sse az egyetlen almunkaterület

Útvonalaliasok (tsconfig.json):

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

Alapértelmezett HTTP-port: 20128 (az API és a vezérlőpult ugyanazt a folyamatot használja). Az adatkönyvtárat a DATA_DIR környezeti változó határozza meg; alapértelmezett értéke ~/.omniroute/.

---

2. Az adattár felépítése

OmniRoute/
├── src/                  Next.js-alkalmazás (App Router, könyvtárak, tartomány, kiszolgáló, megosztott elemek)
├── open-sse/             Streamelési motor munkaterülete (@omniroute/open-sse)
├── electron/             Asztali alkalmazásburkoló (Electron 41 főfolyamat + preload)
├── bin/                  CLI-belépési pontok (omniroute, reset-password)
├── tests/                Egység-, integrációs, e2e-, protocols-e2e-, fordító- és biztonsági tesztek, valamint tesztadatok
├── scripts/              Build-, szinkronizálási, ellenőrzési, migrációs és futásidejű segédszkriptek
├── docs/                 Nyilvános dokumentáció (ez a könyvtár)
├── public/               Statikus erőforrások, PWA-manifeszt, service worker
├── config/               Futásidejű konfigurációs minták
├── images/               Marketing- és képernyőkép-erőforrások
├── _ideia/, _references/, _mono_repo/, _tasks/   Belső jegyzetek / tervezési anyagok (nem részei a kiadásnak)
├── CLAUDE.md             Az adattár Claude Code-ra vonatkozó szabályai
├── AGENTS.md             Részletesebb architekturális referencia az ügynökök számára
├── package.json          v3.8.51, munkaterület gyökere
└── tsconfig.json         Útvonalaliasok + alapvető fordítóbeállítások

---

3. src/ — Next.js-alkalmazás

src/
├── app/                  App Router-oldalak + API-útvonalak
├── lib/                  Alapvető könyvtárak (DB, hitelesítés, OAuth, készségek, memória, …)
├── domain/               Tiszta tartományi réteg (szabályzat, tartalék, költség, kizárás, …)
├── server/               Kizárólag szerveroldali modulok (jogosultságkezelés, CORS, hitelesítés)
├── shared/               Típusok, konstansok, ellenőrzés, szerződések, segédprogramok (határokon át biztonságos)
├── mitm/                 Közbeékelődéses proxy segédeszközei a CLI-integrációhoz
├── models/               Helyi modellek metaadatai / álnevei
├── sse/                  Régi SSE-kezelők, amelyek továbbra is az src/ alatt találhatók (nem az open-sse/ alatt)
├── store/                Kliensoldali állapottárolók
├── middleware/           Útvonalszintű middleware-segédprogramok (nem globális Next.js middleware)
├── scripts/              Az alkalmazáskód által importálható, forrásfán belüli szkriptek
├── types/                Környezeti és megosztott TS-típusok
├── i18n/                 Területi beállítások csomagjai
├── instrumentation.ts    Next.js-instrumentációs horog
├── instrumentation-node.ts
└── proxy.ts              Legfelső szintű proxyindítási segéd

3.1 src/app/ — App Router

Az App Router a vezérlőpult felhasználói felületét és a nyilvános/felügyeleti HTTP API-t egyaránt elérhetővé teszi. Nincs globális middleware — az elfogás útvonalanként történik.

A src/app/ legfelső szintű szegmensei:

Útvonal	Rendeltetés
api/	Minden HTTP API-útvonal (a bontást lásd alább)
a2a/	A2A JSON-RPC 2.0 végpont (POST /a2a)
.well-known/agent.json/	A2A Agent Card felderítési dokumentum
(dashboard)/	Vezérlőpult felhasználói felülete (útvonalcsoport, URL-előtag nélkül)
auth/, login/, forgot-password/, callback/	Hitelesítési folyamatok
landing/	Marketing-/nyitóoldal
docs/	Beágyazott API-dokumentáció-megjelenítő
status/, maintenance/, offline/	Üzemeltetési oldalak
privacy/, terms/	Jogi oldalak
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Statikus hibaoldalak
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Keretrendszerszintű hiba- és betöltési határok
layout.tsx, page.tsx, globals.css, manifest.ts	Gyökérszintű alkalmazásváz

3.1.1 src/app/(dashboard)/dashboard/ — Felhasználói felületi oldalak

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, valamint a gyökérszintű page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Legfelső szintű API-csoportok

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/   Beágyazott szolgáltatások kezelése (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI-kompatibilis nyilvános API
├── v1beta/     Gemini-stílusú kompatibilitás
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Beágyazott szolgáltatások kezelése

Útvonalak a 9Router és a CLIProxyAPI telepítéséhez, elindításához, leállításához és megfigyeléséhez. Minden útvonal LOCAL_ONLY besorolású (csak visszacsatolási interfészen, 17. szigorú szabály), mivel meghívhatják az npm install parancsot, és gyermekfolyamatokat indíthatnak.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() segédfüggvény
│   ├── install/route.ts    POST — npm install az execFile használatával
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — újabb verzió telepítése az npm segítségével
│   ├── rotate-key/route.ts POST — új API-kulcs generálása + újraindítás
│   ├── status/route.ts     GET  — élő + adatbázisbeli állapot + verzió-metaadatok
│   └── auto-start/route.ts POST — az auto_start jelző átváltása
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() segédfüggvény
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — újabb verzió telepítése az npm segítségével
│   ├── status/route.ts     GET  — élő + adatbázisbeli állapot + verzió-metaadatok
│   └── auto-start/route.ts POST — az auto_start jelző átváltása
└── [name]/
    └── logs/route.ts       GET  — SSE-naplófolyam vége (minden szolgáltatás közösen használja)

A hozzá tartozó irányítópult-felület: src/app/(dashboard)/dashboard/providers/services/ — kétlapos oldal (CLIProxyAPI + 9Router). Fordított proxy a 9Router beágyazott felületéhez: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Részletes leírás: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-kompatibilis nyilvános API

v1/
├── accounts/[id]/                       fióklekérdezés
├── agents/tasks/[id]/, agents/tasks/    A2A-jellegű feladat-végpontok
├── api/                                 a v1/api alatt elérhető belső API-segédfüggvények
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    csevegési kiegészítések (a fő végpont)
├── completions/                         örökölt szövegkiegészítések
├── embeddings/                          beágyazások
├── files/[id]/, files/                  fájl-API
├── _helpers/                            megosztott útvonal-segédfüggvények (nincs nyilvános URL)
├── images/{edits, generations}/         képgenerálás + szerkesztés
├── issues/                              osztályozási segédvégpontok
├── management/{proxies}/                felügyeleti hatókörű útvonalak a v1-en belül
├── messages/{count_tokens}/             Anthropic-stílusú üzenetkompatibilitás
├── models/                              modelllista (`route.ts`, `catalog.ts`)
├── moderations/                         moderálás
├── music/                               zenegenerálás
├── providers/[provider]/                szolgáltatónkénti műveletek
├── quotas/{check}                       kvótaellenőrzések
├── registered-keys/                     regisztrált kulcsok adminisztrációja
├── rerank/                              újrarangsorolás
├── responses/[...path]/                 OpenAI Responses API (mindent elfogó)
├── search/                              webes keresés
├── videos/                              videógenerálás
├── ws/                                  WebSocket-híd
└── route.ts                             indexkezelő

Minden útvonalfájl ugyanazt a mintát követi:

Útvonal → CORS-előzetes kérés → Zod-törzsellenőrzés → opcionális hitelesítés
        → API-kulcs-szabályzat érvényesítése → delegálás a kezelőnek (open-sse)

A v1beta/ a Gemini-stílusú kompatibilitási felület (egy vékony burkoló, amely ugyanabba az open-sse/handlers/ folyamatba fordítja át a kéréseket).

3.2 src/lib/ — Alapkönyvtárak

Az adatokat, a szinkronizálást, az OAuth-ot, a készségeket, a memóriát stb. mindig ezeken a modulokon keresztül importálja. A táblázat a tényleges könyvtárakat és a jelentősebb legfelső szintű fájlokat csoportosítja.

Modul	Rendeltetés
a2a/	A2A protokollkiszolgáló: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 képesség: költségelemzés, állapotjelentés, szolgáltatófelderítés, kvótakezelés, intelligens útválasztás, képességek listázása)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Belső API-segédeszközök: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (jelszó-visszaállítás / kivonatolás)
batches/	OpenAI Batches API-szolgáltatás (service.ts)
catalog/	OpenRouter-katalógus szinkronizálása (openrouterCatalog.ts)
cloudAgent/	Felhőügynökök nyilvántartása: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Segédeszközök kombinációk feloldásához
compliance/	Auditálás + szolgáltatói auditálás: index.ts, providerAudit.ts
config/	Futásidejű konfigurációs összekötő réteg
db/	SQLite tartománymodulok (lásd: §3.2.1)
display/	Az API-válaszok által használt felhasználóifelület- és megjelenítési segédeszközök
embeddings/	Beágyazási szolgáltatások nyilvántartása
env/	Környezeti változók betöltése + vizsgálata
evals/	Kiértékelési futtatókörnyezet
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Háttérfeladatok (autoUpdate.ts, …)
memory/	Tartós memória: 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álási szolgáltatói modulok (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, továbbá services/, utils/ és constants/oauth.ts
plugins/	Beépülőmodul-betöltő (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Felügyelt modell-életciklus: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Szolgáltatói segédeszközök: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — az áramkör-megszakító, a várakozási idő és a kizárás beállításai
runtime/	Futásidejű funkcióészlelés
search/	executeWebSearch.ts
services/	Beágyazott szolgáltatási keretrendszer: ServiceSupervisor.ts (általános gyermekfolyamat-felügyelő műveleti zárral, gyűrűpufferrel és állapotellenőrzővel), bootstrap.ts (folyamatszintű regisztráció és automatikus indítás), registry.ts (eszköz → felügyelő leképezés), apiKey.ts (AES-256-GCM-kulcstároló), modelSync.ts (időszakos modell-szinkronizálás), ringBuffer.ts (5 MB-os körkörös naplópuffer), healthCheck.ts (HTTP-állapotvizsgálat), types.ts, embedWsProxy.ts (WebSocket-proxy), installers/{ninerouter,cliproxy}.ts. Lásd: docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Ügynökképesség-katalógus + generátor: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → a skills/{id}/SKILL.md fájlba ír), openapiParser.ts (REST-végpontokat nyer ki az OpenAPI-specifikációból), cliRegistryParser.ts (CLI-alparancsokat nyer ki a bin/cli-registry-ből), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). REST-útvonalak (/api/agent-skills/*), MCP-eszközök (omniroute_agent_skills_*) és az A2A list-capabilities képesség használják. Lásd: AGENT-SKILLS.md.
skills/	Képesség-keretrendszer: 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, valamint builtin/browser.ts
spend/	batchWriter.ts (késleltetett írási puffer)
sync/	bundle.ts, tokens.ts (felhőszinkronizálás)
system/	Rendszerszintű segédeszközök
translator/	Felső szintű fordítási összekötő réteg (az open-sse/translator/ számára delegál)
usage/	Használatelszámolás: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automatikus frissítés + verziójegyzék
ws/	WebSocket-híd
zed-oauth/	A Zed szerkesztő OAuth-folyamata

A src/lib/ legfelső szintű fájljai:

• A régi localDb.ts gyűjtőmodult eltávolítottuk — a felhasználók közvetlenül importálják az egyes src/lib/db/* modulokat.
• 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-adatbázis (getDbInstance() a core.ts fájlban, WAL-naplózással). Soha ne írjon nyers SQL-t útvonalakba vagy kezelőkbe — használja ezeket a modulokat.

Forrás: diagrams/db-schema-overview.mmd

Tartománymodulok (mindegyik egy vagy több táblát kezel): 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.

A migrations/ 168 verziózott .sql fájlt tartalmaz (idempotens, tranzakciós), amelyeket a migrationRunner.ts hajt végre rendszerindításkor.

A migrációk során létrehozott táblák (összesen 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 (valamint FTS5 virtuális táblák a memóriában történő kereséshez).

3.3 src/domain/ — Tartományi réteg

Tiszta üzleti logika, I/O nélkül. Az útvonalak és kezelők importálják.

Fájl	Rendeltetés
policyEngine.ts	Legfelső szintű házirend-feloldó
fallbackPolicy.ts	Tartalékmegoldási döntési fa
costRules.ts	Költségszámítási szabályok
lockoutPolicy.ts	Modellkizárási döntések
tagRouter.ts	Címkealapú útválasztás
comboResolver.ts	Kombináció feloldása a kérésből → céllistává
connectionModelRules.ts	Kapcsolatonkénti modellszűrők
modelAvailability.ts	Modell elérhetőségének ellenőrzése
degradation.ts	Csökkentett funkcionalitású mód átmenetei
providerExpiration.ts	Lejárt fiókok/kulcsok észlelése
quotaCache.ts	Gyorsítótárazott kvótadöntések
responses.ts, omnirouteResponseMeta.ts	A válaszstruktúrákat segítő elemek
configAudit.ts	Konfigurációmódosítások auditálása
assessment/	Modellértékelés (az RFC szerint, részlegesen megvalósítva)
types.ts	Megosztott tartománytípusok

3.4 src/server/ — Kizárólag szerveroldali

Nem importálható klienskomponensekből.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Nyilvános vagy felügyeleti útvonalak osztályozása
│   ├── assertAuth.ts      Segédfüggvény helyességi feltételek ellenőrzéséhez
│   ├── context.ts         Kérésenkénti hitelesítési kontextus
│   ├── headers.ts
│   ├── pipeline.ts        Hitelesítési feldolgozási lánc
│   ├── policies/          Konkrét házirendek
│   └── types.ts
└── cors/origins.ts        Engedélyezett CORS-források listája

3.5 src/shared/ — Biztonságosan megosztható

Célzott alkönyvtárakra felosztva:

• constants/ — providers.ts (Zod által validált szolgáltatókatalógus), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (tiltólista), 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-séma), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — az npm-en közzétett nyilvános API-szerződések.
• types/ — megosztott TS-típusok.
• 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, valamint vezérlőpulti hookok/komponensek a services/, network/, middleware/, schemas/, hooks/, components/ alatt.

---

4. open-sse/ — Streamelési motor munkaterülete

Különálló npm-munkaterület, amely @omniroute/open-sse néven van közzétéve. Ez felel a kérések feldolgozásáért, a végrehajtókért, a fordítókért, a szolgáltatásokért, az átalakítóért és az MCP-kiszolgálóért.

open-sse/
├── index.ts                Nyilvános exportok
├── package.json            Munkaterület-manifeszt
├── tsconfig.json
├── types.d.ts
├── config/                 Szolgáltatói nyilvántartások, fejlécprofilok, identitás, …
├── handlers/               Kéréskezelők (csevegés, beágyazások, hang, kép, …)
├── executors/              108 szolgáltatóspecifikus HTTP-végrehajtó
├── translator/             Formátumkonverzió (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions streamátalakító
├── services/               Több mint 80 szolgáltatásmodul (kombinációk, tartalék útvonalak, kvóták, identitás, …)
├── utils/                  Streamelési segédeszközök, TLS-kliens, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP-kiszolgáló (3 átviteli mód, 33 hatókör, 110 eszköz)

4.1 open-sse/handlers/

Kezelő	Rendeltetés
chatCore.ts	Fő csevegési folyamat (gyorsítótár, sebességkorlátozás, kombinált útválasztás, végrehajtó indítása)
responsesHandler.ts	Az OpenAI Responses API belépési pontja
embeddings.ts	Beágyazások
imageGeneration.ts	Képgenerálás
audioSpeech.ts	Szöveg beszéddé alakítása
audioTranscription.ts	Beszéd szöveggé alakítása
videoGeneration.ts	Videógenerálás
musicGeneration.ts	Zenegenerálás
rerank.ts	Újrarangsorolás
moderations.ts	Moderálás
search.ts	Webes keresés
sseParser.ts	SSE-eseményelemző
usageExtractor.ts	Tokenszámok kinyerése a felsőbb szintű streamekből
responseSanitizer.ts	Szolgáltatóspecifikus zaj eltávolítása
responseTranslator.ts	Kapcsolóréteg a szolgáltatói válasz és a fordítási réteg között

4.2 open-sse/executors/

108 szolgáltatói végrehajtó, amelyek mindegyike a BaseExecutor (base.ts) osztályt bővíti:

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, továbbá a claudeIdentity.ts (megosztott identitássegéd) és az index.ts (nyilvántartás).

Megjegyzés: az itt nem felsorolt szolgáltatókat a default.ts szolgálja ki az általános, OpenAI-kompatibilis végrehajtó használatával. A teljes szolgáltatói katalógus (355 szolgáltató) a src/shared/constants/providers.ts fájlban található.

4.3 open-sse/translator/

Központi és küllős fordítási modell (a központ az OpenAI).

• 9 kérésfordító (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 válaszfordító (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 segédmodul (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, valamint segédmodultesztek.
• Képkezelő segédmodulok (translator/image/sizeMapper.ts).
• Felső szint: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — TransformStream-alapú Responses API ↔ Chat Completions átalakító (a responses/ útvonal minden egyéb esetet kezelő ágában használatos).

4.5 open-sse/services/

Kiemelt elemek (a teljes lista az open-sse/services/ alatt található):

Terület	Fájlok
Kombinált útválasztás	combo.ts (19 stratégia), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Automatikus Combo-motor	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
Hibatűrés	accountFallback.ts (lehűlési idő + zárolás), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Kvóták	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Gyorsítótárazás	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Intelligens útválasztás	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Modellkezelés	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Tömörítés	compression/ — a teljes tömörítőmotor bekötése
Tokenek + munkamenetek	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Szint / manifeszt	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / hálózat	ipFilter.ts, webSearchFallback.ts
Kötegek	batchProcessor.ts
Használat	usage.ts

4.6 open-sse/mcp-server/

• 110 egyedi eszköz van bekötve a server.ts fájlban (45 kanonikus a schemas/tools.ts fájlban + memória-, készség-, GitHub-készség-, készlet-, játékosítási, bővítmény-, Notion-, Obsidian-, helyi korpusz- és tömörítési modulok — az uniót a countUniqueMcpTools számolja).
• 3 átviteli mód: stdio, HTTP Streamable, SSE.
• 33 hatókör van futásidőben kikényszerítve — az alaplista a src/shared/constants/mcpScopes.ts fájlban található, a teljes készlet pedig az egyes eszközmodulok által deklarált hatókörök uniója.
• Auditnapló-tábla: mcp_tool_audit (az audit.ts tölti fel).
• Fájlok: 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, valamint tesztek a __tests__/ alatt.
• A teljes eszközkatalógust lásd az MCP-SERVER.md dokumentumban.

4.7 open-sse/config/

Szolgáltatói nyilvántartások (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), formátumonkénti modellnyilvántartások (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), identitássegédletek (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), hitelesítőadat-segédletek (credentialLoader.ts, codexClient.ts) és felhőadapterek (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/

Streamelési primitívek és szolgáltatói segédfüggvények: 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/ — Asztali burkolóalkalmazás

electron/
├── main.js                  Electron főfolyamat
├── preload.js               Előtöltési híd (contextIsolation engedélyezve)
├── types.d.ts
├── package.json             electron-builder konfiguráció, 3.8.51-es verzió
├── README.md
├── assets/                  Buildelési erőforrások (ikonok, jogosultságok, …)
├── node_modules/            Dedikált node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Buildelési kimenet (nincs verziókezelésbe beküldve)

Öt npm-szkript található a munkaterület gyökerében: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Az automatikus frissítést az electron-updater végzi, amely a GitHub kiadási hírcsatornájára mutat.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Fő CLI-belépési pont (Node ESM)
├── reset-password.mjs      A felügyeleti jelszó visszaállítása CLI-ből
├── mcp-server.mjs          MCP-kiszolgáló indítója (stdio)
├── nodeRuntimeSupport.mjs  Node-verzióellenőrzés
└── cli/
    ├── program.mjs         Commander-program összeállítója
    ├── runtime.mjs         withRuntime segéd (először kiszolgáló/adatbázis tartalékként)
    ├── output.mjs          Kimenetformázók (json/jsonl/table/csv)
    ├── i18n.mjs            t() segéd lokalizációkkal
    ├── api.mjs             API-lekérési segéd
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Parancsregisztráció
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (parancsonként/csoportonként egy fájl)

A package.json → bin alatt két bináris van elérhetővé téve:

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

---

7. tests/

Könyvtár	Típus
tests/unit/	Egységtesztek a Node natív tesztfuttatójával (1821 fájl, valamint api/, auth/, authz/ alkönyvtárak)
tests/integration/	Modulok közötti és adatbázis-állapotot vizsgáló tesztek
tests/e2e/	Playwright felhasználóifelület-tesztek
tests/e2e/protocol-clients.test.ts	MCP/A2A protokollok teljes folyamatot lefedő tesztjei
tests/translator/	Fordítóspecifikus tesztek
tests/security/	Biztonsági regressziós tesztek
tests/load/	Terhelési/stressztesztek
tests/golden-set/	Referenciakimenetek a fordító regressziós tesztjeihez
tests/helpers/, tests/fixtures/, tests/manual/	Támogató segédanyagok

Gyakori parancsok:

Parancs	Mit futtat
npm run test:unit	Az összes tests/unit/*.test.ts fájl a Node tesztfuttatójával (10-es párhuzamosság)
npm run test:vitest	Vitest tesztcsomag (MCP, autoCombo, gyorsítótár)
npm run test:e2e	Playwright felhasználóifelület-tesztcsomag
npm run test:protocols:e2e	MCP + A2A protokollok teljes folyamatot lefedő tesztjei
npm run test:coverage	Lefedettségi küszöb (≥60% sorok/utasítások/függvények/elágazások)
node --import tsx/esm --test tests/unit/<file>.test.ts	Egyetlen fájl futtatása

---

8. scripts/

Rendeltetés szerint 6 almappába rendezve.

• 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. Kérésfeldolgozási folyamat (összefoglaló)

Forrás: diagrams/request-pipeline.mmd

Ügyfélkérés
  → /v1/chat/completions (route.ts)
     CORS előzetes ellenőrzése
     Zod-validáció (chatCompletionsSchema a shared/validation/schemas.ts fájlban)
     Hitelesítés (extractApiKey + isValidApiKey VAGY requireManagementAuth)
     Házirendmotor (src/server/authz/pipeline.ts)
     Védelmi korlátok (PII-maszkoló, promptinjektálás elleni védelem, képfeldolgozási híd)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Gyorsítótár ellenőrzése (szemantikai + olvasási gyorsítótár)
     Sebességkorlátozás (rateLimitManager, accountSemaphore)
     Kombinált útválasztás (ha a modell egy kombinációra oldódik fel)
       comboResolver → ciklus célpontonként → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       lekérés a felsőbb szintű szolgáltatástól → újrapróbálkozás/exponenciális várakozás az accountFallback használatával
     translateResponse() (open-sse/translator/response/*)
     SSE-adatfolyam VAGY JSON-válasz
     Responses API esetén: TransformStream az open-sse/transformer/responsesTransformer.ts használatával
  → Megfelelőségi audit (src/lib/compliance/)
  → Válasz az ügyfélnek

A reziliencia futásidejű állapota (három mechanizmus)

Mechanizmus	Hatókör	Hely
Szolgáltatói áramkör-megszakító	Teljes szolgáltató	src/shared/utils/circuitBreaker.ts, a domain_circuit_breakers tárolóban megőrizve
Kapcsolati várakozási idő	Egy fiók/kulcs	markAccountUnavailable() az src/sse/services/auth.ts fájlban; az accountFallback.checkFallbackError() használja
Modellzárolás	Szolgáltató + kapcsolat + modell	open-sse/services/accountFallback.ts, a domain_lockout_state tárolóban megőrizve

Lásd a RESILIENCE_GUIDE.md fájlt és a CLAUDE.md erre kijelölt szakaszát.

---

10. Hogyan járulhatsz hozzá

Új szolgáltató hozzáadása

1. Regisztráld a src/shared/constants/providers.ts fájlban (betöltéskor Zod-validáció történik).
2. Ha egyéni logika szükséges, adj hozzá egy végrehajtót az open-sse/executors/ könyvtárban (a BaseExecutor kiterjesztésével).
3. Ha nem az OpenAI-formátumot használja, adj hozzá egy fordítót az open-sse/translator/ könyvtárban.
4. OAuth-alapú szolgáltató esetén adj hozzá konfigurációt a src/lib/oauth/providers/ és a src/lib/oauth/services/ könyvtárban.
5. Regisztráld a modelleket az open-sse/config/providerRegistry.ts fájlban (vagy a formátumspecifikus regisztrációs fájlban az open-sse/config/ alatt).
6. Írj teszteket a tests/unit/ könyvtárban.

Új API-útvonal hozzáadása

1. Hozd létre a src/app/api/your-route/route.ts fájlt.
2. Kövesd ezt a mintát: CORS → a törzs Zod-validációja → hitelesítés → delegálás a kezelőnek.
3. Új kérésstruktúra esetén add hozzá a Zod-sémát a src/shared/validation/schemas.ts fájlban.
4. Ha csak felügyeleti célú: add hozzá az elérési utat a src/shared/constants/publicApiRoutes.ts fájlhoz (a nyilvános API-felület tiltólistája).
5. Adj hozzá teszteket a tests/unit/ könyvtárban.
6. Frissítsd a docs/reference/API_REFERENCE.md és a docs/openapi.yaml fájlt.

Új DB-modul hozzáadása

1. Hozd létre a src/lib/db/yourModule.ts fájlt, és importáld a getDbInstance() függvényt a ./core.ts fájlból.
2. Exportáld a domainedhez tartozó CRUD-függvényeket.
3. Új táblák esetén adj hozzá egy migrációt a src/lib/db/migrations/ könyvtárban, szekvenciális sorszámozással, idempotens és tranzakciós módon.
4. Az importálók közvetlen importokat használnak az @/lib/db/yourModule modulból (nincs gyűjtőmodul — a régi localDb.ts újraexportálási réteget eltávolítottuk).
5. Adj hozzá teszteket a tests/unit/ könyvtárban.

Új MCP-eszköz hozzáadása

1. Add hozzá az eszköz definícióját az open-sse/mcp-server/tools/ könyvtárban (vagy bővítsd az open-sse/mcp-server/schemas/tools.ts fájlt).
2. Rendeld hozzá a megfelelő hatókör(öke)t a src/shared/constants/mcpScopes.ts fájlban.
3. Regisztráld az eszközt az open-sse/mcp-server/server.ts fájlban.
4. Adj hozzá teszteket az open-sse/mcp-server/__tests__/ könyvtárban.
5. Frissítsd az MCP-SERVER.md fájlt.

Új A2A-képesség hozzáadása

Lásd: A2A-SERVER.md § Új képesség hozzáadása. A képességek a src/lib/a2a/skills/ könyvtárban találhatók, és az A2A-feladatkezelőn keresztül vannak regisztrálva.

---

11. Konvenciók

• Kódstílus: 2 szóközös behúzás, dupla idézőjelek, 100 karakteres sorhossz, pontosvesszők, es5 záróvesszők — a Prettier kényszeríti ki a lint-staged segítségével.
• Importok: külső → belső (@/, @omniroute/open-sse) → relatív.
• Elnevezés: fájloknál camelCase vagy kebab-case, komponenseknél PascalCase, konstansoknál UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error mindenhol; no-explicit-any = warn az open-sse/ és a tests/ könyvtárban, máshol error.
• TypeScript: strict: false (örökölt beállítás). A modulok közötti határokon részesítsd előnyben az explicit típusokat a típuskövetkeztetéssel szemben.
• Adatbázis: soha ne írj nyers SQL-t útvonalakba vagy kezelőkbe — mindig a src/lib/db/ moduljait használd. Soha ne importálj gyűjtőmodulból — közvetlenül az egyes src/lib/db/* modulokat használd.
• DB-entitások tipizálása (#3512): egy DB-tábla sorstruktúráját író vagy olvasó függvény egy elnevezett TS-interfészt fogadjon/adjon vissza, amely 1:1 arányban tükrözi az adott tábla oszlopait, ne pedig any típust vagy a hívás helyén megadott névtelen beágyazott típust. Helyezd az interfészt a függvény mellé (például export interface UsageEntry a src/lib/usage/usageHistory.ts fájlban, a saveRequestUsage fölött), az egyes mezők maradjanak opcionálisak/null értékűek, ha a különböző írók fokozatosan töltik fel a sort, és részesítsd előnyben az unknown típust az any típussal szemben, ha egy mező struktúrája hívónként változik (ezt dokumentáld a mezőnél, például a UsageEntry.tokens a szolgáltató nyers használati struktúráját és a normalizált struktúrát is elfogadja). Ha egy fájl any-előfordulásainak száma így eléri a nullát, add hozzá a check:any-budget:t11 engedélyezési listájához (scripts/check/check-t11-any-budget.mjs, maxAny: 0), hogy ne történhessen visszalépés. Ez egy első részletre vonatkozó konvenció — a névtelen any típusok átfogó eltávolítása iteratívan történik a kódbázis többi részében.
• Hibák: használj try/catch blokkot konkrét hibatípusokkal, és naplózz pino-kontextussal. Az SSE-adatfolyamokban soha ne nyeld el csendben a hibákat; a tisztításhoz használj megszakítási jeleket.
• Biztonság: soha ne használj eval() / new Function() / közvetett eval funkciót. Minden bemenetet validálj Zoddal. A hitelesítő adatokat titkosítva tárold (AES-256-GCM). Tartsd összhangban a src/shared/constants/upstreamHeaders.ts tiltólistáját a tisztítási/validációs réteggel.
• Commitok: Conventional Commits — feat(scope): subject. Engedélyezett hatókörök: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Ágak: előtagok: feat/, fix/, refactor/, docs/, test/, chore/. Soha ne commitolj közvetlenül a main ágba.
• Husky: a pre-commit futtatja a lint-staged + check:docs-sync + check:any-budget:t11 feladatokat; a pre-push futtatja a check:any-budget:t11 + check:tracked-artifacts feladatokat (gyors ellenőrzőkapuk; a test:unit nincs köztük).

---

12. Szigorú szabályok (a CLAUDE.md alapján)

1. Soha ne véglegesíts titkokat vagy hitelesítő adatokat.
2. Soha ne használj gyűjtőimportot — közvetlenül a megfelelő src/lib/db/* modulokat használd.
3. Soha ne használd az eval() / new Function() függvényeket vagy az implicit evalt.
4. Soha ne véglegesíts közvetlenül a main ágra.
5. Soha ne írj nyers SQL-t az útvonalakban — mindig a src/lib/db/ modulokon keresztül végezd a műveleteket.
6. Soha ne nyeld el észrevétlenül a hibákat az SSE-adatfolyamokban.
7. Mindig Zod-sémákkal validáld a bemeneteket.
8. Az éles kód módosításakor mindig mellékelj teszteket.
9. A lefedettségnek ≥ 60%-on kell maradnia (utasítások, sorok, függvények, elágazások).

---

13. Lásd még

• ARCHITECTURE.md — magas szintű architektúra és a modulok felelősségi körei.
• API_REFERENCE.md — a nyilvános és felügyeleti API referenciája.
• FEATURES.md — funkciómátrix és a verziók főbb újdonságai.
• RESILIENCE_GUIDE.md — a megszakító, a várakozási idő és a kizárás részletes ismertetése.
• AUTO-COMBO.md — az Auto Combo pontozása és stratégiái.
• MCP-SERVER.md — az MCP-eszközök teljes katalógusa és az átviteli módok.
• A2A-SERVER.md — az A2A protokoll képességei és felderítése.
• COMPRESSION_GUIDE.md — RTK- és Caveman-tömörítés.
• CLI-TOOLS.md — CLI-integrációk.
• ELECTRON_GUIDE.md (ha elérhető), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — telepítési célkörnyezetek.
• TROUBLESHOOTING.md — gyakori üzemeltetési problémák.
• CONTRIBUTING.md — közreműködői munkafolyamat.
• CLAUDE.md — a Claude Code adattárra vonatkozó szabályai (a fenti konvenciók jelentős részének mérvadó forrása).
• AGENTS.md — az ügynökök által használt részletesebb architektúra-referencia.