OmniRoute/docs/i18n/sr/docs/architecture/ARCHITECTURE.md

OmniRoute Architecture (Српски)

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

---

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

Последње ажурирање: 2026-06-28

Кратак преглед

OmniRoute је локални gateway за AI рутирање и контролна табла изграђена на Next.js. Обезбеђује јединствену OpenAI-компатибилну крајњу тачку (/v1/*) и рутира саобраћај кроз више upstream провајдера уз превод, резервни режим (fallback), обнову токена и праћење потрошње.

Основне могућности:

• OpenAI-компатибилан API за CLI/алате (355 провајдера, 108 извршилаца)
• Превод захтева/одговора кроз формате различитих провајдера
• Резервни режим комбинације модела (секвенца више модела)
• Структурирани кораци комбинације (provider + model + connection) са runtime уређивањем по compositeTiers
• Резервни режим на нивоу налога (више налога по провајдеру)
• Претходна провера квоте и P2C бирање налога уз свест о квоти у главној путањи ћаскања (chat)
• Управљање OAuth + API-key повезивањем провајдера (22 OAuth модула провајдера)
• Генерисање embedding-а преко /v1/embeddings (18 провајдера)
• Генерисање слика преко /v1/images/generations (10+ провајдера, 20+ модела)
• Транскрипција аудио записа преко /v1/audio/transcriptions (18 провајдера)
• Претварање текста у говор преко /v1/audio/speech (24 уграђена провајдера)
• Генерисање видеа преко /v1/videos/generations (ComfyUI + SD WebUI)
• Генерисање музике преко /v1/music/generations (ComfyUI)
• Веб претрага преко /v1/search (20 провајдера)
• Модерации преко /v1/moderations
• Reranking преко /v1/rerank
• Рашчлањивање think ознака (``) за моделе који закључују (reasoning)
• Санитизација одговора за строгу компатибилност са OpenAI SDK
• Нормализација улога (developer→system, system→user) за компатибилност између провајдера
• Конверзија структурираног излаза (json_schema → Gemini responseSchema)
• Локална персистенција за провајдере, кључеве, алијасе, комбинације, подешавања, цене (122 модула базе података)
• Праћење потрошње/трошкова и логовање захтева
• Опциона синхронизација у облаку за синхронизацију стања на више уређаја
• IP allowlist/blocklist листа за контролу приступа API-ју
• Управљање буџетом размишљања (passthrough/аутоматски/прилагођено/адаптивно)
• Убацивање глобалног системског упита (prompt)
• Праћење сесија и „отисака прста“ (fingerprinting)
• Побољшано ограничавање брзине по налогу са профилима специфичним за провајдера
• Образац „circuit breaker“ за отпорност провајдера
• Заштита против „thundering herd“ ефекта уз mutex закључавање
• Кеш за дедупликацију захтева на основу потписа
• Домен слоја: правила трошкова, политика резервног режима, политика закључавања
• Context Relay: сажеци предаје сесије за континуитет ротације налога
• Персистенција стања домена (SQLite write-through кеш за резервне режиме, буџете, закључавања, circuit breaker-е)
• Механизам политика за централизовану евалуацију захтева (закључавање → буџет → резервни режим)
• Телеметрија захтева са агрегацијом латенције p50/p95/p99
• Телеметрија циљева комбинације и историјско здравље циљева комбинације преко combo_execution_key / combo_step_id
• Correlation ID (X-Request-Id) за трасирање од краја до краја
• Логовање ревизије усклађености (compliance audit) са могућношћу искључивања по API кључу
• Eval оквир за осигурање квалитета LLM-а
• Контролна табла здравља са статусом circuit breaker-а провајдера у реалном времену
• MCP сервер (110 алата) са 3 транспорта (stdio/SSE/Streamable HTTP)
• A2A сервер (JSON-RPC 2.0 + SSE) са вештинама и животним циклусом задатака
• Систем меморије (екстракција, убацивање, преузимање, сумирање)
• Систем вештина (регистар, извршилац, sandbox, уграђене вештине)
• MITM proxy са управљањем сертификатима и DNS обрадом
• Middleware за заштиту од prompt injection напада
• Пипелajн компресије упита (prompt) са Caveman, RTK, наслаганим пипелајнима, комбинацијама компресије, језичким пакетима и аналитиком
• ACP (Agent Communication Protocol) регистар
• Модуларни OAuth провајдери (22 засебна модула у src/lib/oauth/providers/)
• Скрипте за деинсталацију/потпуну деинсталацију
• Акција за поправку OAuth окружења
• WebSocket мост за WS клијенте компатибилне са OpenAI-јем (/v1/ws)
• Управљање sync токенима (издавање/опозив, преузимање конфигурационог пакета верзионисаног ETag-ом)
• GLM Thinking (glmt) провајдерски преподешен режим првог реда
• Хибридно бројање токена (бројање на страни провајдера /messages/count_tokens са резервном проценом)
• Аутоматско семенирање алијаса модела (30+ нормализација дијалеката између proxy сервера при покретању)
• Безбедно излазно преузимање (fetch) са SSRF заштитом, блокирањем приватних URL-ова и подесивим поновним покушајима
• Поновни покушаји ћаскања свесни хлађења (cooldown) са подесивим requestRetry и maxRetryIntervalSec
• Валидација runtime окружења помоћу Zod при покретању
• Ревизија усклађености v2 (compliance audit v2) са паginacijom, CRUD догађајима провајдера и логовањем валидације блокиране од SSRF-а

Примарни модел рада:

• Next.js app рутe под src/app/api/* имплементирају и API-је контролне табле и API-је компатибилности
• Дељено SSE/routing језгро у src/sse/* + open-sse/* обрађује извршавање провајдера, превод, стриминг, резервни режим и потрошњу

Референтни дијаграми

Канонски, верзионисани Mermaid извори за v3.8.0 платформу налазе се у docs/diagrams/. Два су приказана испод ради оријентације; остали су линковани из својих специфичних водича по домену.

Извор: diagrams/request-pipeline.mmd

Извор: diagrams/resilience-3layers.mmd — такође линкован из RESILIENCE_GUIDE.md и референце отпорности у CLAUDE.md.

Обим и границе

У обиму

• Локални gateway runtime
• API-ови за управљање dashboard-ом
• Аутентикација провајдера и обнова токена
• Превод захтева и SSE streaming
• Локални state + перзистенција коришћења
• Опционална оркестрација синхронизације у cloud-у

Ван обима

• Имплементација cloud сервиса иза NEXT_PUBLIC_CLOUD_URL
• SLA/контролна раван провајдера ван локалног процеса
• Спољашњи CLI извршни фајлови сами по себи (Claude CLI, Codex CLI, итд.)

Dashboard површина (тренутна)

Главне странице под src/app/(dashboard)/dashboard/:

• /dashboard — брзи почетак + преглед провајдера
• /dashboard/endpoint — endpoint proxy + MCP + A2A + картице API endpoint-а
• /dashboard/providers — конекције и креденцијали провајдера
• /dashboard/combos — combo стратегије, шаблони, градитељ по корацима, правила рутирања модела, ручно перзистирано редослеђивање
• /dashboard/auto-combo — Auto Combo Engine: тежине оцењивања, паковања режима (mode packs), пресети виртуелне фабрике, телеметрија
• /dashboard/costs — агрегација трошкова и видљивост цена
• /dashboard/analytics — аналитика коришћења, евалуације, здравље combo циљева
• /dashboard/limits — контроле квоте/rate-a
• /dashboard/cli-tools — CLI онбординг, детекција runtime-а, генерисање конфигурације
• /dashboard/agents — детектовани ACP агенти + регистрација прилагођених агената
• /dashboard/cloud-agents — задаци агента хостовани у cloud-у (Codex Cloud, Devin, Jules) и животни циклус задатака
• /dashboard/skills — A2A регистар вештина, sandbox извршавање, каталог уграђених вештина
• /dashboard/memory — инспекција и претрага перзистентне conversational memory
• /dashboard/webhooks — исходне webhook претплате, ротација тајних кључева, статистика поновних покушаја
• /dashboard/batch — слање batch послова и праћење напретка
• /dashboard/cache — статистике read-through и reasoning cache-a, контроле избацивања (eviction)
• /dashboard/playground — интерактивни чет playground против било којег конфигурисаног combo/модела
• /dashboard/changelog — приказивач changelog-а у апликацији (рендерује CHANGELOG.md)
• /dashboard/system — runtime дијагностика, информације о верзији, површина за валидацију окружења
• /dashboard/onboarding — чаробњак почетног подешавања за нове инсталације
• /dashboard/media — playground за слике/видео/музику
• /dashboard/search-tools — тестирање провајдера претраге и историја
• /dashboard/health — uptime, circuit breaker-и, rate limit-и, сесије под праћењем квоте
• /dashboard/logs — логови захтева/proxy-a/аудита/конзоле
• /dashboard/settings — картице системских подешавања (опште, рутирање, подразумевани combo, итд.)
• /dashboard/context/caveman — правила Caveman компресије, језички пакети, преглед и режим излаза
• /dashboard/context/rtk — филтери за RTK излаз из команде, преглед и подешавања безбедности runtime-а
• /dashboard/context/combos — именовани pipeline-ови компресије додељени routing combo-има
• /dashboard/translator — инспекција преводиоца и преглед конверзије формата захтева
• /dashboard/audit — прегледник compliance аудит логова са паginацијом и структурираним metadata
• /dashboard/usage — прегледник коришћења по захтеву везан за usage_history
• /dashboard/compression — аналитика компресије, статистике и додела pipeline-а
• /dashboard/api-manager — животни циклус API кључева и дозволе за модел

Контекст система на високом нивоу

flowchart LR
    subgraph Clients[Developer Clients]
        C1[Claude Code]
        C2[Codex CLI]
        C3[OpenClaw / Droid / Cline / Continue / Roo]
        C4[Custom OpenAI-compatible clients]
        BROWSER[Browser Dashboard]
    end

    subgraph Router[OmniRoute Local Process]
        API[V1 Compatibility API\n/v1/*]
        DASH[Dashboard + Management API\n/api/*]
        CORE[SSE + Translation Core\nopen-sse + src/sse]
        DB[(storage.sqlite)]
        UDB[(usage tables + log artifacts)]
    end

    subgraph Upstreams[Upstream Providers]
        P1[OAuth Providers\nClaude/Codex/Gemini/Qoder/GitHub/Kiro/Cursor/Antigravity]
        P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
        P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
    end

    subgraph Cloud[Optional Cloud Sync]
        CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
    end

    C1 --> API
    C2 --> API
    C3 --> API
    C4 --> API
    BROWSER --> DASH

    API --> CORE
    DASH --> DB
    CORE --> DB
    CORE --> UDB

    CORE --> P1
    CORE --> P2
    CORE --> P3

    DASH --> CLOUD

Основне компоненте окружења за извршавање

1) API и слој рутирања (Next.js App Routes)

Главни директоријуми:

• src/app/api/v1/* и src/app/api/v1beta/* за компатибилне API-је
• src/app/api/* за API-је за управљање/конфигурацију
• Next преусмерења у next.config.mjs мапирају /v1/* на /api/v1/*

Важне компатибилне руте:

• src/app/api/v1/chat/completions/route.ts
• src/app/api/v1/messages/route.ts
• src/app/api/v1/responses/route.ts
• src/app/api/v1/models/route.ts — укључује прилагођене моделе са custom: true
• src/app/api/v1/embeddings/route.ts — генерисање embedding-а (6 провајдера)
• src/app/api/v1/images/generations/route.ts — генерисање слика (4+ провајдера, укључујући Antigravity/Nebius)
• src/app/api/v1/messages/count_tokens/route.ts
• src/app/api/v1/providers/[provider]/chat/completions/route.ts — намењен ćaskanju (chat) по провајдеру
• src/app/api/v1/providers/[provider]/embeddings/route.ts — намењен embedding-у по провајдеру
• src/app/api/v1/providers/[provider]/images/generations/route.ts — намењен сликама по провајдеру
• src/app/api/v1beta/models/route.ts
• src/app/api/v1beta/models/[...path]/route.ts

Домени за управљање:

• Аутентикација/подешавања: src/app/api/auth/*, src/app/api/settings/*
• Провајдери/конекције: src/app/api/providers*
• Провајдерски чворови: src/app/api/provider-nodes*
• Прилагођени модели: src/app/api/provider-models (GET/POST/DELETE)
• Каталог модела: src/app/api/models/route.ts (GET)
• Конфигурација proxy-ja: src/app/api/settings/proxy (GET/PUT/DELETE) + src/app/api/settings/proxy/test (POST)
• OAuth: src/app/api/oauth/*
• Кључеви/алијаси/комбинације/цене: src/app/api/keys*, src/app/api/models/alias, src/app/api/combos*, src/app/api/pricing
• Употреба (usage): src/app/api/usage/*
• Синхронизација/облак: src/app/api/sync/*, src/app/api/cloud/*
• Помагала за CLI алате: src/app/api/cli-tools/*
• IP филтер: src/app/api/settings/ip-filter (GET/PUT)
• Буџет размишљања (thinking budget): src/app/api/settings/thinking-budget (GET/PUT)
• Системски промпт: src/app/api/settings/system-prompt (GET/PUT)
• Компресија: src/app/api/settings/compression, src/app/api/compression/*, и src/app/api/context/*
• Сесије: src/app/api/sessions (GET)
• Ограничења брзине (rate limits): src/app/api/rate-limits (GET)
• Отпорност (resilience): src/app/api/resilience (GET/PATCH) — ред чекања захтева, период хлађења конекције, прекидач провајдера, конфигурација чекања на хлађење
• Ресетовање отпорности: src/app/api/resilience/reset (POST) — ресетовање прекидача провајдера
• Статистика кеша: src/app/api/cache/stats (GET/DELETE)
• Телеметрија: src/app/api/telemetry/summary (GET)
• Буџет: src/app/api/usage/budget (GET/POST)
• Резервни ланци (fallback chains): src/app/api/fallback/chains (GET/POST/DELETE)
• Ревизија усклађености (compliance audit): src/app/api/compliance/audit-log (GET, са пагинацијом + структурираним метаподацима)
• Евалуације: src/app/api/evals (GET/POST), src/app/api/evals/[suiteId] (GET)
• Политике: src/app/api/policies (GET/POST)
• Синхронизациони токени: src/app/api/sync/tokens (GET/POST), src/app/api/sync/tokens/[id] (GET/DELETE)
• Пакет конфигурације: src/app/api/sync/bundle (GET, ETag-верзионисани снимак подешавања/провајдера/комбинација/кључева)
• WebSocket: src/app/api/v1/ws/route.ts — Upgrade handler за OpenAI-компатибилне WS клијенте

2) SSE + Translation jezgro

Glavni moduli protoka:

• Ulaz: src/sse/handlers/chat.ts
• Osnovna orkestracija: open-sse/handlers/chatCore.ts
• Adapteri za izvršavanje kod provajdera: open-sse/executors/*
• Detekcija formata/konfiguracija provajdera: open-sse/services/provider.ts
• Parsiranje/razrešavanje modela: src/sse/services/model.ts, open-sse/services/model.ts
• Logika fallback naloga: open-sse/services/accountFallback.ts
• Registar prevoda: open-sse/translator/index.ts
• Transformacije toka (stream): open-sse/utils/stream.ts, open-sse/utils/streamHandler.ts
• Ekstrakcija/normalizacija upotrebe: open-sse/utils/usageTracking.ts
• Parser think tagova: open-sse/utils/thinkTagParser.ts
• Handler za embedding: open-sse/handlers/embeddings.ts
• Registar embedding provajdera: open-sse/config/embeddingRegistry.ts
• Handler za generisanje slika: open-sse/handlers/imageGeneration.ts
• Registar provajdera za slike: open-sse/config/imageRegistry.ts
• Sanitizacija odgovora: open-sse/handlers/responseSanitizer.ts
• Normalizacija uloga: open-sse/services/roleNormalizer.ts

Servisi (poslovna logika):

• Izbor/ocenjivanje naloga: open-sse/services/accountSelector.ts
• Upravljanje životnim ciklusom konteksta: open-sse/services/contextManager.ts
• Primena IP filtera: open-sse/services/ipFilter.ts
• Praćenje sesija: open-sse/services/sessionManager.ts
• Deduplikacija zahteva: open-sse/services/signatureCache.ts
• Ubacivanje system prompt-a: open-sse/services/systemPrompt.ts
• Upravljanje budžetom razmišljanja (thinking budget): open-sse/services/thinkingBudget.ts
• Wildcard rutiranje modela: open-sse/services/wildcardRouter.ts
• Upravljanje ograničenjima brzine (rate limit): open-sse/services/rateLimitManager.ts
• Circuit breaker: src/shared/utils/circuitBreaker.ts
• Predaja konteksta (handoff): open-sse/services/contextHandoff.ts — generisanje sažetka predaje i ubacivanje za strategiju context-relay
• Kompresija: open-sse/services/compression/* — proaktivna kompresija pre prevoda kod provajdera; uključuje Caveman pravila, RTK filtere, stackovane pipeline-ove, kombinacije kompresije, statistiku i validaciju
• Dobavljač kvote za Codex: open-sse/services/codexQuotaFetcher.ts — dobavlja Codex kvotu za odluke o context-relay predaji
• Ponovni pokušaj svestan cooldown-a: src/sse/services/cooldownAwareRetry.ts — ponovni pokušaji po modelu uz poštovanje cooldown-a, sa konfigurabilnim requestRetry / maxRetryIntervalSec
• Bezbedno izlazno preuzimanje (fetch): src/shared/network/safeOutboundFetch.ts — zaštićeno preuzimanje provajdera/modela sa SSRF zaštitom, blokiranjem privatnih URL-ova, ponovnim pokušajima i tajmautom
• Zaštita izlaznih URL-ova: src/shared/network/outboundUrlGuard.ts — validira URL-ove provajdera u odnosu na privatne/localhost CIDR opsege
• Podrazumevane vrednosti zahteva provajdera: open-sse/services/providerRequestDefaults.ts — podrazumevane vrednosti na nivou provajdera za maxTokens, temperature, thinkingBudgetTokens
• GLM konstante provajdera: open-sse/config/glmProvider.ts — deljeni GLM modeli, URL-ovi kvote, GLMT tajmaut/podrazumevane vrednosti
• Antigravity upstream: open-sse/config/antigravityUpstream.ts — konstante osnovnog URL-a i putanje za otkrivanje (discovery)
• Konstante Codex klijenta: open-sse/config/codexClient.ts — verzionisan user-agent i vrednosti verzije klijenta
• Seed alijasa modela: src/lib/modelAliasSeed.ts — inicijalizuje preko 30 alijasa dijalekata cross-proxy pri pokretanju

Moduli domenskog sloja:

• Pravila troškova/budžeti: src/domain/costRules.ts
• Fallback politika: src/domain/fallbackPolicy.ts
• Razrešavač kombinacija: src/domain/comboResolver.ts
• Politika zabrane (lockout): src/domain/lockoutPolicy.ts
• Mehanizam politika: src/domain/policyEngine.ts — centralizovana evaluacija lockout → budžet → fallback
• Katalog kodova grešaka: src/shared/constants/errorCodes.ts
• ID zahteva: src/shared/utils/requestId.ts
• Tajmaut preuzimanja (fetch): src/shared/utils/fetchTimeout.ts
• Telemetrija zahteva: src/shared/utils/requestTelemetry.ts
• Usklađenost/revizija: src/lib/compliance/index.ts
• Izvršavanje evaluacija: src/lib/evals/evalRunner.ts
• Perzistencija stanja domena: src/lib/db/domainState.ts — SQLite CRUD operacije za fallback lance, budžete, istoriju troškova, stanje zabrane (lockout), circuit breakere

OAuth moduli provajdera (22 pojedinačna fajla u src/lib/oauth/providers/):

• Indeks registra: src/lib/oauth/providers/index.ts
• Pojedinačni provajderi: agy.ts, antigravity.ts, claude.ts, cline.ts, codebuddy-cn.ts, codex.ts, cursor.ts, devin-desktop.ts, ghe-copilot.ts, github.ts, gitlab-duo.ts, grok-cli-oauth.ts, grok-cli.ts, kilocode.ts, kimi-coding.ts, kiro.ts, openference.ts, qoder.ts, trae.ts, xai-oauth.ts, zed-hosted.ts, zed.ts
• Tanak omotač (wrapper): src/lib/oauth/providers.ts — reeksportuje iz pojedinačnih modula

5) Уграђене услуге (v3.8.4)

OmniRoute може да инсталира, надгледа и рутира ка локално покренутим процесима AI алата названим уграђене услуге. Испоручено је пет: 9Router, CLIProxyAPI, Bifrost, Mux и Dario.

Слојеви архитектуре:

• UI (/dashboard/providers/services) — страница са две картице са контролама животног циклуса, стримингом логова у реалном времену, управљањем API кључевима и (за 9Router) уграђеним нативним UI-јем преко интерног reverse proxy-ја.
• API (/api/services/{name}/*) — 11 endpoint-а за 9Router, 10 за CLIProxyAPI, по 8 за Bifrost / Mux / Dario, сви класификовани као LOCAL_ONLY (строго правило #17). Заједнички GET /api/services/[name]/logs SSE endpoint служи обе услуге.
• Supervisor (src/lib/services/) — генеричка ServiceSupervisor класа обмотава child_process.spawn, чува 5 MB прстенасти бафер (ring buffer) за SSE стриминг логова, петљу за проверу здравља (health probe), атомско закључавање операција и корак постепеног гашења SIGTERM→SIGKILL. bootstrap.ts повезује све конфигурисане услуге приликом покретања процеса.
• Provider/executor (open-sse/executors/ninerouter.ts) — 9Router је изложен као прави provider. Модели имају префикс 9router/{sub}/{model} и синхронизују се сваких 5 минута преко endpoint-а /v1/models из 9Router-а.

Детаљнији увид: docs/frameworks/EMBEDDED-SERVICES.md

Главни подсистеми (v3.8.0)

A. Auto Combo механизам

Auto Combo динамички бодује и бира циљеве рутирања у тренутку захтева, уместо да се ослања на статичку дефиницију комба. Он покреће породицу префикса модела auto/*.

• Улазна тачка механизма: open-sse/services/autoCombo/ (autoComboEngine.ts, scoringEngine.ts, virtualFactory.ts, modePacks.ts)
• Resolver: src/domain/comboResolver.ts (аутоматска детекција префикса auto/)
• Контролна табла: /dashboard/auto-combo
• Телеметрија: SQLite табела auto_combo_decisions

Кључне могућности:

• 19 стратегија рутирања (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, context-relay, fusion, плус путања за резервни случај) — auto је најзначајнија новина у v3.8.0; fusion (панелски fan-out + синтеза од стране судије, open-sse/services/fusion.ts) је нов у v3.8.36.
• Бодовање са 16 фактора: квота, здравље, инверзни трошак, инверзна латенција, подударност задатка и још десет других. Каноничка табела фактора и њихових подразумеваних тежина се налази у docs/routing/AUTO-COMBO.md — понављање тога овде би јој дало друго место да застари.
• Виртуелна фабрика материјализује ефемерне combo-е када не постоји одговарајући именовани combo, преузимајући кандидате из здравих активних веза провајдера.
• Auto префикси: auto/coding, auto/cheap, auto/fast, auto/offline, auto/smart, auto/lkgp — сваки подржан подешеним профилом тежина.
• 6 mode packs: ship-fast, cost-saver, quality-first, offline-friendly, reliability-first и chaos-mode — задате конфигурације тежина које се могу позвати из контролне табле. (Не треба их мешати са auto/* префиксима изнад, који су варијанте у тренутку захтева.)

За потпуне алгоритамске детаље (формуле фактора, подешавање тежина), погледајте docs/routing/AUTO-COMBO.md.

B. Cloud Agents

Cloud Agents обмотава платформе агента кода трећих страна у облаку (Codex Cloud, Devin, Jules) иза јединственог животног циклуса задатака подржаног базом података. Сви endpoint-и за креирање/инспекцију задатака захтевају management аутентикацију.

• Корен модула: src/lib/cloudAgent/ (baseAgent.ts, registry.ts, api.ts, types.ts, db.ts, плус поддиректоријуми по агенту под agents/)
• Имплементације по агенту: agents/codex/, agents/devin/, agents/jules/
• Јавни endpoint-и: /api/v1/agents/tasks/* (list/create/get/cancel)
• Management endpoint-и: /api/cloud/* (provisioning, status, batch)
• Контролна табла: /dashboard/cloud-agents
• Складиштење: табела cloud_agent_tasks

За специфичности provisioning-а по агенту и OAuth, погледајте docs/frameworks/CLOUD_AGENT.md.

C. Guardrails

Модул guardrails је middleware слој који се може поново учитати без прекида рада (hot-reloadable) и који инспектује захтеве и одговоре тражећи PII, prompt injection и небезбедан визуелни садржај. Прекршаји прекидају захтев HTTP статусом 503 плус структурираним кодом грешке, дозвољавајући downstream позивачима да покушају поново или гранају ток.

• Корен модула: src/lib/guardrails/ (base.ts, registry.ts, piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts)
• Hot reload: registry прати промене конфигурације и на месту поново изграђује ланац
• Тачке уклапања: улазна тачка chat handler-а, handler за генерисање слика, санитизатор одговора
• HTTP уговор: прекршаји се приказују као 503 са error.code = "GUARDRAIL_VIOLATION"

За писање скупова правила и подешавање прагова, погледајте docs/security/GUARDRAILS.md.

D. Domain слој

Namespace src/domain/ централизује одлуке политике тако да route handler-и не морају сами да састављају логику закључавања/буџета/резервног пута.

• Механизам политике: src/domain/policyEngine.ts — јединствена улазна тачка за евалуацију пре извршења (редослед lockout → budget → fallback)
• Правила трошкова: src/domain/costRules.ts
• Политика резервног пута: src/domain/fallbackPolicy.ts
• Политика закључавања: src/domain/lockoutPolicy.ts
• Рутирање на основу тагова: src/domain/tagRouter.ts
• Combo resolver: src/domain/comboResolver.ts — разрешава називе combo-а, префиксе auto/* и wildcard циљеве модела у конкретне планове извршења
• Спајач правила везе/модела: src/domain/connectionModelRules.ts
• Снимци доступности модела: src/domain/modelAvailability.ts
• Праћење истека провајдера: src/domain/providerExpiration.ts
• Кеш квоте: src/domain/quotaCache.ts
• Стање деградације: src/domain/degradation.ts
• Ревизија конфигурације: src/domain/configAudit.ts
• Градитељ метаподатака OmniRoute одговора: src/domain/omnirouteResponseMeta.ts
• Подсистем процене: src/domain/assessment/ — периодични послови евалуације

E. Токовник ауторизације (Authorization Pipeline)

Токовник ауторизације класификује сваки долазни захтев и примењује одговарајући ланац политика пре прослеђивања (dispatch).

• Улазна тачка токовника: src/server/authz/pipeline.ts
• Класификатор захтева: src/server/authz/classify.ts — разликује јавне компатибилне руте од management рута
• Инвентар јавних рута: src/shared/constants/publicApiRoutes.ts
• Политике: src/server/authz/policies/ — компоновани предикати (requireApiKey, requireManagement, requireFreshAuth, итд.)
• Помоћне функције за заглавља: src/server/authz/headers.ts
• Помагач за потврђивање: src/server/authz/assertAuth.ts
• Контекст захтева: src/server/authz/context.ts

Јавне у односу на management руте представљају строгу границу: API-ји за агенте/cooldown и мутације провајдера захтевају management аутентикацију (HTTP 401 ако недостаје).

За потпуна правила класификације рута, погледајте docs/architecture/AUTHZ_GUIDE.md.

F. Workflow FSM и Task-Aware Router

Router вођен коначним автоматом стања (FSM), надслојен изнад бирања combo-а да усмерава саобраћај на основу детектоване фазе тока рада (планирање, извршење, преглед) и афинитета према позадинским задацима.

• Workflow FSM: open-sse/services/workflowFSM.ts
• Task-aware router: open-sse/services/taskAwareRouter.ts
• Детектор позадинских задатака: open-sse/services/backgroundTaskDetector.ts
• Класификатор намере: open-sse/services/intentClassifier.ts

Транзиције FSM-а се уносе у бодовање Auto Combo-а, усмеравајући ка јефтинијим моделима за позадинске/аутоматизоване задатке и ка снажнијим моделима за интерактивне кориснике при планирању/прегледу.

G. Отпорност специфична за провајдера

Неколико провајдера испоручује посвећене модуле отпорности и прикривања (stealth) који се надовезују на глобалне слојеве circuit breaker-а / cooldown-а веза / закључавања модела:

• Antigravity 429 механизам: open-sse/services/antigravity429Engine.ts (ротира идентитет, чисти заглавља одговора, покреће праћење кредита/верзије преко antigravityCredits.ts, antigravityHeaderScrub.ts, antigravityHeaders.ts, antigravityIdentity.ts, antigravityVersion.ts)
• Политика квоте за ModelScope: open-sse/services/modelscopePolicy.ts
• Claude Code CCH (Compatibility Channel Handshake): open-sse/services/claudeCodeCCH.ts, плус claudeCodeCompatible.ts, claudeCodeConstraints.ts, claudeCodeExtraRemap.ts, claudeCodeToolRemapper.ts
• Обликовање отиска (fingerprint) Claude Code: open-sse/services/claudeCodeFingerprint.ts
• Прикривање Claude Code: open-sse/services/claudeCodeObfuscation.ts

За потпун stealth приручник и оперативна упутства, погледајте docs/security/STEALTH_GUIDE.md.

H. Webhooks, кеш резоновања, кеш читања

• Webhooks — одлазно слање за догађаје провајдера/налога/задатка.
  • Dispatcher: src/lib/webhookDispatcher.ts
  • Складиштење: SQLite табела webhooks (преко src/lib/db/webhooks.ts)
  • Контролна табла: /dashboard/webhooks (претплате, тајне, историја покушаја)
  • За таксономију догађаја и семантику покушаја, погледајте docs/frameworks/WEBHOOKS.md.
• Кеш резоновања — блокови резоновања за поновну репродукцију за провајдере који емитују токене мишљења (Claude, GLMT, итд.) тако да узастопни потези могу да прескоче поновно размишљање.
  • DB слој: src/lib/db/reasoningCache.ts
  • Слој услуге: open-sse/services/reasoningCache.ts
  • За семантику репродукције, погледајте docs/routing/REASONING_REPLAY.md.
• Кеш читања — краткотрајан кеш одговора кључан по потпису и коришћен за сажимање идентичних поновних покушаја од покварених upstream SDK-ова.
  • DB слој: src/lib/db/readCache.ts
  • Endpoint статистике: GET /api/cache/stats, контролна табла на /dashboard/cache

3) Sloj za perzistenciju

Primarna baza stanja (SQLite):

• Osnovna infrastruktura: src/lib/db/core.ts (better-sqlite3, migracije, WAL)
• Pristup bazi: uvozite konkretne src/lib/db/* module direktno (stari localDb.ts barrel je uklonjen)
• fajl: ${DATA_DIR}/storage.sqlite (ili $XDG_CONFIG_HOME/omniroute/storage.sqlite kada je podešeno, inače ~/.omniroute/storage.sqlite)
• entiteti (tabele + KV imenski prostori): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, customModels, proxyConfig, ipFilter, thinkingBudget, systemPrompt

Perzistencija korišćenja:

• fasada: src/lib/usageDb.ts (rasčlanjeni moduli u src/lib/usage/*)
• SQLite tabele u storage.sqlite: usage_history, call_logs, proxy_logs
• opcioni fajl artefakti ostaju iz razloga kompatibilnosti/debagovanja (${DATA_DIR}/log.txt, ${DATA_DIR}/call_logs/, <repo>/logs/...)
• stariji JSON fajlovi se migriraju u SQLite putem migracija pri pokretanju kada postoje

Baza stanja domena (SQLite):

• src/lib/db/domainState.ts — CRUD operacije za stanje domena
• Tabele (kreirane u src/lib/db/core.ts): domain_fallback_chains, domain_budgets, domain_cost_history, domain_lockout_state, domain_circuit_breakers
• Šablon write-through keša: mape u memoriji su autoritativne u vreme izvršavanja; izmene se sinhrono upisuju u SQLite; stanje se obnavlja iz baze prilikom hladnog pokretanja

4) Površine za autentifikaciju i bezbednost

• Autentifikacija kolačićem za dashboard: src/proxy.ts, src/app/api/auth/login/route.ts
• Generisanje/verifikacija API ključa: src/shared/utils/apiKey.ts
• Tajne provajdera se čuvaju u zapisima providerConnections
• Podrška za izlazni proxy putem open-sse/utils/proxyFetch.ts (env promenljive) i open-sse/utils/networkProxy.ts (podesivo po provajderu ili globalno)
• SSRF / zaštita izlaznog URL-a: src/shared/network/outboundUrlGuard.ts — blokira privatne/loopback/link-local opsege za sve pozive provajdera
• Validacija env promenljivih u vreme izvršavanja: src/lib/env/runtimeEnv.ts — Zod šema za sve promenljive okruženja, prikazana kao greške/upozorenja prilikom pokretanja
• Sync tokeni: src/lib/db/syncTokens.ts — tokeni ograničenog opsega za endpointe preuzimanja konfiguracionih paketa; podržani SQLite tabelom sync_tokens (migracija 024_create_sync_tokens.sql)
• Autentifikacija WebSocket handshake-a: src/lib/ws/handshake.ts — validira zahteve za WS upgrade putem API ključa ili sesijskog kolačića

5) Sinhronizacija u oblaku

• Inicijalizacija planera: src/lib/initCloudSync.ts, src/shared/services/initializeCloudSync.ts, src/shared/services/modelSyncScheduler.ts
• Periodični zadatak: src/shared/services/cloudSyncScheduler.ts
• Periodični zadatak: src/shared/services/modelSyncScheduler.ts
• Kontrolna ruta: src/app/api/sync/cloud/route.ts

Životni ciklus zahteva (/v1/chat/completions)

sequenceDiagram
    autonumber
    participant Client as CLI/SDK Klijent
    participant Route as /api/v1/chat/completions
    participant Chat as src/sse/handlers/chat
    participant Core as open-sse/handlers/chatCore
    participant Model as Model Resolver
    participant Auth as Selektor kredencijala
    participant Exec as Izvršavač provajdera
    participant Prov as Provajder uzvodno
    participant Stream as Prevodilac strima
    participant Usage as usageDb

    Client->>Route: POST /v1/chat/completions
    Route->>Chat: handleChat(request)
    Chat->>Model: parsiraj/razreši model ili combo

    alt Combo model
        Chat->>Chat: iteriraj kroz combo modele (handleComboChat)
    end

    Chat->>Auth: getProviderCredentials(provider)
    Auth-->>Chat: aktivni nalog + tokeni/api ključ

    Chat->>Core: handleChatCore(body, modelInfo, credentials)
    Core->>Core: detektuj izvorni format
    Core->>Core: prevedi zahtev u ciljni format
    Core->>Exec: execute(provider, transformedBody)
    Exec->>Prov: uzvodni API poziv
    Prov-->>Exec: SSE/JSON odgovor
    Exec-->>Core: odgovor + metapodaci

    alt 401/403
        Core->>Exec: refreshCredentials()
        Exec-->>Core: ažurirani tokeni
        Core->>Exec: ponovi zahtev
    end

    Core->>Stream: prevedi/normalizuj strim u format klijenta
    Stream-->>Client: SSE delovi / JSON odgovor

    Stream->>Usage: izdvoji podatke o korišćenju i sačuvaj istoriju/log

Ток Combo + Резервни налог (Account Fallback)

flowchart TD
    A[Долазни низ модела] --> B{Да ли је combo назив?}
    B -- Да --> C[Учитај секвенцу combo модела]
    B -- Не --> D[Путања за један модел]

    C --> E[Пробај модел N]
    E --> F[Разреши provider/model]
    D --> F

    F --> G[Изабери акредитиве налога]
    G --> H{Да ли су акредитиви доступни?}
    H -- Не --> I[Врати provider недоступан]
    H -- Да --> J[Изврши захтев]

    J --> K{Успех?}
    K -- Да --> L[Врати одговор]
    K -- Не --> M{Грешка подложна резерви?}

    M -- Не --> N[Врати грешку]
    M -- Да --> O[Означи налог недоступан cooldown]
    O --> P{Постоји други налог за provider?}
    P -- Да --> G
    P -- Не --> Q{У combo-у са следећим моделом?}
    Q -- Да --> E
    Q -- Не --> R[Врати све недоступно]

Одлуке о резервној опцији (fallback) вођене су у open-sse/services/accountFallback.ts уз коришћење кодова статуса и хеуристике порука о грешкама. Combo рутирање додаје још један заштитни механизам: 400 грешке специфичне за provider, као што су неуспеси блокирања садржаја (upstream content-block) и валидације улоге, третирају се као грешке локалне за модел, тако да каснији combo циљеви и даље могу да се изврше.

Животни циклус OAuth онбординга и обновe токена

sequenceDiagram
    autonumber
    participant UI as Dashboard UI
    participant OAuth as /api/oauth/[provider]/[action]
    participant ProvAuth as Provider Auth Server
    participant DB as localDb
    participant Test as /api/providers/[id]/test
    participant Exec as Provider Executor

    UI->>OAuth: GET authorize или device-code
    OAuth->>ProvAuth: креирај auth/device ток
    ProvAuth-->>OAuth: auth URL или device code payload
    OAuth-->>UI: подаци тока

    UI->>OAuth: POST exchange или poll
    OAuth->>ProvAuth: размена/провера токена
    ProvAuth-->>OAuth: access/refresh токени
    OAuth->>DB: createProviderConnection(oauth data)
    OAuth-->>UI: успех + id везе

    UI->>Test: POST /api/providers/[id]/test
    Test->>Exec: валидирај акредитиве / опционо обнови
    Exec-->>Test: важећи или обновљени подаци токена
    Test->>DB: ажурирај статус/токене/грешке
    Test-->>UI: резултат валидације

Обнова током активног саобраћаја извршава се унутар open-sse/handlers/chatCore.ts преко executor функције refreshCredentials().

Животни циклус Cloud синхронизације (Укључивање / Синхронизација / Искључивање)

sequenceDiagram
    autonumber
    participant UI as Endpoint Page UI
    participant Sync as /api/sync/cloud
    participant DB as localDb
    participant Cloud as External Cloud Sync
    participant Claude as ~/.claude/settings.json

    UI->>Sync: POST action=enable
    Sync->>DB: постави cloudEnabled=true
    Sync->>DB: обезбеди да API кључ постоји
    Sync->>Cloud: POST /sync/{machineId} (provideri/aliasi/combo/kljucevi)
    Cloud-->>Sync: резултат синхронизације
    Sync->>Cloud: GET /{machineId}/v1/verify
    Sync-->>UI: укључено + статус верификације

    UI->>Sync: POST action=sync
    Sync->>Cloud: POST /sync/{machineId}
    Cloud-->>Sync: удаљени подаци
    Sync->>DB: ажурирај новије локалне токене/статус
    Sync-->>UI: синхронизовано

    UI->>Sync: POST action=disable
    Sync->>DB: постави cloudEnabled=false
    Sync->>Cloud: DELETE /sync/{machineId}
    Sync->>Claude: пребаци ANTHROPIC_BASE_URL назад на локални (ако је потребно)
    Sync-->>UI: искључено

Периодична синхронизација се покреће помоћу CloudSyncScheduler када је cloud опција укључена.

Модел података и мапа складиштења

erDiagram
    SETTINGS ||--o{ PROVIDER_CONNECTION : controls
    PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
    PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage

    SETTINGS {
      boolean cloudEnabled
      number stickyRoundRobinLimit
      boolean requireLogin
      string password_hash
      string fallbackStrategy
      json rateLimitDefaults
      json providerProfiles
    }

    PROVIDER_CONNECTION {
      string id
      string provider
      string authType
      string name
      number priority
      boolean isActive
      string apiKey
      string accessToken
      string refreshToken
      string expiresAt
      string testStatus
      string lastError
      string rateLimitedUntil
      json providerSpecificData
    }

    PROVIDER_NODE {
      string id
      string type
      string name
      string prefix
      string apiType
      string baseUrl
    }

    MODEL_ALIAS {
      string alias
      string targetModel
    }

    COMBO {
      string id
      string name
      string[] models
    }

    API_KEY {
      string id
      string name
      string key
      string machineId
    }

    USAGE_ENTRY {
      string provider
      string model
      number prompt_tokens
      number completion_tokens
      string connectionId
      string timestamp
    }

    CUSTOM_MODEL {
      string id
      string name
      string providerId
    }

    PROXY_CONFIG {
      string global
      json providers
    }

    IP_FILTER {
      string mode
      string[] allowlist
      string[] blocklist
    }

    THINKING_BUDGET {
      string mode
      number customBudget
      string effortLevel
    }

    SYSTEM_PROMPT {
      boolean enabled
      string prompt
      string position
    }

Физичке датотеке складиштења:

• примарна runtime база: ${DATA_DIR}/storage.sqlite
• линије лога захтева: ${DATA_DIR}/log.txt (артефакт за компатибилност/дебаговање)
• архиве структурираних payload-ова позива: ${DATA_DIR}/call_logs/
• опционе debug сесије преводиоца/захтева: <repo>/logs/...

Топологија распоређивања (Deployment Topology)

flowchart LR
    subgraph LocalHost[Развојни хост]
        CLI[CLI алати]
        Browser[Прегледач контролне табле]
    end

    subgraph ContainerOrProcess[OmniRoute Runtime]
        Next[Next.js Server\nPORT=20128]
        Core[SSE Core + Executors]
        MainDB[(storage.sqlite)]
        UsageDB[(usage tables + log artifacts)]
    end

    subgraph External[Спољни сервиси]
        Providers[AI провајдери]
        SyncCloud[Cloud Sync сервис]
    end

    CLI --> Next
    Browser --> Next
    Next --> Core
    Next --> MainDB
    Core --> MainDB
    Core --> UsageDB
    Core --> Providers
    Next --> SyncCloud

Мапирање модула (критично за одлучивање)

Модули рута и API-ја

• src/app/api/v1/*, src/app/api/v1beta/*: API-ови за компатибилност
• src/app/api/v1/providers/[provider]/*: посвећене руте по провајдеру (chat, embeddings, images)
• src/app/api/providers*: CRUD провајдера, валидација, тестирање
• src/app/api/provider-nodes*: управљање прилагођеним компатибилним чворовима
• src/app/api/provider-models: управљање прилагођеним моделима (CRUD)
• src/app/api/models/route.ts: API каталога модела (алијаси + прилагођени модели)
• src/app/api/oauth/*: OAuth/device-code токови
• src/app/api/keys*: животни циклус локалних API кључева
• src/app/api/models/alias: управљање алијасима
• src/app/api/combos*: управљање fallback комбинацијама
• src/app/api/pricing: прилагођавања цена за обрачун трошкова
• src/app/api/settings/proxy: конфигурација proxy-ja (GET/PUT/DELETE)
• src/app/api/settings/proxy/test: тест излазне proxy конекције (POST)
• src/app/api/usage/*: API-ови за коришћење и логове
• src/app/api/sync/* + src/app/api/cloud/*: cloud синхронизација и помоћни alati okrenuti ka cloud-u
• src/app/api/cli-tools/*: локални писачи/провера CLI конфигурације
• src/app/api/settings/ip-filter: IP листа дозвола/забрана (GET/PUT)
• src/app/api/settings/thinking-budget: конфигурација буџета thinking токена (GET/PUT)
• src/app/api/settings/system-prompt: глобални системски промпт (GET/PUT)
• src/app/api/settings/compression: глобалне поставке компресије (GET/PUT)
• src/app/api/compression/*: преглед компресије, метаподаци о правилима и језички пакети
• src/app/api/context/caveman/config: алијас за Caveman поставке (GET/PUT)
• src/app/api/context/rtk/*: RTK конфигурација, каталог филтера, тест ендпоинт и опоравак сировог излаза
• src/app/api/context/combos*: CRUD компресионих комбинација и додела routing-комбинација
• src/app/api/context/analytics: алијас за аналитику компресије
• src/app/api/sessions: листа активних сесија (GET)
• src/app/api/rate-limits: статус ограничења брзине по налогу (GET)
• src/app/api/sync/tokens: CRUD синхронизационих токена (GET/POST)
• src/app/api/sync/tokens/[id]: преузимање/брисање синхронизационог токена (GET/DELETE)
• src/app/api/sync/bundle: преузимање пакета конфигурације (GET, ETag верзионисање)
• src/app/api/v1/ws: WebSocket handler за upgrade, за OpenAI-компатибилне WS клијенте

Језгро рутирања и извршавања

• src/sse/handlers/chat.ts: рашчлањивање захтева, обрада комбинација, петља за избор налога
• open-sse/handlers/chatCore.ts: превод, дистрибуција извршиоцима, обрада retry/refresh, подешавање стрима
• open-sse/executors/*: понашање специфично за провајдера у вези мреже и формата

Регистар превода и конвертери формата

• open-sse/translator/index.ts: регистар преводиоца и оркестрација
• Преводиоци захтева: open-sse/translator/request/* (9 модула — 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)
• Преводиоци одговора: open-sse/translator/response/* (11 модула — claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude, openai-to-gemini, openai-to-gemini-sse, responsesToolItem)
• Помоћници: open-sse/translator/helpers/* (12 модула — claudeHelper, geminiHelper, geminiToolsSanitizer, jsonUtil, markdownBoundary, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, strictSystemHoist, toolCallHelper, toolCallShim)
• Константе формата: open-sse/translator/formats.ts
• Bootstrap и регистар: open-sse/translator/bootstrap.ts, open-sse/translator/registry.ts
• Помоћници за формат слика: open-sse/translator/image/

Персистенција

• src/lib/db/*: трајна конфигурација/стање и доменска персистенција на SQLite
• src/lib/db/*: увозите специфичне модуле директно — без barrel-а (стари слој ре-експорта localDb.ts је уклонjен)
• src/lib/usageDb.ts: фасада историје коришћења/логова позива изнад SQLite табела

Покривеност извршилаца провајдера (Strategy Pattern)

Сваки провајдер има специјализовани извршилац који проширује BaseExecutor (у open-sse/executors/base.ts), који обезбеђује изградњу URL-а, конструкцију заглавља, поновне покушаје са експоненцијалним раскораком (retry with exponential backoff), куке за освежавање креденцијала и методу оркестрације execute().

Извршилац	Провајдер(и)	Посебно руковање
DefaultExecutor	OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, итд.	Динамичка конфигурација URL-а/заглавља по провајдеру
AntigravityExecutor	Google Antigravity	Прилагођени ID-ови пројекта/сесије, парсирање Retry-After, 429 опструкција
AzureOpenAIExecutor	Azure OpenAI	Рутирање засновано на распоређивању, обавезна провера параметра api-version
BlackboxWebExecutor	Blackbox AI (веб-режим)	Реверзна веб-сесија са емулацијом TLS отиска (fingerprint)
ClaudeIdentityExecutor	Claude.ai (CCH путања)	Пипелини ограничења + премапирања алата, формирање отиска (fingerprint shaping)
CliProxyApiExecutor	Провајдери компатибилни са CLIProxyAPI	Прилагођено руковање аутентикацијом и протоколом
CloudflareAiExecutor	Cloudflare Workers AI	Убацивање ID-а налога, праћење употребе на бази Neurons
CodexExecutor	OpenAI Codex	Убацује системске инструкције, форсира ниво резоновања
ChatGptWebCodexExecutor	ChatGPT Web (Codex)	Мост Responses API-ја кроз browser-сесију са фиксацијом нити/потеза (thread/turn)
CommandCodeExecutor	Command Code	OAuth + ротација заглавља по сесији
CursorExecutor	Cursor IDE	ConnectRPC протокол, Protobuf енкодирање, потписивање захтева преко checksuma
DevinCliExecutor	Devin CLI	Повезивање животног циклуса Devin задатака преко облак агент модула
GithubExecutor	GitHub Copilot	Освежавање Copilot токена, заглавља која опонашају VSCode
GitlabExecutor	GitLab Duo	GitLab OAuth + рутирање ограничено на пројекат
GlmExecutor	Z.AI GLM (укључујући glmt подешавање)	Свесно буџета размишљања (thinking-budget aware), GLMT константе подешавања
GrokWebExecutor	xAI Grok web	Реверзна веб-сесија, избор режима (мисаони/стандардни)
KieExecutor	KIE	Прилагођено издавање токена са ротирајућим тачкама сесије
KiroExecutor	AWS CodeWhisperer/Kiro	Конверзија AWS EventStream бинарног формата → SSE
MuseSparkWebExecutor	Muse Spark (web)	Реверзна веб-сесија са повезивањем слика-порука
NlpCloudExecutor	NLP Cloud	Специфичан облик тела захтева по провајдеру
OpenCodeExecutor	OpenCode	Подешавање провајдера компатибилно са AI SDK
PerplexityWebExecutor	Perplexity web	Реверзна веб-сесија за настављање разговора
PetalsExecutor	Petals дистрибуирано закључивање (inference)	Децентрализовано рутирање роја (swarm)
PollinationsExecutor	Pollinations AI	API кључ није потребан, захтеви са ограничењем брзине
QoderExecutor	Qoder AI	Подршка за PAT и OAuth, бесплатан ниво са више модела
VertexExecutor	Google Vertex AI	Аутентикација сервисним налогом, крајње тачке по регионима
DevinDesktopExecutor	Devin Desktop	Увезени API кључ + стриминг ћаскања преко Connect-protobuf

Сви остали провајдери (укључујући прилагођене компатибилне чворове) користе DefaultExecutor.

Матрица компатибилности провајдера

Напомена: Матрица испод представља репрезентативан узорак 351 регистрованог провајдера у OmniRoute v3.8.0. За канонски и континуирано ажурирани списак, погледајте docs/reference/PROVIDER_REFERENCE.md (аутоматски генерисано) или изворну истину у src/shared/constants/providers.ts (валидирано Zod-ом при учитавању).

Провајдер	Формат	Аутентикација	Стриминг	Без стриминга	Обнова токена	API за коришћење
Claude	claude	API Key / OAuth	✅	✅	✅	⚠️ Само админ
Gemini	gemini	API Key / OAuth	✅	✅	✅	⚠️ Cloud Console
Antigravity	antigravity	OAuth	✅	✅	✅	✅ Пун API квоте
OpenAI	openai	API Key	✅	✅	❌	❌
Codex	openai-responses	OAuth	✅ форсирано	❌	✅	✅ Ограничења стопе
ChatGPT Web (Codex)	openai-responses	Сесија прегледача	✅ форсирано	❌	❌	❌
GitHub Copilot	openai	OAuth + Copilot Token	✅	✅	✅	✅ Снимци квоте
Cursor	cursor	Прилагођена контролна сума	✅	✅	❌	❌
Kiro	kiro	AWS SSO OIDC	✅ (EventStream)	❌	✅	✅ Ограничења коришћења
Qoder	openai	OAuth / PAT	✅	✅	✅	⚠️ По захтеву
Kilo Code	openai	OAuth	✅	✅	✅	❌
Cline	openai	OAuth	✅	✅	✅	❌
Kimi Coding	openai	OAuth	✅	✅	✅	❌
OpenRouter	openai	API Key	✅	✅	❌	❌
GLM/Kimi/MiniMax	claude	API Key	✅	✅	❌	❌
DeepSeek	openai	API Key	✅	✅	❌	❌
Groq	openai	API Key	✅	✅	❌	❌
xAI (Grok)	openai	API Key	✅	✅	❌	❌
Mistral	openai	API Key	✅	✅	❌	❌
Perplexity	openai	API Key	✅	✅	❌	❌
Together AI	openai	API Key	✅	✅	❌	❌
Fireworks AI	openai	API Key	✅	✅	❌	❌
Cerebras	openai	API Key	✅	✅	❌	❌
Cohere	openai	API Key	✅	✅	❌	❌
NVIDIA NIM	openai	API Key	✅	✅	❌	❌
Cloudflare AI	openai	API токен + Acct ID	✅	✅	❌	❌
Pollinations	openai	Нема (без кључа)	✅	✅	❌	❌
Scaleway AI	openai	API Key	✅	✅	❌	❌
LongCat	openai	API Key	✅	✅	❌	❌
Ollama Cloud	openai	API Key (опционо)	✅	✅	❌	❌
HuggingFace	openai	API Key	✅	✅	❌	❌
Nebius	openai	API Key	✅	✅	❌	❌
SiliconFlow	openai	API Key	✅	✅	❌	❌
Hyperbolic	openai	API Key	✅	✅	❌	❌
Vertex AI	gemini	Сервисни налог	✅	✅	✅	⚠️ Cloud Console
Command Code	openai	OAuth	✅	✅	✅	⚠️ По захтеву
Z.AI / GLM	openai	API Key / OAuth	✅	✅	❌	❌
GLMT (preset)	claude	API Key	✅	✅	❌	⚠️ По захтеву
Kimi Coding	openai	OAuth / API Key	✅	✅	✅	❌
KIE	openai	API Key	✅	✅	❌	❌
Devin Desktop	openai	Увезени API кључ	✅ (Connect→SSE)	✅	❌	⚠️ По захтеву
GitLab Duo	openai	OAuth (GitLab)	✅	✅	✅	❌
Devin CLI	openai	Локална CLI пријава	✅	✅	❌	✅ Task API
Codex Cloud	openai-responses	OAuth	✅	❌	✅	✅ Ограничења стопе
Jules	openai	OAuth	✅	✅	✅	✅ Task API
AgentRouter	openai	API Key	✅	✅	❌	❌
Grok-Web	openai	Session cookie	✅	✅	❌	❌
Perplexity-Web	openai	Session cookie	✅	✅	❌	❌
BlackBox-Web	openai	Session cookie + TLS	✅	✅	❌	❌
Muse-Spark-Web	openai	Session cookie	✅	✅	❌	❌
ModelScope	openai	API Key	✅	✅	❌	⚠️ Политика квоте
BazaarLink	openai	API Key	✅	✅	❌	❌
Petals	openai	Нема	✅	✅	❌	❌
Qoder	openai	OAuth / PAT	✅	✅	✅	⚠️ По захтеву
OpenCode (Go/Zen)	openai	OAuth	✅	✅	✅	❌
CLIProxyAPI	openai	Прилагођено	✅	✅	❌	❌

Покривеност превода формата

Детектовани извориформати укључују:

• openai
• openai-responses
• claude
• gemini

Циљни формати укључују:

• OpenAI chat/Responses
• Claude
• Gemini/Antigravity envelope
• Kiro
• Cursor

Преводи користе OpenAI као централни (hub) формат — све конверзије пролазе кроз OpenAI као посредни формат:

Изворни формат → OpenAI (hub) → Циљни формат

Преводи се бирају динамички на основу облика изворног payload-а и циљног формата провајдера.

Додатни слојеви обраде у пипелајну превода:

• Санитизација одговора — Уклања нестандардна поља из одговора у OpenAI формату (и стриминг и не-стриминг) ради обезбеђивања строге усклађености са SDK-ом
• Нормализација улога — Конвертује developer → system за не-OpenAI циљеве; спаја system → user за моделе који одбијају улогу system (GLM, ERNIE)
• Екстракција think ознака — Парсира `` блокове из садржаја у поље reasoning_content
• Структурисани излаз — Конвертује OpenAI response_format.json_schema у Gemini-јев responseMimeType + responseSchema

Подржани API крајњи циљеви (endpoints)

Крајњи циљ (Endpoint)	Формат	Handler
POST /v1/chat/completions	OpenAI Chat	src/sse/handlers/chat.ts
POST /v1/messages	Claude Messages	Исти handler (аутоматска детекција)
POST /v1/responses	OpenAI Responses	open-sse/handlers/responsesHandler.ts
POST /v1/embeddings	OpenAI Embeddings	open-sse/handlers/embeddings.ts
GET /v1/embeddings	Листа модела	API рута
POST /v1/images/generations	OpenAI Images	open-sse/handlers/imageGeneration.ts
GET /v1/images/generations	Листа модела	API рута
POST /v1/providers/{provider}/chat/completions	OpenAI Chat	Наменски по провајдеру са валидацијом модела
POST /v1/providers/{provider}/embeddings	OpenAI Embeddings	Наменски по провајдеру са валидацијом модела
POST /v1/providers/{provider}/images/generations	OpenAI Images	Наменски по провајдеру са валидацијом модела
POST /v1/messages/count_tokens	Claude Token Count	API рута
GET /v1/models	Листа OpenAI модела	API рута (chat + embedding + image + прилагођени модели)
GET /api/models/catalog	Каталог	Сви модели груписани по провајдеру + типу
POST /v1beta/models/*:streamGenerateContent	Gemini native	API рута
GET/PUT/DELETE /api/settings/proxy	Proxy конфигурација	Конфигурација мрежног proxy-ja
POST /api/settings/proxy/test	Проверa proxy везе	Endpoint за тестирање здравственог стања/повезивости proxy-ja
GET/POST/DELETE /api/provider-models	Модели провајдера	Метаподаци о моделима провајдера који подржавају прилагођене и управљане доступне моделе

Bypass Handler (Rukovalac za preskakanje)

Rukovalac za preskakanje (open-sse/utils/bypassHandler.ts) presreće poznate „одбациве" захтеве Claude CLI-ja — пробна загревања (warmup pings), издвајања наслова и бројања токена — и враћа лажан одговор без трошења токена узводног провајдера. Ово се покреће само када User-Agent садржи claude-cli.

Логовање захтева и артефакти

Старији логер захтева заснован на фајловима (open-sse/utils/requestLogger.ts) задржан је само за legacy компатибилност. Тренутни runtime уговор користи:

• APP_LOG_TO_FILE=true за апликационе и ревизорске логове који се записују под <repo>/logs/
• SQLite записе логова позива у call_logs
• ${DATA_DIR}/call_logs/YYYY-MM-DD/... артефакте када је омогућен pipeline за логовање позива

Режими отказивања и отпорност (Resilience)

1) Доступност налога/провајдера

• period хлађења (cooldown) конекције код узводних отказивања која се могу поновити
• резервни налог (fallback) пре трајног неуспеха захтева
• резервни модел из комбо листе када је тренутна путања модел/провајдер исцрпљена

2) Истицање токена

• претходна провера и обнављање са поновним покушајем за провајдере који подржавају освежавање
• поновни покушај 401/403 након покушаја обнављања у главној путањи

3) Безбедност стриминга

• контролер стрима свестан прекида везе (disconnect-aware)
• преводилачки стрим са завршним пражњењем (end-of-stream flush) и обрадом [DONE]
• резервна процена коришћења (usage estimation fallback) када недостају метаподаци о коришћењу провајдера

4) Деградација облак синхронизације (Cloud Sync)

• грешке синхронизације се приказују, али локални runtime наставља рад
• планер (scheduler) има логику способну за поновне покушаје, али периодично извршавање тренутно подразумевано позива синхронизацију само са једним покушајем

5) Интегритет података

• SQLite шема миграције и куке за аутоматско ажурирање при покретању
• путања компатибилности за миграцију legacy JSON → SQLite

6) SSRF / Заштита излазних URL адреса

• src/shared/network/outboundUrlGuard.ts блокира све приватне/loopback/link-local циљне URL адресе пре него што стигну до извршиоца провајдера
• Руте за откривање и валидацију модела провајдера користе src/shared/network/safeOutboundFetch.ts, који примењује заштиту пре сваког излазног захтева
• Грешке заштите се приказују као URL_GUARD_BLOCKED са HTTP 422 статусом и логују се у трагу ревизије усклађености (compliance audit trail) путем providerAudit.ts

Опсервабилност и оперативни сигнали

Извори видљивости runtime-a:

• конзолни логови из src/sse/utils/logger.ts
• агрегати коришћења по захтеву у SQLite (usage_history, call_logs, proxy_logs)
• четворостепени детаљни снимци корисног садржаја (payload) у SQLite (request_detail_logs) када је settings.detailed_logs_enabled=true
• текстуални лог статуса захтева у log.txt (опционо/compat)
• опциони фајлови апликационих логова под logs/ када је APP_LOG_TO_FILE=true
• опциони артефакти захтева под ${DATA_DIR}/call_logs/ када је омогућен pipeline за логовање позива
• endpoint-и за коришћење на контролној табли (/api/usage/*) за потрошњу у UI-ју

Детаљно снимање корисног садржаја захтева чува до четири JSON фазе корисног садржаја по руtiranom позиву:

• сирови захтев примљен од клијента
• преведени захтев који је стварно послат узводно
• одговор провајдера реконструисан као JSON; стримовани одговори се сажимају у финални резиме плус метаподатке стрима
• финални одговор клијенту који враћа OmniRoute; стримовани одговори се чувају у истом сажетом облику резимеа

Bezbednosno osetljive granice

• JWT tajni ključ (JWT_SECRET) obezbeđuje verifikaciju/potpisivanje sesijskog kolačića kontrolne table
• Bootstrap inicijalne lozinke (INITIAL_PASSWORD) treba eksplicitno konfigurisati za prvo pokretanje
• HMAC tajni ključ API ključa (API_KEY_SECRET) obezbeđuje generisani format lokalnog API ključa
• Tajne provajdera (API ključevi/tokeni) se čuvaju u lokalnoj bazi podataka i treba ih zaštititi na nivou fajl sistema
• Krajnje tačke sinhronizacije u облaku zavise od autentifikacije putem API ključa i semantike identifikatora mašine

Matrica okruženja i runtime-a

Promenljive okruženja koje aktivno koristi kod:

• Aplikacija/autentifikacija: JWT_SECRET, INITIAL_PASSWORD
• Skladištenje: DATA_DIR
• Opciono premošćavanje osnovne putanje skladištenja (Linux/macOS kada DATA_DIR nije podešeno): XDG_CONFIG_HOME
• Bezbednosno heširanje: API_KEY_SECRET, MACHINE_ID_SALT
• Logovanje: APP_LOG_TO_FILE, APP_LOG_RETENTION_DAYS, CALL_LOG_RETENTION_DAYS
• URL adresiranje sinhronizacije/облака: NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_CLOUD_URL
• Izlazni proxy: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY i varijante malim slovima
• SOCKS5 funkcijske oznake (feature flags): ENABLE_SOCKS5_PROXY, NEXT_PUBLIC_ENABLE_SOCKS5_PROXY
• Pomoćnici platforme/runtime-a (nisu specifični za konfiguraciju aplikacije): APPDATA, NODE_ENV, PORT, HOSTNAME

Poznate arhitektonske napomene

1. usageDb i localDb dele istu politiku osnovnog direktorijuma (DATA_DIR -> XDG_CONFIG_HOME/omniroute -> ~/.omniroute) uz migraciju zastarelih fajlova.
2. /api/v1/route.ts prosleđuje isti unifikovani graditelj katalog koji koristi /api/v1/models (src/app/api/v1/models/catalog.ts) da bi se izbeglo semantičko rasipanje.
3. Request logger upisuje kompletna zaglavlja/tela kada je omogućen; direktorijum logova treba tretirati kao osetljiv.
4. Ponašanje облака zavisi od pravilno podešenog NEXT_PUBLIC_BASE_URL i dostupnosti krajnje tačke облака.
5. Direktorijum open-sse/ se objavljuje kao npm workspace paket @omniroute/open-sse. Izvorni kod ga uvozi preko @omniroute/open-sse/... (razrešava se putem Next.js transpilePackages). Putanje fajlova u ovom dokumentu i dalje koriste naziv direktorijuma open-sse/ radi konzistentnosti.
6. Grafikoni na kontrolnoj tabli koriste Recharts (zasnovan na SVG-u) za pristupačne, interaktivne vizualizacije analitike (bar grafikoni korišćenja modela, tabele pregleda po provajderima sa stopama uspešnosti).
7. E2E testovi koriste Playwright (tests/e2e/), pokreću se putem npm run test:e2e. Jedinični testovi koriste Node.js test runner (tests/unit/), pokreću se putem npm run test:unit. Izvorni kod u src/ je napisan u TypeScript-u (.ts/.tsx); workspace open-sse/ ostaje u JavaScript-u (.js).
8. Stranica podešavanja organizovana je u 7 tabova: General, Appearance, AI, Security, Routing, Resilience, Advanced. Stranica Resilience konfiguriše samo red čekanja zahteva, hlađenje veze (connection cooldown), prekidač provajdera (provider breaker) i ponašanje čekanja na hlađenje; stanje prekidača u realnom vremenu prikazano je na stranici Health.
9. Strategija Context Relay (context-relay) je podeljena na dva sloja: combo.ts odlučuje da li treba generisati predaju (handoff), chat.ts ubacuje predaju nakon razrešavanja naloga. Podaci o predaji se čuvaju u SQLite tabeli context_handoffs. Ova podela je namerna jer samo chat.ts zna da li se stvarni nalog promenio.
10. Sprovođenje proxy politike je sada sveobuhvatno: tokenHealthCheck.ts razrešava proxy po konekciji, /api/providers/validate koristi runWithProxyContext, a proxyFetch.ts koristi undici.fetch() da bi se održala kompatibilnost dispečera na Node 22.
11. Detekcija politike Node.js runtime-a: /api/settings/require-login vraća polja nodeVersion i nodeCompatible. Stranica za prijavu prikazuje traku upozorenja kada runtime izađe iz opsega podržanih bezbednih Node.js linija.

Контролна листа за оперативну верификацију

• Изградња из извора: npm run build
• Изградња Docker слике: docker build -t omniroute .
• Покретање сервиса и верификација:
• GET /api/settings
• GET /api/v1/models
• Циљна базна URL адреса CLI-ja треба да буде http://<host>:20128/v1 када је PORT=20128