# OmniRoute Codebase Documentation (Türkçe)

🌐 **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) · 🇬🇪 [ka](../../../ka/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) · 🇺🇦 [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)

---

> **Sürüm:** v3.8.51
> **Son güncelleme:** 2026-06-28
> **Hedef kitle:** OmniRoute'a katkıda bulunan veya onun üzerinde entegrasyonlar geliştiren mühendisler.
>
> Üst düzey mimari diyagramlar ve her alt sistemin arkasındaki gerekçeler için
> [ARCHITECTURE.md](./ARCHITECTURE.md) dosyasını okuyun. Belirli alt sistemler
> (Auto Combo, MCP sunucusu, A2A sunucusu, Skills, Memory, Cloud Agents, Resilience,
> Compression vb.) hakkında ayrıntılı bilgi için bu `docs/` dizinindeki ilgili dosyalara bakın.

Bu dosya, yeni bir mühendisin dizin ağacında gezinebilmesi, çalışma zamanı katmanlarını
anlayabilmesi ve yeni modüller oluşturmadan kodu nereye ekleyeceğini bilmesi için
**depoda bugün mevcut olanları** açıklar.

---

## 1. Teknoloji Yığını

| Konu             | Tercih                                                                                                                             |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Web çatısı       | **Next.js 16** (App Router, bağımsız çıktı, global ara katman yok)                                                                 |
| Dil              | **TypeScript 6.0+** — hedef `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                               |
| Çalışma ortamı   | **Node.js** `>=22.22.2 <23` veya `>=24.0.0 <27` (`engines` + `SUPPORTED_NODE_RANGE` aracılığıyla zorunlu tutulur)                  |
| Veritabanı       | `better-sqlite3` aracılığıyla **SQLite** (tekil örnek, WAL günlükleme)                                                             |
| Masaüstü         | **Electron 41** + `electron-builder` 26.10 (`electron/` altında ayrı çalışma alanı)                                                |
| Testler          | **Node yerel test çalıştırıcısı** (birim/entegrasyon), **Vitest** (MCP, autoCombo, önbellek), **Playwright** (e2e + protocols-e2e) |
| Derleme          | `scripts/build/build-next-isolated.mjs` aracılığıyla bağımsız Next.js                                                              |
| Lint/biçim       | ESLint düz yapılandırması + Prettier (Husky ön işleme kancası aracılığıyla `lint-staged`)                                          |
| Modül sistemi    | Her yerde ESM (`"type": "module"`)                                                                                                 |
| Çalışma alanları | npm çalışma alanı — `open-sse` tek alt çalışma alanıdır                                                                            |

Yol takma adları (`tsconfig.json`):

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

Varsayılan HTTP portu: **`20128`** (API ve pano aynı süreci paylaşır). Veri
dizini, varsayılan değeri `~/.omniroute/` olan `DATA_DIR` ortam değişkenidir.

---

## 2. Depo Düzeni

```
OmniRoute/
├── src/                  Next.js uygulaması (App Router, kütüphaneler, alan, sunucu, paylaşılanlar)
├── open-sse/             Akış motoru çalışma alanı (@omniroute/open-sse)
├── electron/             Masaüstü sarmalayıcısı (Electron 41 ana süreç + preload)
├── bin/                  CLI giriş noktaları (omniroute, reset-password)
├── tests/                Birim, entegrasyon, e2e, protocols-e2e, çevirici, güvenlik, fikstürler
├── scripts/              Derleme, eşitleme, denetim, geçiş ve çalışma zamanı yardımcı betikleri
├── docs/                 Herkese açık belgeler (bu dizin)
├── public/               Statik varlıklar, PWA manifestosu, service worker
├── config/               Çalışma zamanı yapılandırma örnekleri
├── images/               Pazarlama/ekran görüntüsü varlıkları
├── _ideia/, _references/, _mono_repo/, _tasks/   Dahili taslak / planlama (dağıtıma dahil edilmez)
├── CLAUDE.md             Claude Code için depo kuralları
├── AGENTS.md             Ajanlar için daha ayrıntılı mimari referans
├── package.json          v3.8.51, çalışma alanı kökü
└── tsconfig.json         Yol takma adları + temel derleyici seçenekleri
```

---

## 3. `src/` — Next.js Uygulaması

```
src/
├── app/                  App Router sayfaları + API rotaları
├── lib/                  Temel kütüphaneler (DB, kimlik doğrulama, OAuth, beceriler, bellek, …)
├── domain/               Saf alan katmanı (politika, geri dönüş, maliyet, kilitleme, …)
├── server/               Yalnızca sunucuya yönelik modüller (yetkilendirme, cors, kimlik doğrulama)
├── shared/               Türler, sabitler, doğrulama, sözleşmeler, yardımcılar (sınırlar arası güvenli)
├── mitm/                 CLI entegrasyonu için ortadaki adam proxy yardımcıları
├── models/               Yerel model meta verileri / takma adlandırma
├── sse/                  Hâlâ src/ altında bulunan eski SSE işleyicileri (open-sse/ altında değil)
├── store/                İstemci tarafı durum depoları
├── middleware/           Rota düzeyinde ara yazılım yardımcıları (Next.js global ara yazılımı değil)
├── scripts/              Uygulama kodu tarafından içe aktarılabilen depo içi betikler
├── types/                Ortam ve paylaşılan TS türleri
├── i18n/                 Yerel ayar paketleri
├── instrumentation.ts    Next.js enstrümantasyon kancası
├── instrumentation-node.ts
└── proxy.ts              Üst düzey proxy önyükleme yardımcısı
```

### 3.1 `src/app/` — App Router

App Router, hem kontrol paneli kullanıcı arayüzünü hem de genel/yönetim HTTP API'sini sunar.
**Global ara yazılım yoktur** — müdahale rota bazında gerçekleştirilir.

`src/app/` altındaki üst düzey segmentler:

| Yol                                                                           | Amaç                                                          |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `api/`                                                                        | Tüm HTTP API rotaları (aşağıdaki döküme bakın)                |
| `a2a/`                                                                        | A2A JSON-RPC 2.0 uç noktası (`POST /a2a`)                     |
| `.well-known/agent.json/`                                                     | A2A Agent Card keşif belgesi                                  |
| `(dashboard)/`                                                                | Kontrol paneli kullanıcı arayüzü (rota grubu, URL ön eki yok) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | Kimlik doğrulama akışları                                     |
| `landing/`                                                                    | Pazarlama/açılış sayfası                                      |
| `docs/`                                                                       | Gömülü API belgeleri görüntüleyicisi                          |
| `status/`, `maintenance/`, `offline/`                                         | Operasyonel sayfalar                                          |
| `privacy/`, `terms/`                                                          | Yasal sayfalar                                                |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | Statik hata sayfaları                                         |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Framework hata/yükleme sınırları                              |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | Kök kabuk                                                     |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — Kullanıcı arayüzü sayfaları

`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`; ayrıca kök `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — Üst düzey API grupları

```
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/   Gömülü hizmet yönetimi (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI uyumlu genel API
├── v1beta/     Gemini tarzı uyumluluk
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — Gömülü Hizmetlerin yönetimi

9Router ve CLIProxyAPI'yi yükleme, başlatma, durdurma ve izleme rotaları.
`npm install` komutunu çalıştırabildikleri ve alt süreçler oluşturabildikleri için tüm yollar
**LOCAL_ONLY** (yalnızca geri döngü, kesin kural #17) olarak sınıflandırılır.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() yardımcısı
│   ├── install/route.ts    POST — execFile aracılığıyla npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — daha yeni sürüm için npm install
│   ├── rotate-key/route.ts POST — yeni API anahtarı oluştur + yeniden başlat
│   ├── status/route.ts     GET  — canlı durum + DB durumu + sürüm meta verileri
│   └── auto-start/route.ts POST — auto_start bayrağını aç/kapat
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() yardımcısı
│   ├── 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 — daha yeni sürüm için npm install
│   ├── status/route.ts     GET  — canlı durum + DB durumu + sürüm meta verileri
│   └── auto-start/route.ts POST — auto_start bayrağını aç/kapat
└── [name]/
    └── logs/route.ts       GET  — SSE günlük akışı (tüm servisler tarafından paylaşılır)
```

İlgili pano kullanıcı arayüzü:
`src/app/(dashboard)/dashboard/providers/services/` — iki sekmeli sayfa (CLIProxyAPI + 9Router).
9Router gömülü kullanıcı arayüzü için ters proxy:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

Ayrıntılı inceleme: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — OpenAI uyumlu genel API

```
v1/
├── accounts/[id]/                       hesap arama
├── agents/tasks/[id]/, agents/tasks/    A2A tarzı görev uç noktaları
├── api/                                 v1/api altında sunulan dahili API yardımcıları
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Sohbet Tamamlamaları (ana uç nokta)
├── completions/                         Eski metin tamamlamaları
├── embeddings/                          Gömme vektörleri
├── files/[id]/, files/                  Dosyalar API'si
├── _helpers/                            Paylaşılan rota yardımcıları (genel URL yok)
├── images/{edits, generations}/         Görsel oluşturma + düzenleme
├── issues/                              Sınıflandırma yardımcı uç noktaları
├── management/{proxies}/                v1 içindeki yönetim kapsamlı rotalar
├── messages/{count_tokens}/             Anthropic tarzı mesaj uyumluluğu
├── models/                              Model listeleme (`route.ts`, `catalog.ts`)
├── moderations/                         Moderasyon
├── music/                               Müzik oluşturma
├── providers/[provider]/                Sağlayıcı başına işlemler
├── quotas/{check}                       Kota yoklamaları
├── registered-keys/                     Kayıtlı anahtar yönetimi
├── rerank/                              Yeniden sıralama
├── responses/[...path]/                 OpenAI Responses API (tümünü yakalayan)
├── search/                              Web araması
├── videos/                              Video oluşturma
├── ws/                                  WebSocket köprüsü
└── route.ts                             Dizin işleyicisi
```

Her rota dosyası aynı kalıbı izler:

```
Rota → CORS ön kontrolü → Zod gövde doğrulaması → isteğe bağlı kimlik doğrulama
     → API anahtarı politikası uygulaması → işleyiciye devretme (open-sse)
```

`v1beta/`, Gemini tarzı uyumluluk yüzeyidir (aynı `open-sse/handlers/`
işlem hattına dönüştüren ince bir sarmalayıcı).

### 3.2 `src/lib/` — Çekirdek kütüphaneler

Verileri, eşitlemeyi, OAuth'u, becerileri, belleği vb. her zaman bu modüller aracılığıyla içe aktarın.
Tablo, gerçek dizinleri ve dikkat çeken üst düzey dosyaları gruplandırır.

| Modül             | Amaç                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | A2A protokol sunucusu: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 beceri: maliyet analizi, sistem durumu raporu, sağlayıcı keşfi, kota yönetimi, akıllı yönlendirme, yetenekleri listeleme)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `acp/`            | Agent-Control-Protocol: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `api/`            | Dahili API yardımcıları: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `auth/`           | `managementPassword.ts` (parola sıfırlama / karma oluşturma)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `batches/`        | OpenAI Batches API hizmeti (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `catalog/`        | OpenRouter katalog senkronizasyonu (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `cloudAgent/`     | Bulut ajanı kayıt sistemi: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `combos/`         | Kombinasyon çözümleme yardımcıları                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `compliance/`     | Denetim + sağlayıcı denetimi: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `config/`         | Çalışma zamanı yapılandırma bağlantıları                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `db/`             | SQLite etki alanı modülleri (bkz. §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `display/`        | API yanıtlarında kullanılan kullanıcı arayüzü/görüntüleme yardımcıları                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `embeddings/`     | Gömme hizmeti kayıt sistemi                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `env/`            | Ortam yükleme + inceleme                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `evals/`          | Değerlendirme çalışma zamanı                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `jobs/`           | Arka plan işleri (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `memory/`         | Kalıcı bellek: `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/içe aktarma sağlayıcı modülleri (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`; ayrıca `services/`, `utils/` ve `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                                                   |
| `plugins/`        | Eklenti yükleyici (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `providerModels/` | Yönetilen model yaşam döngüsü: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `providers/`      | Sağlayıcı yardımcıları: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `resilience/`     | `settings.ts` — devre kesici, bekleme süresi ve kilitleme ayarları                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `runtime/`        | Çalışma zamanı özellik algılama                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `services/`       | Gömülü hizmetler çerçevesi: `ServiceSupervisor.ts` (işlem kilidi, halka arabellek ve sistem durumu denetleyicisi içeren genel alt süreç denetleyicisi), `bootstrap.ts` (süreç düzeyinde kayıt ve otomatik başlatma), `registry.ts` (araç → denetleyici eşlemesi), `apiKey.ts` (AES-256-GCM anahtar deposu), `modelSync.ts` (düzenli model senkronizasyonu), `ringBuffer.ts` (5 MB dairesel günlük arabelleği), `healthCheck.ts` (HTTP sistem durumu yoklaması), `types.ts`, `embedWsProxy.ts` (WebSocket proxy'si), `installers/{ninerouter,cliproxy}.ts`. Bkz. `docs/frameworks/EMBEDDED-SERVICES.md`                                                                                                                    |
| `agentSkills/`    | Ajan Becerileri kataloğu + oluşturucu: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → `skills/{id}/SKILL.md` dosyasına yazar), `openapiParser.ts` (OpenAPI belirtiminden REST uç noktalarını çıkarır), `cliRegistryParser.ts` (bin/cli-registry'den CLI alt komutlarını çıkarır), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). REST rotaları (`/api/agent-skills/*`), MCP araçları (`omniroute_agent_skills_*`) ve A2A becerisi `list-capabilities` tarafından kullanılır. Bkz. [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | Beceri çerçevesi: `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`; ayrıca `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `spend/`          | `batchWriter.ts` (arkadan yazma arabelleği)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sync/`           | `bundle.ts`, `tokens.ts` (Bulut Senkronizasyonu)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `system/`         | Sistem düzeyinde yardımcılar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `translator/`     | Üst düzey çevirmen bağlantıları (`open-sse/translator/` bileşenine devreder)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `usage/`          | Kullanım muhasebesi: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `versionManager/` | Otomatik güncelleme + sürüm bildirimi                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ws/`             | WebSocket köprüsü                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `zed-oauth/`      | Zed düzenleyicisi OAuth akışı                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

`src/lib/` içindeki üst düzey dosyalar:

- Eski `localDb.ts` barrel dosyası kaldırıldı — tüketiciler belirli `src/lib/db/*` modüllerini doğrudan içe aktarır.
- `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 veritabanı (`core.ts` içindeki `getDbInstance()`, WAL günlükleme).
**Rotalarda veya işleyicilerde asla ham SQL yazmayın** — bu modüller üzerinden işlem yapın.

![Veritabanı şemasına genel bakış (seçili temel tablolar)](../diagrams/exported/db-schema-overview.svg)

> Kaynak: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

Etki alanı modülleri (her biri bir veya daha fazla tablonun sahibidir): `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/`, sürümlendirilmiş 168 `.sql` dosyası (idempotent ve işlemsel) barındırır ve
başlatma sırasında `migrationRunner.ts` tarafından çalıştırılır.

Geçişler genelinde oluşturulan tablolar (toplam 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` (ayrıca bellek araması için FTS5 sanal tabloları).

### 3.3 `src/domain/` — Etki alanı katmanı

Saf iş mantığı; G/Ç içermez. Rotalar ve işleyiciler tarafından içe aktarılır.

| Dosya                                      | Amaç                                                  |
| ------------------------------------------ | ----------------------------------------------------- |
| `policyEngine.ts`                          | Üst düzey politika çözümleyici                        |
| `fallbackPolicy.ts`                        | Geri dönüş karar ağacı                                |
| `costRules.ts`                             | Maliyet hesaplama kuralları                           |
| `lockoutPolicy.ts`                         | Model kilitleme kararları                             |
| `tagRouter.ts`                             | Etiket tabanlı yönlendirme                            |
| `comboResolver.ts`                         | İstekten → hedef listesine kombinasyon çözümleme      |
| `connectionModelRules.ts`                  | Bağlantı başına model filtreleri                      |
| `modelAvailability.ts`                     | Model kullanılabilirlik denetimi                      |
| `degradation.ts`                           | Düşürülmüş mod geçişleri                              |
| `providerExpiration.ts`                    | Süresi dolmuş hesap/anahtar algılama                  |
| `quotaCache.ts`                            | Önbelleğe alınmış kota kararları                      |
| `responses.ts`, `omnirouteResponseMeta.ts` | Yanıt biçimi yardımcıları                             |
| `configAudit.ts`                           | Yapılandırma değişikliği denetimi                     |
| `assessment/`                              | Model değerlendirmesi (RFC'ye göre, kısmen uygulandı) |
| `types.ts`                                 | Paylaşılan etki alanı türleri                         |

### 3.4 `src/server/` — Yalnızca sunucu

İstemci bileşenlerinden içe aktarılamaz.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Rotaları herkese açık ve yönetim olarak sınıflandırır
│   ├── assertAuth.ts      Doğrulama yardımcısı
│   ├── context.ts         İstek başına yetkilendirme bağlamı
│   ├── headers.ts
│   ├── pipeline.ts        Yetkilendirme işlem hattı
│   ├── policies/          Somut politikalar
│   └── types.ts
└── cors/origins.ts        CORS kaynak izin listesi
```

### 3.5 `src/shared/` — Paylaşılması güvenli

Odaklanmış alt dizinlere ayrılmıştır:

- `constants/` — `providers.ts` (Zod ile doğrulanan sağlayıcı kataloğu), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (engelleme listesi), `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 şeması), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — npm'de yayımlanan genel API sözleşmeleri.
- `types/` — paylaşılan TS türleri.
- `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`; ayrıca `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/` altında pano hook'ları/bileşenleri.

---

## 4. `open-sse/` — Akış motoru çalışma alanı

`@omniroute/open-sse` olarak yayımlanan ayrı bir npm çalışma alanıdır. İstek
işleme, yürütücüler, çeviriciler, servisler, dönüştürücü ve MCP sunucusunu yönetir.

```
open-sse/
├── index.ts                Herkese açık dışa aktarımlar
├── package.json            Çalışma alanı manifesti
├── tsconfig.json
├── types.d.ts
├── config/                 Sağlayıcı kayıtları, başlık profilleri, kimlik, …
├── handlers/               İstek işleyicileri (sohbet, gömmeler, ses, görüntü, …)
├── executors/              150 sağlayıcı yürütücü modülü (yürütücü sınıfları + sağlayıcı başına yardımcılar)
├── translator/             Biçim dönüştürme (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions akış dönüştürücüsü
├── services/               80+ servis modülü (kombolar, geri dönüş, kotalar, kimlik, …)
├── utils/                  Akış yardımcıları, TLS istemcisi, AWS SigV4, proxy fetch, …
└── mcp-server/             MCP sunucusu (3 aktarım, 33 kapsam, 110 araç)
```

### 4.1 `open-sse/handlers/`

| İşleyici                | Amaç                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `chatCore.ts`           | Ana sohbet işlem hattı (önbellek, hız sınırı, kombo yönlendirme, yürütücü dağıtımı) |
| `responsesHandler.ts`   | OpenAI Responses API giriş noktası                                                  |
| `embeddings.ts`         | Gömmeler                                                                            |
| `imageGeneration.ts`    | Görüntü oluşturma                                                                   |
| `audioSpeech.ts`        | Metinden konuşmaya                                                                  |
| `audioTranscription.ts` | Konuşmadan metne                                                                    |
| `videoGeneration.ts`    | Video oluşturma                                                                     |
| `musicGeneration.ts`    | Müzik oluşturma                                                                     |
| `rerank.ts`             | Yeniden sıralama                                                                    |
| `moderations.ts`        | Moderasyon                                                                          |
| `search.ts`             | Web araması                                                                         |
| `sseParser.ts`          | SSE olay ayrıştırıcısı                                                              |
| `usageExtractor.ts`     | Yukarı akışlardan token sayılarını çıkarma                                          |
| `responseSanitizer.ts`  | Sağlayıcıya özgü gürültüyü kaldırma                                                 |
| `responseTranslator.ts` | Sağlayıcı yanıtı ile çevirici katmanı arasındaki bağlantı                           |

### 4.2 `open-sse/executors/`

150 üst düzey yürütücü modülü (`*.ts` eksi `base.ts`, `index.ts` ve testler — bu sayı
`npm run check:docs-counts` tarafından ölçülür). Her yürütücü sınıfı, doğrudan veya
`DefaultExecutor` ya da başka bir yürütücü aracılığıyla `BaseExecutor` (`base.ts`) sınıfını genişletir;
kalan modüller sağlayıcı başına yardımcılardır (araç şemaları, fetch/TTS adaptörleri, özel durum işleyicileri).
Yürütücüler şunları içerir:

`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`; ayrıca `claudeIdentity.ts`
(paylaşılan kimlik yardımcısı) ve `index.ts` (kayıt defteri).

> Not: burada listelenmeyen sağlayıcılar, genel OpenAI uyumlu yürütücüyü kullanan
> `default.ts` tarafından sunulur. Tam sağlayıcı kataloğu (375 sağlayıcı)
> `src/shared/constants/providers.ts` içinde yer alır.

### 4.3 `open-sse/translator/`

Merkez-uç çevirisi (merkez OpenAI'dır).

- **9 istek çeviricisi** (`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 yanıt çeviricisi** (`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 yardımcı** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper` ve
  yardımcı testleri.
- **Görüntü yardımcıları** (`translator/image/sizeMapper.ts`).
- Üst düzey: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

### 4.4 `open-sse/transformer/`

- `responsesTransformer.ts` — `TransformStream` tabanlı Responses API ↔ Chat
  Completions dönüştürücüsü (`responses/` rotasının tümünü yakalayan işleyicisi tarafından kullanılır).

### 4.5 `open-sse/services/`

Öne çıkanlar (tam liste `open-sse/services/` altında):

| Konu               | Dosyalar                                                                                                                                                                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo yönlendirme  | `combo.ts` (20 strateji), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                      |
| Auto Combo motoru  | `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`             |
| Dayanıklılık       | `accountFallback.ts` (bekleme süresi + kilitleme), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                 |
| Kotalar            | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| Önbelleğe alma     | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Yönlendirme zekâsı | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| Model işleme       | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| Sıkıştırma         | `compression/` — tam sıkıştırma motoru bağlantılandırması                                                                                                                                                                                                |
| Token + oturum     | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| Katman / manifest  | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / ağ            | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| Toplu işlemler     | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Kullanım           | `usage.ts`                                                                                                                                                                                                                                               |

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

- `server.ts` içinde bağlanmış **110 benzersiz araç** (`schemas/tools.ts` içinde 45 kanonik araç +
  bellek, beceriler, GitHub becerileri, havuz, oyunlaştırma, eklenti, Notion, Obsidian,
  yerel derlem ve sıkıştırma modülleri — birleşim `countUniqueMcpTools` tarafından sayılır).
- **3 aktarım yöntemi**: stdio, HTTP Streamable, SSE.
- Çalışma zamanında **33 kapsam** uygulanır — temel liste `src/shared/constants/mcpScopes.ts` içindedir; tam küme, her araç modülü tarafından bildirilen kapsamların birleşimidir.
- Denetim tablosu: `mcp_tool_audit` (`audit.ts` tarafından doldurulur).
- Dosyalar: `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`,
  ayrıca `__tests__/` altındaki testler.
- Tam araç kataloğu için [MCP-SERVER.md](../frameworks/MCP-SERVER.md) dosyasına bakın.

### 4.7 `open-sse/config/`

Sağlayıcı kayıtları (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), biçim başına model kayıtları (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
kimlik yardımcıları (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
kimlik bilgisi yardımcıları (`credentialLoader.ts`, `codexClient.ts`) ve bulut
bağdaştırıcıları (`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/`

Akış temel bileşenleri ve sağlayıcı yardımcıları: `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/` — Masaüstü sarmalayıcısı

```
electron/
├── main.js                  Electron ana süreci
├── preload.js               Önyükleme köprüsü (contextIsolation etkin)
├── types.d.ts
├── package.json             electron-builder yapılandırması, sürüm 3.8.51
├── README.md
├── assets/                  Derleme kaynakları (simgeler, yetkilendirmeler, …)
├── node_modules/            Ayrılmış node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Derleme çıktısı (depoya işlenmez)
```

Çalışma alanı kökünde beş npm betiği bulunur: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. Otomatik güncelleme,
GitHub sürüm akışına yönlendirilen `electron-updater` aracılığıyla gerçekleştirilir.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           Ana CLI giriş noktası (Node ESM)
├── reset-password.mjs      Yönetim parolasını CLI üzerinden sıfırlar
├── mcp-server.mjs          MCP sunucusu başlatıcısı (stdio)
├── nodeRuntimeSupport.mjs  Node sürümü koruması
└── cli/
    ├── program.mjs         Commander program oluşturucusu
    ├── runtime.mjs         withRuntime yardımcısı (önce sunucu/veritabanı geri dönüşü)
    ├── output.mjs          Çıktı biçimlendiricileri (json/jsonl/table/csv)
    ├── i18n.mjs            Yerel ayar destekli t() yardımcısı
    ├── api.mjs             API fetch yardımcısı
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Komut kaydı
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (komut/grup başına bir dosya)
```

`package.json` → `bin` içinde iki çalıştırılabilir dosya sunulur:

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

---

## 7. `tests/`

| Dizin                                                | Tür                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | Node yerel test çalıştırıcısı aracılığıyla birim testleri (1821 dosya ve `api/`, `auth/`, `authz/` alt dizinleri) |
| `tests/integration/`                                 | Modüller arası + veritabanı durumu testleri                                                                       |
| `tests/e2e/`                                         | Playwright kullanıcı arayüzü testleri                                                                             |
| `tests/e2e/protocol-clients.test.ts`                 | MCP/A2A protokolü uçtan uca testleri                                                                              |
| `tests/translator/`                                  | Çeviriciye özgü testler                                                                                           |
| `tests/security/`                                    | Güvenlik regresyonları                                                                                            |
| `tests/load/`                                        | Yük / stres testleri                                                                                              |
| `tests/golden-set/`                                  | Çevirici regresyonları için referans çıktılar                                                                     |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Destek                                                                                                            |

Yaygın komutlar:

| Komut                                                    | Çalıştırdığı işlem                                                                          |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `npm run test:unit`                                      | Node test çalıştırıcısı aracılığıyla tüm `tests/unit/*.test.ts` dosyaları (eşzamanlılık 10) |
| `npm run test:vitest`                                    | Vitest test paketi (MCP, autoCombo, önbellek)                                               |
| `npm run test:e2e`                                       | Playwright kullanıcı arayüzü test paketi                                                    |
| `npm run test:protocols:e2e`                             | MCP + A2A protokolü uçtan uca testleri                                                      |
| `npm run test:coverage`                                  | Kapsama eşiği (satırlar/deyimler/fonksiyonlar/dallar ≥%60)                                  |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | Tek dosya çalıştırması                                                                      |

---

## 8. `scripts/`

Amaca göre 6 alt klasör halinde düzenlenmiştir.

- **`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` ve ayrıca salt okunur PR gözetim yardımcıları:
  `ci-discriminate.sh` (bir PR'nin başarısız kontrol imzalarını bir referans PR'ye
  veya base-red sorununa göre kendisine ait / devralınmış / bilinmeyen olarak
  sınıflandırır) ve `audit-worktree.sh` (bir çalışanın PR'si kabul edilmeden önce
  kirli dosyaları, korunan yüzeyleri, kaldırılan assert'leri, bastırma sayılarını,
  geride kalan geçici tsconfig'leri ve PR başı ile yerel HEAD'i denetler).
- **`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. İstek İşlem Hattı (Özet)

![İstek işlem hattı (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Kaynak: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
İstemci isteği
  → /v1/chat/completions (route.ts)
     CORS ön kontrolü
     Zod doğrulaması (shared/validation/schemas.ts içindeki chatCompletionsSchema)
     Kimlik doğrulama (extractApiKey + isValidApiKey VEYA requireManagementAuth)
     İlke motoru (src/server/authz/pipeline.ts)
     Koruyucu önlemler (PII maskeleyici, istem enjeksiyonu, görüntü köprüsü)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Önbellek kontrolü (anlamsal + okuma önbelleği)
     Hız sınırı (rateLimitManager, accountSemaphore)
     Birleşik yönlendirme (model bir kombinasyona çözümlenirse)
       comboResolver → hedef başına döngü → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       üst kaynağı getir → accountFallback aracılığıyla yeniden deneme/üstel bekleme
     translateResponse() (open-sse/translator/response/*)
     SSE akışı VEYA JSON yanıtı
     Responses API ise: open-sse/transformer/responsesTransformer.ts aracılığıyla TransformStream
  → Uyumluluk denetimi (src/lib/compliance/)
  → İstemciye yanıt
```

### Dayanıklılık çalışma zamanı durumu (üç mekanizma)

| Mekanizma                | Kapsam                       | Konum                                                                                                                        |
| ------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Sağlayıcı devre kesicisi | Sağlayıcının tamamı          | `src/shared/utils/circuitBreaker.ts`, `domain_circuit_breakers` içinde kalıcı olarak saklanır                                |
| Bağlantı bekleme süresi  | Bir hesap/anahtar            | `src/sse/services/auth.ts` içindeki `markAccountUnavailable()`; `accountFallback.checkFallbackError()` tarafından kullanılır |
| Model kilitleme          | Sağlayıcı + bağlantı + model | `open-sse/services/accountFallback.ts`, `domain_lockout_state` içinde kalıcı olarak saklanır                                 |

Bkz. [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) ve
[CLAUDE.md](../../CLAUDE.md) içindeki özel bölüm.

---

## 10. Nasıl Katkıda Bulunulur

### Yeni bir sağlayıcı ekleme

1. `src/shared/constants/providers.ts` içinde kaydedin (yükleme sırasında Zod ile doğrulanır).
2. Özel mantık gerekiyorsa `open-sse/executors/` içine bir yürütücü ekleyin
   (`BaseExecutor` sınıfını genişletin).
3. OpenAI biçimini kullanmıyorsa `open-sse/translator/` içine bir çevirici ekleyin.
4. OAuth tabanlıysa `src/lib/oauth/providers/` ve
   `src/lib/oauth/services/` altına yapılandırma ekleyin.
5. Modelleri `open-sse/config/providerRegistry.ts` içinde (veya `open-sse/config/`
   altındaki biçime özgü kayıt defterinde) kaydedin.
6. Testleri `tests/unit/` altında yazın.

### Yeni bir API rotası ekleme

1. `src/app/api/your-route/route.ts` dosyasını oluşturun.
2. Şu düzeni izleyin: CORS → Zod gövde doğrulaması → kimlik doğrulama → işleyiciye devretme.
3. Yeni bir istek yapısı varsa Zod şemasını `src/shared/validation/schemas.ts` içine ekleyin.
4. Yalnızca yönetim amaçlıysa yolu `src/shared/constants/publicApiRoutes.ts`
   içine ekleyin (genel API yüzeyi için engelleme listesi).
5. Testleri `tests/unit/` altına ekleyin.
6. `docs/reference/API_REFERENCE.md` ve `docs/openapi.yaml` dosyalarını güncelleyin.

### Yeni bir DB modülü ekleme

1. `src/lib/db/yourModule.ts` dosyasını oluşturun ve `./core.ts` içinden `getDbInstance()` işlevini içe aktarın.
2. Alanınız için CRUD işlevlerini dışa aktarın.
3. Yeni tablolar varsa `src/lib/db/migrations/` altına sıralı olarak
   numaralandırılmış, idempotent ve işlemsel bir migrasyon ekleyin.
4. İçe aktaranlar `@/lib/db/yourModule` üzerinden doğrudan içe aktarma kullanır (barrel yoktur — eski `localDb.ts` yeniden dışa aktarma katmanı kaldırılmıştır).
5. Testleri `tests/unit/` altına ekleyin.

### Yeni bir MCP aracı ekleme

1. Araç tanımını `open-sse/mcp-server/tools/` altına ekleyin (veya
   `open-sse/mcp-server/schemas/tools.ts` dosyasını genişletin).
2. `src/shared/constants/mcpScopes.ts` içinde uygun kapsamları atayın.
3. Aracı `open-sse/mcp-server/server.ts` içinde kaydedin.
4. Testleri `open-sse/mcp-server/__tests__/` altına ekleyin.
5. [MCP-SERVER.md](../frameworks/MCP-SERVER.md) dosyasını güncelleyin.

### Yeni bir A2A becerisi ekleme

Bkz. [A2A-SERVER.md § Yeni Bir Beceri Ekleme](../frameworks/A2A-SERVER.md). Beceriler
`src/lib/a2a/skills/` altında bulunur ve A2A görev yöneticisi aracılığıyla kaydedilir.

---

## 11. Kurallar

- **Kod stili**: 2 boşluklu girinti, çift tırnak, 100 karakter genişliği, noktalı virgüller,
  `es5` son virgülleri — Prettier tarafından `lint-staged` aracılığıyla uygulanır.
- **İçe aktarmalar**: harici → dahili (`@/`, `@omniroute/open-sse`) → göreli.
- **Adlandırma**: dosyalar `camelCase` veya `kebab-case`, bileşenler `PascalCase`,
  sabitler `UPPER_SNAKE`.
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = her yerde `error`;
  `no-explicit-any` = `open-sse/` ve `tests/` içinde `warn`, diğer yerlerde `error`.
- **TypeScript**: `strict: false` (eski yaklaşım). Modüller arası sınırlarda
  çıkarım yerine açık türleri tercih edin.
- **Veritabanı**: rotalarda veya işleyicilerde asla ham SQL yazmayın — her zaman
  `src/lib/db/` modüllerini kullanın. Asla barrel içe aktarması kullanmayın — belirli `src/lib/db/*` modüllerini doğrudan kullanın.
- **DB varlık türleri (#3512)**: Bir DB tablosunun satır yapısını yazan veya
  okuyan bir işlev, çağrı noktasında `any` ya da satır içi anonim bir tür yerine,
  o tablonun sütunlarını bire bir yansıtan adlandırılmış bir TS arayüzünü parametre
  olarak almalı veya döndürmelidir. Arayüzü işlevin yanına yerleştirin (ör. `saveRequestUsage`
  üzerinde, `src/lib/usage/usageHistory.ts` içinde `export interface UsageEntry`);
  farklı yazıcılar satırı kademeli olarak dolduruyorsa tek tek alanları isteğe bağlı/nullable
  tutun ve yapısı çağıranlara göre değişen bir alan için `any` yerine `unknown`
  tercih edin (alan üzerinde belgelendiği şekilde; ör. `UsageEntry.tokens` hem sağlayıcı
  biçimindeki ham kullanımı hem de normalleştirilmiş biçimi kabul eder). Bir dosyanın
  `any` sayısı bu yöntemle sıfıra ulaştığında, gerilememesi için dosyayı
  `check:any-budget:t11` izin listesine (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`) ekleyin. Bu, ilk dilime yönelik bir kuraldır — daha geniş kapsamlı
  "anonim `any` yok" temizliği kod tabanının geri kalanında yinelemeli olarak yürütülür.
- **Hatalar**: Belirli hata türleriyle try/catch kullanın, pino bağlamıyla günlükleyin. SSE
  akışlarında hataları asla sessizce yutmayın; temizlik için iptal sinyallerini kullanın.
- **Güvenlik**: Asla `eval()` / `new Function()` / örtük eval kullanmayın. Tüm
  girdileri Zod ile doğrulayın. Kimlik bilgilerini bekleme hâlindeyken şifreleyin (AES-256-GCM).
  `src/shared/constants/upstreamHeaders.ts` engelleme listesini
  temizleme/doğrulama katmanıyla uyumlu tutun.
- **Commit'ler**: Conventional Commits — `feat(scope): subject`. İzin verilen kapsamlar:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Dallar**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/` önekleri. Asla doğrudan `main` dalına commit göndermeyin.
- **Husky**: pre-commit, `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11` çalıştırır; pre-push, `check:any-budget:t11` + `check:tracked-artifacts` çalıştırır (hızlı denetimler; `test:unit` hariç).

---

## 12. Kesin Kurallar (CLAUDE.md'den)

1. Gizli bilgileri veya kimlik bilgilerini asla commit etmeyin.
2. Asla barrel import kullanmayın — doğrudan belirli `src/lib/db/*` modüllerini kullanın.
3. `eval()` / `new Function()` / örtük eval kullanımından kaçının.
4. Asla doğrudan `main` dalına commit etmeyin.
5. Route'larda asla ham SQL yazmayın — her zaman `src/lib/db/` modüllerini kullanın.
6. SSE akışlarındaki hataları asla sessizce yutmayın.
7. Girdileri her zaman Zod şemalarıyla doğrulayın.
8. Üretim kodunu değiştirirken her zaman testleri de ekleyin.
9. Kapsama oranı ≥ %60 (ifadeler, satırlar, fonksiyonlar, dallar) olarak kalmalıdır.

---

## 13. Ayrıca Bakınız

- [ARCHITECTURE.md](./ARCHITECTURE.md) — üst düzey mimari ve modül
  sorumlulukları.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — genel + yönetim API'si referansı.
- [FEATURES.md](../guides/FEATURES.md) — özellik matrisi ve sürümde öne çıkanlar.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — devre kesici, bekleme süresi ve
  kilitleme hakkında ayrıntılı inceleme.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo puanlaması ve stratejileri.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — eksiksiz MCP araç kataloğu + aktarımlar.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A protokolü becerileri ve keşfi.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman sıkıştırması.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI entegrasyonları.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (varsa), [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) — dağıtım hedefleri.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — yaygın operasyonel sorunlar.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — katkıda bulunanların iş akışı.
- [CLAUDE.md](../../CLAUDE.md) — Claude Code için depo kuralları (yukarıdaki
  kuralların çoğunun doğruluk kaynağı).
- [AGENTS.md](../../AGENTS.md) — aracılar tarafından kullanılan daha ayrıntılı mimari referansı.