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

OmniRoute Codebase Documentation (ქართული)

🌐 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 · 🇰🇭 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, დამოუკიდებელი გამომავალი, გლობალური middleware-ის გარეშე)
ენა	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, cache), Playwright (e2e + protocols-e2e)
აგება	Next.js-ის დამოუკიდებელი გამომავალი scripts/build/build-next-isolated.mjs-ის მეშვეობით
ლინტინგი/ფორმატირება	ESLint-ის ბრტყელი კონფიგურაცია + Prettier (lint-staged Husky-ის pre-commit-ის მეშვეობით)
მოდულების სისტემა	ყველგან ESM ("type": "module")
სამუშაო სივრცეები	npm workspace — 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 მანიფესტი, სერვის-ვორკერი
├── 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/                  ძირითადი ბიბლიოთეკები (DB, ავტორიზაცია, OAuth, უნარები, მეხსიერება, …)
├── domain/               სუფთა დომენური შრე (პოლიტიკა, სარეზერვო მექანიზმი, ღირებულება, დაბლოკვა, …)
├── server/               მხოლოდ სერვერის მოდულები (ავტორიზაცია, cors, ავთენტიფიკაცია)
├── shared/               ტიპები, მუდმივები, ვალიდაცია, კონტრაქტები, დამხმარე ფუნქციები (უსაფრთხოა საზღვრებს შორის)
├── mitm/                 შუამავალი პროქსის დამხმარე ფუნქციები CLI-სთან ინტეგრაციისთვის
├── models/               ლოკალური მოდელების მეტამონაცემები / ფსევდონიმები
├── sse/                  ძველი SSE დამმუშავებლები, რომლებიც ჯერ კიდევ src/-შია (და არა open-sse/-ში)
├── store/                კლიენტის მხარის მდგომარეობის საცავები
├── middleware/           მარშრუტის დონის middleware-ის დამხმარე ფუნქციები (არა Next.js-ის გლობალური middleware)
├── scripts/              კოდის ხეში არსებული სკრიპტები, რომელთა იმპორტირებაც აპლიკაციის კოდს შეუძლია
├── types/                გარემოსეული და გაზიარებული TS ტიპები
├── i18n/                 ლოკალების პაკეტები
├── instrumentation.ts    Next.js-ის ინსტრუმენტაციის ჰუკი
├── instrumentation-node.ts
└── proxy.ts              უმაღლესი დონის პროქსის ინიციალიზაციის დამხმარე

3.1 src/app/ — App Router

App Router ხელმისაწვდომს ხდის როგორც მართვის პანელის ინტერფეისს, ისე საჯარო/მართვის HTTP API-ს. გლობალური middleware არ არსებობს — ჩაჭერა თითოეული მარშრუტის დონეზე ხორციელდება.

უმაღლესი დონის სეგმენტები 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/         OpenAI-სთან თავსებადი საჯარო API
├── 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  — მიმდინარე + DB სტატუსი + ვერსიის მეტამონაცემები
│   └── 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  — მიმდინარე + DB სტატუსი + ვერსიის მეტამონაცემები
│   └── auto-start/route.ts POST — auto_start ალმის გადართვა
└── [name]/
    └── logs/route.ts       GET  — SSE ჟურნალის კუდი (საერთოა ყველა სერვისისთვის)

შესაბამისი მართვის პანელის UI: src/app/(dashboard)/dashboard/providers/services/ — ორ-ჩანართიანი გვერდი (CLIProxyAPI + 9Router). უკუპროქსი 9Router-ის ჩაშენებული UI-სთვის: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

დეტალური განხილვა: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI-თან თავსებადი საჯარო API

v1/
├── accounts/[id]/                       ანგარიშის მოძიება
├── agents/tasks/[id]/, agents/tasks/    A2A-სტილის ამოცანების საბოლოო წერტილები
├── api/                                 v1/api-ის ქვეშ ხელმისაწვდომი შიდა API-ის დამხმარე ფუნქციები
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    ჩატის დასრულებები (მთავარი საბოლოო წერტილი)
├── completions/                         მოძველებული ტექსტური დასრულებები
├── embeddings/                          ჩაშენებები
├── files/[id]/, files/                  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-ის პასუხებში გამოყენებული UI/ჩვენების დამხმარე მოდულები
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 (OpenAPI სპეციფიკაციიდან გამოყოფს REST ბოლო წერტილებს), cliRegistryParser.ts (bin/cli-registry-დან გამოყოფს CLI ქვეკომანდებს), 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/	Zed რედაქტორის OAuth ნაკადი

უმაღლესი დონის ფაილები src/lib/-ში:

• ძველი localDb.ts barrel წაიშალა — მომხმარებლები პირდაპირ ახორციელებენ კონკრეტული 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/

Singleton 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/ — დომენის შრე

სუფთა ბიზნესლოგიკა, I/O-ის გარეშე. იმპორტირდება მარშრუტებისა და დამმუშავებლების მიერ.

ფაილი	დანიშნულება
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         თითოეული მოთხოვნის authz კონტექსტი
│   ├── headers.ts
│   ├── pipeline.ts        Authz კონვეიერი
│   ├── 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/ — npm-ზე გამოქვეყნებული საჯარო API-ის კონტრაქტები.
• 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, ასევე დაფის ჰუკები/კომპონენტები 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, პროქსირებული fetch, …
└── 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 მარშრუტიზაცია	combo.ts (19 სტრატეგია), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Auto Combo ძრავა	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 (cooldown + lockout), errorClassifier.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-skills-ის, პულის, გეიმიფიკაციის, პლაგინების, 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 დამხმარე ფუნქცია (ჯერ სერვერი/DB-ზე სარეზერვო გადასვლა)
    ├── output.mjs          გამოტანის ფორმატერები (json/jsonl/table/csv)
    ├── i18n.mjs            t() დამხმარე ფუნქცია ლოკალებით
    ├── api.mjs             API fetch დამხმარე ფუნქცია
    ├── 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/	მოდულთაშორისი და DB-ის მდგომარეობის ტესტები
tests/e2e/	Playwright-ის UI ტესტები
tests/e2e/protocol-clients.test.ts	MCP/A2A პროტოკოლის e2e ტესტები
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, cache)
npm run test:e2e	Playwright-ის UI ტესტების ნაკრებს
npm run test:protocols:e2e	MCP + A2A პროტოკოლის e2e ტესტებს
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. თუ პროვაიდერი OpenAI-ის ფორმატს არ იყენებს, დაამატეთ მთარგმნელი open-sse/translator/-ში.
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.

ახალი DB მოდულის დამატება

1. შექმენით src/lib/db/yourModule.ts და შემოიტანეთ getDbInstance() ./core.ts-დან.
2. თქვენი დომენისთვის გაიტანეთ CRUD ფუნქციები.
3. ახალი ცხრილების შემთხვევაში: დაამატეთ მიგრაცია src/lib/db/migrations/-ში, თანმიმდევრული ნომრით; ის უნდა იყოს იდემპოტენტური და ტრანზაქციული.
4. გამომყენებლებმა პირდაპირ უნდა შემოიტანონ @/lib/db/yourModule-დან (barrel-ის გარეშე — ძველი 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/ მოდულები. არასოდეს გამოიყენოთ barrel-იმპორტი — უშუალოდ გამოიყენეთ კონკრეტული src/lib/db/* მოდულები.
• DB ერთეულების ტიპიზაცია (#3512): ფუნქციამ, რომელიც DB ცხრილის სტრიქონის სტრუქტურას წერს ან კითხულობს, უნდა მიიღოს/დააბრუნოს დასახელებული TS ინტერფეისი, რომელიც ამ ცხრილის სვეტებს 1:1-ზე ასახავს, და არა any ან გამოძახების ადგილზე ჩაშენებული ანონიმური ტიპი. განათავსეთ ინტერფეისი ფუნქციის გვერდით (მაგ., export interface UsageEntry src/lib/usage/usageHistory.ts-ში, saveRequestUsage-ის ზემოთ), დატოვეთ ცალკეული ველები არასავალდებულო/nullable, როდესაც სხვადასხვა ჩამწერი სტრიქონს ეტაპობრივად ავსებს, და მიანიჭეთ 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() / არაპირდაპირი eval. შეამოწმეთ ყველა შემავალი მონაცემი 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: pre-commit უშვებს lint-staged + check:docs-sync + check:any-budget:t11; pre-push უშვებს check:any-budget:t11 + check:tracked-artifacts (სწრაფი შემოწმებები; არ მოიცავს test:unit-ს).

---

12. მკაცრი წესები (CLAUDE.md-დან)

1. არასოდეს შეიტანოთ commit-ში საიდუმლოები ან ავტორიზაციის მონაცემები.
2. არასოდეს გამოიყენოთ barrel import — უშუალოდ გამოიყენეთ კონკრეტული src/lib/db/* მოდულები.
3. არასოდეს გამოიყენოთ eval() / new Function() / ნაგულისხმევი eval.
4. არასოდეს შეიტანოთ commit პირდაპირ main-ში.
5. არასოდეს დაწეროთ დაუმუშავებელი SQL მარშრუტებში — ყოველთვის გამოიყენეთ src/lib/db/ მოდულები.
6. არასოდეს უგულებელყოთ შეცდომები უხმოდ SSE ნაკადებში.
7. ყოველთვის შეამოწმეთ შემავალი მონაცემები Zod სქემებით.
8. საწარმოო კოდის შეცვლისას ყოველთვის დაამატეთ ტესტები.
9. დაფარვა უნდა დარჩეს ≥ 60% (ინსტრუქციები, ხაზები, ფუნქციები, განშტოებები).

---

13. აგრეთვე იხილეთ

• ARCHITECTURE.md — მაღალი დონის არქიტექტურა და მოდულების პასუხისმგებლობები.
• API_REFERENCE.md — საჯარო და მართვის API-ის ცნობარი.
• FEATURES.md — ფუნქციების მატრიცა და ვერსიების მნიშვნელოვანი სიახლეები.
• RESILIENCE_GUIDE.md — circuit breaker-ის, cooldown-ისა და lockout-ის დეტალური მიმოხილვა.
• 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 — აგენტების მიერ გამოყენებული არქიტექტურის უფრო სიღრმისეული ცნობარი.