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

OmniRoute Codebase Documentation (Български)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇩 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 · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Версия: v3.8.51 Последно актуализирано: 2026-06-28 Аудитория: Инженери, които допринасят към OmniRoute или изграждат интеграции върху него.

За архитектурни диаграми на високо ниво и обосновката зад всяка подсистема прочетете ARCHITECTURE.md. За задълбочена информация относно отделните подсистеми (Auto Combo, MCP сървър, A2A сървър, Skills, Memory, Cloud Agents, Resilience, Compression и др.) вижте предназначените за тях файлове в тази директория docs/.

Този файл описва какво съществува в хранилището в момента, така че нов инженер да може да се ориентира в дървото, да разбере слоевете по време на изпълнение и да знае къде да добавя код, без да създава нови модули.

---

1. Технологичен стек

Аспект	Избор
Уеб рамка	Next.js 16 (App Router, самостоятелен изход, без глобален междинен софтуер)
Език	TypeScript 6.0+ — цел ES2022, module: esnext, moduleResolution: bundler, strict: false
Среда за изпълнение	Node.js >=22.22.2 <23 или >=24.0.0 <27 (наложено чрез engines + SUPPORTED_NODE_RANGE)
База данни	SQLite чрез better-sqlite3 (единичен екземпляр, WAL журнал)
Настолно приложение	Electron 41 + electron-builder 26.10 (отделно работно пространство в electron/)
Тестове	Вграден инструмент за тестове на Node (модулни/интеграционни), Vitest (MCP, autoCombo, кеш), Playwright (e2e + protocols-e2e)
Компилиране	Самостоятелна версия на Next.js чрез scripts/build/build-next-isolated.mjs
Проверка/форматиране	Плоска конфигурация на ESLint + Prettier (lint-staged чрез Husky pre-commit)
Модулна система	ESM навсякъде ("type": "module")
Работни пространства	npm работно пространство — open-sse е единственото подработно пространство

Псевдоними на пътища (tsconfig.json):

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

HTTP порт по подразбиране: 20128 (API и таблото за управление използват един и същ процес). Директорията за данни се задава чрез променливата на средата DATA_DIR, като стойността по подразбиране е ~/.omniroute/.

---

2. Структура на хранилището

OmniRoute/
├── src/                  Next.js приложение (App Router, библиотеки, домейн, сървър, споделени компоненти)
├── open-sse/             Работно пространство на системата за поточно предаване (@omniroute/open-sse)
├── electron/             Обвивка за настолното приложение (основен процес на Electron 41 + preload)
├── bin/                  Входни точки на CLI (omniroute, reset-password)
├── tests/                Модулни, интеграционни, e2e, protocols-e2e, преводачески, защитни тестове и фикстури
├── scripts/              Помощни скриптове за компилиране, синхронизиране, проверки, миграция и изпълнение
├── docs/                 Публична документация (тази директория)
├── public/               Статични ресурси, PWA манифест, service worker
├── config/               Примерни конфигурации за изпълнение
├── images/               Маркетингови ресурси/екранни снимки
├── _ideia/, _references/, _mono_repo/, _tasks/   Вътрешни чернови/планиране (не се доставят)
├── CLAUDE.md             Правила на хранилището за Claude Code
├── AGENTS.md             По-задълбочен архитектурен справочник за агенти
├── package.json          v3.8.51, корен на работното пространство
└── tsconfig.json         Псевдоними на пътища + основни опции на компилатора

---

3. src/ — Next.js приложение

src/
├── app/                  Страници на App Router + API маршрути
├── lib/                  Основни библиотеки (БД, удостоверяване, OAuth, умения, памет, …)
├── domain/               Чист домейнен слой (политики, резервни механизми, разходи, блокиране, …)
├── server/               Модули само за сървъра (оторизация, CORS, удостоверяване)
├── shared/               Типове, константи, валидиране, договори, помощни функции (безопасни за използване през различни граници)
├── mitm/                 Помощни средства за прокси тип „човек по средата“ за CLI интеграция
├── models/               Метаданни/псевдоними на локални модели
├── sse/                  Остарели SSE обработчици, които все още се намират в src/ (не в open-sse/)
├── store/                Хранилища за състояние от клиентската страна
├── middleware/           Помощни средства за междинен софтуер на ниво маршрут (не глобален междинен софтуер на Next.js)
├── scripts/              Скриптове в дървото, които могат да се импортират от кода на приложението
├── types/                Глобални и споделени TS типове
├── i18n/                 Пакети за локализация
├── instrumentation.ts    Инструментационна кука на Next.js
├── instrumentation-node.ts
└── proxy.ts              Помощен модул от най-високо ниво за инициализиране на прокси

3.1 src/app/ — App Router

App Router предоставя както потребителския интерфейс на таблото, така и публичния/административния HTTP API. Няма глобален междинен софтуер — прихващането се извършва за всеки маршрут поотделно.

Сегменти от най-високо ниво в src/app/:

Път	Предназначение
api/	Всички HTTP API маршрути (вижте разбивката по-долу)
a2a/	A2A JSON-RPC 2.0 крайна точка (POST /a2a)
.well-known/agent.json/	Документ за откриване на A2A Agent Card
(dashboard)/	Потребителски интерфейс на таблото (група маршрути, без URL префикс)
auth/, login/, forgot-password/, callback/	Потоци за удостоверяване
landing/	Маркетингова/целева страница
docs/	Вграден преглед на API документацията
status/, maintenance/, offline/	Оперативни страници
privacy/, terms/	Правни страници
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Статични страници за грешки
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Граници на рамката за грешки/зареждане
layout.tsx, page.tsx, globals.css, manifest.ts	Основна обвивка

3.1.1 src/app/(dashboard)/dashboard/ — Страници на потребителския интерфейс

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, както и кореновите page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — API групи от най-високо ниво

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/   Управление на вградени услуги (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Публичен API, съвместим с OpenAI
├── v1beta/     Съвместимост в стил Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Управление на вградени услуги

Маршрути за инсталиране, стартиране, спиране и наблюдение на 9Router и CLIProxyAPI. Всички пътища са класифицирани като LOCAL_ONLY (само loopback, строго правило №17), защото могат да изпълняват npm install и да стартират дъщерни процеси.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             помощна функция getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install чрез execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install на по-нова версия
│   ├── rotate-key/route.ts POST — генериране на нов API ключ + рестартиране
│   ├── status/route.ts     GET  — текущо състояние + състояние в БД + метаданни за версията
│   └── auto-start/route.ts POST — превключване на флага auto_start
├── cliproxy/
│   ├── _lib.ts             помощна функция getOrInitSupervisor()
│   ├── 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 — npm install на по-нова версия
│   ├── status/route.ts     GET  — текущо състояние + състояние в БД + метаданни за версията
│   └── auto-start/route.ts POST — превключване на флага auto_start
└── [name]/
    └── logs/route.ts       GET  — SSE поток от последните записи в дневника (споделен от всички услуги)

Съответният потребителски интерфейс на таблото: src/app/(dashboard)/dashboard/providers/services/ — страница с два раздела (CLIProxyAPI + 9Router). Обратен прокси сървър за вградения потребителски интерфейс на 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Подробен преглед: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — публичен API, съвместим с OpenAI

v1/
├── accounts/[id]/                       извличане на акаунт
├── agents/tasks/[id]/, agents/tasks/    крайни точки за задачи в стил A2A
├── api/                                 вътрешни помощни функции за API, достъпни под v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    чат довършвания (основната крайна точка)
├── completions/                         остарели текстови довършвания
├── embeddings/                          векторни представяния
├── files/[id]/, files/                  API за файлове
├── _helpers/                            споделени помощни функции за маршрутите (без публичен URL)
├── images/{edits, generations}/         генериране + редактиране на изображения
├── issues/                              помощни крайни точки за сортиране на проблеми
├── management/{proxies}/                маршрути с обхват за управление във v1
├── messages/{count_tokens}/             съвместимост със съобщения в стил Anthropic
├── models/                              списък с модели (`route.ts`, `catalog.ts`)
├── moderations/                         модериране
├── music/                               генериране на музика
├── providers/[provider]/                операции за отделните доставчици
├── quotas/{check}                       проверки на квоти
├── registered-keys/                     администриране на регистрирани ключове
├── rerank/                              повторно класиране
├── responses/[...path]/                 OpenAI Responses API (прихваща всички маршрути)
├── search/                              търсене в мрежата
├── videos/                              генериране на видео
├── ws/                                  WebSocket мост
└── route.ts                             обработчик на индекса

Всеки файл с маршрут следва един и същ шаблон:

Маршрут → предварителна CORS заявка → валидиране на тялото със Zod → незадължително удостоверяване
        → прилагане на правилата за API ключове → делегиране към обработчик (open-sse)

v1beta/ е интерфейсът за съвместимост в стил Gemini (тънка обвивка, която преобразува към същия конвейер open-sse/handlers/).

3.2 src/lib/ — Основни библиотеки

Винаги импортирайте данни, синхронизация, OAuth, умения, памет и т.н. чрез тези модули. Таблицата групира действителните директории и важните файлове от най-горно ниво.

Модул	Предназначение
a2a/	Сървър за A2A протокола: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 умения: анализ на разходите, отчет за състоянието, откриване на доставчици, управление на квоти, интелигентно маршрутизиране, изброяване на възможностите)
acp/	Протокол за управление на агенти: index.ts, manager.ts, registry.ts
api/	Помощни компоненти за вътрешния API: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (нулиране/хеширане на пароли)
batches/	Услуга за OpenAI Batches API (service.ts)
catalog/	Синхронизиране на каталога на OpenRouter (openrouterCatalog.ts)
cloudAgent/	Регистър на облачни агенти: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Помощни компоненти за разрешаване на комбинации
compliance/	Одит + одит на доставчици: index.ts, providerAudit.ts
config/	Свързващ слой за конфигурацията по време на изпълнение
db/	Домейн модули за SQLite (вижте §3.2.1)
display/	Помощни компоненти за потребителския интерфейс/визуализацията, използвани от API отговорите
embeddings/	Регистър на услуги за векторни представяния
env/	Зареждане + проверка на средата
evals/	Среда за изпълнение на оценки
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Фонови задачи (autoUpdate.ts, …)
memory/	Постоянна памет: 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/импортиране на доставчици (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, плюс services/, utils/ и constants/oauth.ts
plugins/	Зареждащ модул за приставки (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Управляван жизнен цикъл на моделите: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Помощни компоненти за доставчици: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — настройки за прекъсвач на веригата, период на изчакване и блокиране
runtime/	Откриване на функционалности по време на изпълнение
search/	executeWebSearch.ts
services/	Рамка за вградени услуги: ServiceSupervisor.ts (универсален надзорник на дъщерни процеси със заключване на операции, пръстеновиден буфер и проверка на състоянието), bootstrap.ts (регистрация на ниво процес и автоматично стартиране), registry.ts (съпоставяне инструмент → надзорник), apiKey.ts (хранилище за ключове с AES-256-GCM), modelSync.ts (периодично синхронизиране на модели), ringBuffer.ts (5 MB кръгов буфер за регистрационни съобщения), healthCheck.ts (HTTP проверка на състоянието), types.ts, embedWsProxy.ts (WebSocket прокси), installers/{ninerouter,cliproxy}.ts. Вижте docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Каталог + генератор на умения за агенти: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → записва skills/{id}/SKILL.md), openapiParser.ts (извлича REST крайни точки от OpenAPI спецификация), cliRegistryParser.ts (извлича CLI подкоманди от bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Използва се от REST маршрутите (/api/agent-skills/*), MCP инструментите (omniroute_agent_skills_*) и A2A умението list-capabilities. Вижте AGENT-SKILLS.md.
skills/	Рамка за умения: 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, плюс builtin/browser.ts
spend/	batchWriter.ts (буфер за отложен запис)
sync/	bundle.ts, tokens.ts (облачно синхронизиране)
system/	Помощни компоненти на системно ниво
translator/	Свързващ слой на транслатора от най-високо ниво (делегира към open-sse/translator/)
usage/	Отчитане на използването: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Автоматично актуализиране + манифест на версиите
ws/	WebSocket мост
zed-oauth/	OAuth поток за редактора Zed

Файлове от най-горно ниво в src/lib/:

• Старият обобщаващ модул localDb.ts беше премахнат — потребителите импортират конкретни модули от src/lib/db/* директно.
• 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/

Единична SQLite база данни (getDbInstance() в core.ts, журнален режим WAL). Никога не пишете необработен SQL в маршрути или обработчици — използвайте тези модули.

Източник: diagrams/db-schema-overview.mmd

Домейн модули (всеки управлява една или повече таблици): 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/ съдържа 168 версионирани .sql файла (идемпотентни, транзакционни) и се изпълнява от migrationRunner.ts при стартиране.

Таблици, създадени от миграциите (общо 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 (плюс виртуални FTS5 таблици за търсене в паметта).

3.3 src/domain/ — Домейн слой

Чиста бизнес логика без входно-изходни операции. Импортира се от маршрути и обработчици.

Файл	Предназначение
policyEngine.ts	Основен механизъм за определяне на политики
fallbackPolicy.ts	Дърво за вземане на решения при резервно превключване
costRules.ts	Правила за изчисляване на разходите
lockoutPolicy.ts	Решения за блокиране на модели
tagRouter.ts	Маршрутизиране въз основа на етикети
comboResolver.ts	Определяне на комбинация от заявка → списък с цели
connectionModelRules.ts	Филтри за модели за всяка връзка
modelAvailability.ts	Проверка на наличността на модели
degradation.ts	Преходи към режим с влошена функционалност
providerExpiration.ts	Откриване на изтекъл акаунт/ключ
quotaCache.ts	Кеширани решения за квоти
responses.ts, omnirouteResponseMeta.ts	Помощни функции за структурата на отговорите
configAudit.ts	Одит на промените в конфигурацията
assessment/	Оценка на модели (съгласно RFC, частично реализирана)
types.ts	Споделени домейн типове

3.4 src/server/ — Само за сървъра

Не може да се импортира от клиентски компоненти.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Класифицира маршрутите като публични или административни
│   ├── assertAuth.ts      Помощна функция за проверки
│   ├── context.ts         Контекст за оторизация за всяка заявка
│   ├── headers.ts
│   ├── pipeline.ts        Последователност за оторизация
│   ├── policies/          Конкретни политики
│   └── types.ts
└── cors/origins.ts        Списък с разрешени CORS източници

3.5 src/shared/ — Безопасно за споделяне

Разделено на специализирани поддиректории:

• constants/ — providers.ts (каталог на доставчици, валидиран чрез Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (списък със забранени стойности), 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 схеми), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — публични API договори, публикувани в npm.
• types/ — споделени TS типове.
• 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, както и hooks/компоненти за таблото за управление в services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Работно пространство на стрийминг енджина

Отделно npm работно пространство, публикувано като @omniroute/open-sse. Отговаря за обработката на заявки, изпълнителите, транслаторите, услугите, трансформатора и MCP сървъра.

open-sse/
├── index.ts                Публични експорти
├── package.json            Манифест на работното пространство
├── tsconfig.json
├── types.d.ts
├── config/                 Регистри на доставчици, профили на заглавки, идентичност, …
├── handlers/               Обработчици на заявки (чат, вграждания, аудио, изображения, …)
├── executors/              108 специфични за доставчиците HTTP изпълнители
├── translator/             Преобразуване на формати (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Трансформатор на потоци Responses API ↔ Chat Completions
├── services/               Над 80 модула за услуги (комбинации, резервни варианти, квоти, идентичност, …)
├── utils/                  Помощни инструменти за стрийминг, TLS клиент, AWS SigV4, прокси извличане, …
└── mcp-server/             MCP сървър (3 транспорта, 33 обхвата, 110 инструмента)

4.1 open-sse/handlers/

Обработчик	Предназначение
chatCore.ts	Основен чат конвейер (кеш, ограничаване на честотата, комбинирано маршрутизиране, диспечиране към изпълнител)
responsesHandler.ts	Входна точка на OpenAI Responses API
embeddings.ts	Векторни представяния
imageGeneration.ts	Генериране на изображения
audioSpeech.ts	Преобразуване на текст в реч
audioTranscription.ts	Преобразуване на реч в текст
videoGeneration.ts	Генериране на видео
musicGeneration.ts	Генериране на музика
rerank.ts	Пренареждане
moderations.ts	Модериране
search.ts	Търсене в уеб
sseParser.ts	Парсър за SSE събития
usageExtractor.ts	Извличане на броя токени от потоци от външни доставчици
responseSanitizer.ts	Премахване на специфичен за доставчика шум
responseTranslator.ts	Свързващ слой между отговора на доставчика и слоя за транслиране

4.2 open-sse/executors/

108 изпълнители за доставчици, всеки от които разширява 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, както и claudeIdentity.ts (споделен помощен модул за идентичност) и index.ts (регистър).

Забележка: доставчиците, които не са изброени тук, се обслужват от default.ts чрез общия изпълнител, съвместим с OpenAI. Пълният каталог на доставчиците (355 доставчици) се намира в src/shared/constants/providers.ts.

4.3 open-sse/translator/

Транслиране по модела „център и лъчи“ (OpenAI е центърът).

• 9 транслатора на заявки (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 транслатора на отговори (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 помощни модула (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, както и тестове на помощните модули.
• Помощни модули за изображения (translator/image/sizeMapper.ts).
• На най-горно ниво: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — базиран на TransformStream конвертор между Responses API ↔ Chat Completions (използван от универсалния маршрут responses/).

4.5 open-sse/services/

Основни компоненти (пълният списък е в open-sse/services/):

Област	Файлове
Комбинирано маршрутизиране	combo.ts (19 стратегии), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Автоматичен комбиниран механизъм	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
Устойчивост	accountFallback.ts (период на изчакване + блокиране), errorClassifier.ts, requestRejectedStreak.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Квоти	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Кеширане	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Интелигентно маршрутизиране	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Обработка на модели	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Компресиране	compression/ — цялостно свързване на механизма за компресиране
Токени + сесии	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Ниво / манифест	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / мрежа	ipFilter.ts, webSearchFallback.ts
Пакетна обработка	batchProcessor.ts
Използване	usage.ts

4.6 open-sse/mcp-server/

• 110 уникални инструмента, свързани в server.ts (45 канонични в schemas/tools.ts + модули за памет, умения, GitHub умения, пул, геймификация, плъгини, Notion, Obsidian, локален корпус и компресиране — обединението е преброено чрез countUniqueMcpTools).
• 3 транспорта: stdio, HTTP Streamable, SSE.
• 33 обхвата, прилагани по време на изпълнение — базовият списък е в src/shared/constants/mcpScopes.ts, а пълният набор е обединението от обхватите, декларирани от всеки модул с инструменти.
• Таблица за одит: mcp_tool_audit (попълва се от audit.ts).
• Файлове: 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, плюс тестове в __tests__/.
• Вижте MCP-SERVER.md за пълния каталог с инструменти.

4.7 open-sse/config/

Регистри на доставчици (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), регистри на модели по формат (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), помощни компоненти за идентичност (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), помощни компоненти за идентификационни данни (credentialLoader.ts, codexClient.ts) и облачни адаптери (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/

Примитиви за поточно предаване и помощни инструменти за доставчици: 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/ — Обвивка за настолно приложение

electron/
├── main.js                  Основен процес на Electron
├── preload.js               Мост за предварително зареждане (contextIsolation е активирано)
├── types.d.ts
├── package.json             Конфигурация на electron-builder, версия 3.8.51
├── README.md
├── assets/                  Ресурси за компилацията (икони, права, …)
├── node_modules/            Самостоятелна директория node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Резултат от компилацията (не се включва в хранилището)

Пет npm скрипта в корена на работното пространство: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Автоматичното актуализиране се извършва чрез electron-updater, насочен към канала за издания в GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Основна входна точка на CLI (Node ESM)
├── reset-password.mjs      Нулиране на паролата за управление чрез CLI
├── mcp-server.mjs          Стартиращ модул за MCP сървъра (stdio)
├── nodeRuntimeSupport.mjs  Проверка на версията на Node
└── cli/
    ├── program.mjs         Конструктор на програмата с Commander
    ├── runtime.mjs         Помощна функция withRuntime (първо сървър/резервно БД)
    ├── output.mjs          Форматиращи функции за изхода (json/jsonl/table/csv)
    ├── i18n.mjs            Помощна функция t() с локали
    ├── api.mjs             Помощна функция за извличане от API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Регистриране на команди
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (по един файл за команда/група)

Два изпълними файла са декларирани в package.json → bin:

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

---

7. tests/

Директория	Тип
tests/unit/	Модулни тестове чрез вградения инструмент за тестове на Node (1821 файла плюс поддиректории api/, auth/, authz/)
tests/integration/	Тестове между модули и за състоянието на БД
tests/e2e/	Тестове на потребителския интерфейс с Playwright
tests/e2e/protocol-clients.test.ts	Цялостни тестове на протоколите MCP/A2A
tests/translator/	Тестове, специфични за преводача
tests/security/	Регресионни тестове за сигурността
tests/load/	Тестове за натоварване и устойчивост
tests/golden-set/	Референтни резултати за регресионни тестове на преводача
tests/helpers/, tests/fixtures/, tests/manual/	Помощни ресурси

Често използвани команди:

Команда	Какво изпълнява
npm run test:unit	Всички tests/unit/*.test.ts чрез инструмента за тестове на Node (паралелност 10)
npm run test:vitest	Набор от тестове с Vitest (MCP, autoCombo, кеш)
npm run test:e2e	Набор от UI тестове с Playwright
npm run test:protocols:e2e	Цялостни тестове на протоколите MCP + A2A
npm run test:coverage	Праг за покритие (≥60% редове/инструкции/функции/разклонения)
node --import tsx/esm --test tests/unit/<file>.test.ts	Изпълнение на един файл

---

8. scripts/

Организирана в 6 подпапки според предназначението.

• 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. Конвейер за заявки (обобщение)

Източник: diagrams/request-pipeline.mmd

Клиентска заявка
  → /v1/chat/completions (route.ts)
     Проверка на CORS предварителната заявка
     Валидиране чрез Zod (chatCompletionsSchema в shared/validation/schemas.ts)
     Удостоверяване (extractApiKey + isValidApiKey ИЛИ requireManagementAuth)
     Механизъм за политики (src/server/authz/pipeline.ts)
     Защитни механизми (маскиране на PII, инжектиране в подкани, мост за визуално съдържание)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Проверка на кеша (семантичен кеш + кеш за четене)
     Ограничаване на честотата (rateLimitManager, accountSemaphore)
     Комбинирано маршрутизиране (ако моделът се преобразува до комбинация)
       comboResolver → цикъл за всяка цел → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       извличане от външната услуга → повторен опит/експоненциално изчакване чрез accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE поток ИЛИ JSON отговор
     Ако се използва Responses API: TransformStream чрез open-sse/transformer/responsesTransformer.ts
  → Одит за съответствие (src/lib/compliance/)
  → Отговор към клиента

Състояние по време на изпълнение за устойчивост (три механизма)

Механизъм	Обхват	Къде
Прекъсвач на веригата за доставчик	Целият доставчик	src/shared/utils/circuitBreaker.ts, съхранява се в domain_circuit_breakers
Период на изчакване за връзка	Един акаунт/ключ	markAccountUnavailable() в src/sse/services/auth.ts; използва се от accountFallback.checkFallbackError()
Блокиране на модел	Доставчик + връзка + модел	open-sse/services/accountFallback.ts, съхранява се в domain_lockout_state

Вижте RESILIENCE_GUIDE.md и специалния раздел в CLAUDE.md.

---

10. Как да допринасяте

Добавяне на нов доставчик

1. Регистрирайте го в src/shared/constants/providers.ts (валидира се чрез Zod при зареждане).
2. Добавете изпълнител в open-sse/executors/, ако е необходима персонализирана логика (разширете BaseExecutor).
3. Добавете преобразувател в open-sse/translator/, ако доставчикът не използва формата на OpenAI.
4. Ако е базиран на OAuth, добавете конфигурация в src/lib/oauth/providers/ и src/lib/oauth/services/.
5. Регистрирайте моделите в open-sse/config/providerRegistry.ts (или в регистъра за конкретния формат в open-sse/config/).
6. Напишете тестове в tests/unit/.

Добавяне на нов API маршрут

1. Създайте src/app/api/your-route/route.ts.
2. Следвайте шаблона: CORS → валидиране на тялото чрез Zod → удостоверяване → делегиране към обработчик.
3. Ако структурата на заявката е нова: добавете Zod схемата в src/shared/validation/schemas.ts.
4. Ако е само за управление: добавете пътя към src/shared/constants/publicApiRoutes.ts (списък със забранени пътища за публичната API повърхност).
5. Добавете тестове в tests/unit/.
6. Актуализирайте docs/reference/API_REFERENCE.md и docs/openapi.yaml.

Добавяне на нов модул за БД

1. Създайте src/lib/db/yourModule.ts и импортирайте getDbInstance() от ./core.ts.
2. Експортирайте CRUD функции за вашия домейн.
3. Ако има нови таблици: добавете миграция в src/lib/db/migrations/, номерирана последователно, идемпотентна и транзакционна.
4. Импортиращите модули използват директни импорти от @/lib/db/yourModule (без обобщаващ модул — старият слой за реекспортиране localDb.ts беше премахнат).
5. Добавете тестове в tests/unit/.

Добавяне на нов MCP инструмент

1. Добавете дефиницията на инструмента в open-sse/mcp-server/tools/ (или разширете open-sse/mcp-server/schemas/tools.ts).
2. Задайте подходящия обхват или обхвати в src/shared/constants/mcpScopes.ts.
3. Регистрирайте инструмента в open-sse/mcp-server/server.ts.
4. Добавете тестове в open-sse/mcp-server/__tests__/.
5. Актуализирайте MCP-SERVER.md.

Добавяне на ново A2A умение

Вижте A2A-SERVER.md § Добавяне на ново умение. Уменията се намират в src/lib/a2a/skills/ и се регистрират чрез диспечера на A2A задачи.

---

11. Конвенции

• Стил на кода: отстъп от 2 интервала, двойни кавички, ширина от 100 знака, точки и запетаи, крайни запетаи в стил es5 — налагат се от Prettier чрез lint-staged.
• Импорти: външни → вътрешни (@/, @omniroute/open-sse) → относителни.
• Именуване: файлове в camelCase или kebab-case, компоненти в PascalCase, константи в UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error навсякъде; no-explicit-any = warn в open-sse/ и tests/, а другаде е грешка.
• TypeScript: strict: false (наследен подход). Предпочитайте явни типове пред извеждане на типове при границите между модулите.
• База данни: никога не пишете необработен SQL в маршрути или обработчици — винаги използвайте модулите в src/lib/db/. Никога не импортирайте чрез обобщаващ модул — използвайте директно конкретните модули в src/lib/db/*.
• Типизиране на обекти от БД (#3512): функция, която записва или чете структурата на ред от таблица в БД, трябва да приема/връща именуван TS интерфейс, отразяващ колоните на таблицата 1:1, а не any или анонимен тип, дефиниран на мястото на извикване. Поставете интерфейса до функцията (например export interface UsageEntry в src/lib/usage/usageHistory.ts над saveRequestUsage), запазете отделните полета като незадължителни/допускащи null, когато различни записващи функции попълват реда поетапно, и предпочитайте unknown пред any за поле, чиято структура се различава между извикващите функции (документирайте това при полето, например UsageEntry.tokens приема както необработени данни за употребата във формата на доставчика, така и нормализираната структура). След като броят на any в даден файл достигне нула по този начин, добавете го към списъка с разрешени файлове на check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0), за да не се допусне връщане назад. Това е конвенция за първоначалния етап — по-широкото премахване на анонимни any се извършва итеративно в останалата част от кодовата база.
• Грешки: използвайте try/catch с конкретни типове грешки и регистрирайте събитията с контекст чрез pino. Никога не потискайте безшумно грешки в SSE потоци; използвайте сигнали за прекъсване при почистване.
• Сигурност: никога не използвайте eval() / new Function() / неявно изпълнение на код. Валидирайте всички входни данни със Zod. Шифровайте идентификационните данни при съхранение (AES-256-GCM). Поддържайте списъка със забранени стойности src/shared/constants/upstreamHeaders.ts синхронизиран със слоя за прочистване/валидиране.
• Комити: Conventional Commits — feat(scope): subject. Разрешени обхвати: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Клонове: префикси feat/, fix/, refactor/, docs/, test/, chore/. Никога не правете комити директно в main.
• Husky: преди комит се изпълняват lint-staged + check:docs-sync + check:any-budget:t11; преди изпращане се изпълняват check:any-budget:t11 + check:tracked-artifacts (бързи проверки; изключва test:unit).

---

12. Строги правила (от CLAUDE.md)

1. Никога не комитвайте тайни или идентификационни данни.
2. Никога не използвайте обобщени импорти (barrel imports) — използвайте директно конкретните модули от src/lib/db/*.
3. Никога не използвайте eval() / new Function() / косвено извикване на eval.
4. Никога не комитвайте директно в main.
5. Никога не пишете необработен SQL в маршрути — винаги използвайте модулите от src/lib/db/.
6. Никога не потискайте безшумно грешки в SSE потоци.
7. Винаги валидирайте входните данни със Zod схеми.
8. Винаги включвайте тестове при промяна на продукционен код.
9. Покритието трябва да остане ≥ 60% (инструкции, редове, функции, разклонения).

---

13. Вижте също

• ARCHITECTURE.md — архитектура на високо ниво и отговорности на модулите.
• API_REFERENCE.md — справочник за публичния API и API за управление.
• FEATURES.md — матрица на функционалностите и акценти по версии.
• RESILIENCE_GUIDE.md — подробен преглед на прекъсвача на веригата, периода за изчакване и блокирането.
• AUTO-COMBO.md — оценяване и стратегии на Auto Combo.
• MCP-SERVER.md — пълен каталог на MCP инструменти и транспортни механизми.
• A2A-SERVER.md — умения и откриване в A2A протокола.
• COMPRESSION_GUIDE.md — компресия с RTK и Caveman.
• CLI-TOOLS.md — CLI интеграции.
• ELECTRON_GUIDE.md (ако е наличен), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — цели за внедряване.
• TROUBLESHOOTING.md — често срещани оперативни проблеми.
• CONTRIBUTING.md — работен процес за сътрудници.
• CLAUDE.md — правила на хранилището за Claude Code (основният достоверен източник за много от конвенциите по-горе).
• AGENTS.md — по-задълбочен архитектурен справочник, използван от агентите.