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

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

---

> **ვერსია:** v3.8.51
> **ბოლო განახლება:** 2026-06-28
> **აუდიტორია:** ინჟინრები, რომლებსაც წვლილი შეაქვთ OmniRoute-ში ან მის საფუძველზე ინტეგრაციებს ქმნიან.
>
> მაღალი დონის არქიტექტურული დიაგრამებისა და თითოეული ქვესისტემის საფუძვლად არსებული მსჯელობის გასაცნობად წაიკითხეთ
> [ARCHITECTURE.md](./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](../frameworks/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/exported/db-schema-overview.svg)

> წყარო: [diagrams/db-schema-overview.mmd](../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/              პროვაიდერის 156 შემსრულებელი მოდული (შემსრულებელი კლასები + თითოეული პროვაიდერის დამხმარეები)
├── 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/`

ზედა დონის 156 შემსრულებელი მოდული (`*.ts`, გარდა `base.ts`, `index.ts` და ტესტებისა — რაოდენობას
`npm run check:docs-counts` ზომავს). ყოველი შემსრულებელი კლასი აფართოებს `BaseExecutor`-ს (`base.ts`),
პირდაპირ ან `DefaultExecutor`-ის ან სხვა შემსრულებლის გავლით; დარჩენილი მოდულები თითოეული პროვაიდერისთვის
განკუთვნილი დამხმარეებია (ხელსაწყოების სქემები, fetch/TTS ადაპტერები, თავისებურებების დამმუშავებლები). შემსრულებლები მოიცავს:

`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-თან თავსებადი შემსრულებლის გამოყენებით. პროვაიდერების სრული კატალოგი (375 პროვაიდერი) მდებარეობს
> `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` (20 სტრატეგია), `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` (მოლოდინის პერიოდი + დაბლოკვა), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                               |
| კვოტები                  | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| კეშირება                 | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| მარშრუტიზაციის ინტელექტი | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| მოდელების დამუშავება     | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| შეკუმშვა                 | `compression/` — შეკუმშვის ძრავის სრული დაკავშირება                                                                                                                                                                                                      |
| ტოკენი + სესია           | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| დონე / მანიფესტი         | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / ქსელი               | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| პაკეტები                 | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| გამოყენება               | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **110 უნიკალური ხელსაწყო**, დაკავშირებული `server.ts`-ში (45 კანონიკური ხელსაწყო `schemas/tools.ts`-ში +
  მეხსიერების, უნარების, GitHub-უნარების, პულის, გეიმიფიკაციის, პლაგინის, Notion-ის, Obsidian-ის,
  ლოკალური კორპუსისა და შეკუმშვის მოდულები — გაერთიანება დათვლილია `countUniqueMcpTools`-ის მიერ).
- **3 ტრანსპორტი**: stdio, HTTP Streamable, SSE.
- გაშვების დროს კონტროლდება **33 წვდომის სფერო** — საბაზისო სია მოცემულია `src/shared/constants/mcpScopes.ts`-ში, სრული ნაკრები კი თითოეული ხელსაწყოს მოდულის მიერ დეკლარირებული წვდომის სფეროების გაერთიანებაა.
- აუდიტის ცხრილი: `mcp_tool_audit` (ივსება `audit.ts`-ის მიერ).
- ფაილები: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`,
  `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`,
  `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`,
  ასევე ტესტები `__tests__/`-ში.
- ხელსაწყოების სრული კატალოგისთვის იხილეთ [MCP-SERVER.md](../frameworks/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`, ასევე PR-ების მონიტორინგისთვის განკუთვნილი მხოლოდ წაკითხვადი დამხმარე სკრიპტები:
  `ci-discriminate.sh` (PR-ის წარუმატებელი შემოწმებების ხელწერებს ახარისხებს საკუთარ /
  მემკვიდრეობით / უცნობ კატეგორიებად, ეტალონურ PR-თან ან საბაზისო წარუმატებლობის საკითხთან შედარებით) და `audit-worktree.sh`
  (შეცვლილი ფაილები, დაცული ზედაპირები, წაშლილი მტკიცებები, ჩახშობების რაოდენობა, დარჩენილი
  დროებითი tsconfig-ები, PR-ის head ადგილობრივ HEAD-თან შედარებით — მუშაკის PR-ის მიღებამდე).
- **`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. მოთხოვნის დამუშავების კონვეიერი (შეჯამება)

![მოთხოვნის დამუშავების კონვეიერი (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> წყარო: [diagrams/request-pipeline.mmd](../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](./RESILIENCE_GUIDE.md) და შესაბამისი განყოფილება
[CLAUDE.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](../frameworks/MCP-SERVER.md).

### ახალი A2A უნარის დამატება

იხილეთ [A2A-SERVER.md § ახალი უნარის დამატება](../frameworks/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](./ARCHITECTURE.md) — მაღალი დონის არქიტექტურა და მოდულების
  პასუხისმგებლობები.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — საჯარო და მართვის API-ის ცნობარი.
- [FEATURES.md](../guides/FEATURES.md) — ფუნქციების მატრიცა და ვერსიების მნიშვნელოვანი სიახლეები.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — circuit breaker-ის, cooldown-ისა და
  lockout-ის დეტალური მიმოხილვა.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo-ს შეფასება და სტრატეგიები.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — MCP ინსტრუმენტების სრული კატალოგი და ტრანსპორტები.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A პროტოკოლის უნარები და აღმოჩენა.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK და Caveman შეკუმშვა.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI ინტეგრაციები.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (თუ არსებობს), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — განთავსების სამიზნეები.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — გავრცელებული საოპერაციო პრობლემები.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — კონტრიბუტორის სამუშაო პროცესი.
- [CLAUDE.md](../../CLAUDE.md) — რეპოზიტორიის წესები Claude Code-ისთვის (ზემოთ მოცემული
  მრავალი შეთანხმების პირველწყარო).
- [AGENTS.md](../../AGENTS.md) — აგენტების მიერ გამოყენებული არქიტექტურის უფრო სიღრმისეული ცნობარი.