# 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) · 🇬🇪 [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) · 🇵🇭 [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, ਸਟੈਂਡਅਲੋਨ ਆਉਟਪੁੱਟ, ਕੋਈ ਗਲੋਬਲ ਮਿਡਲਵੇਅਰ ਨਹੀਂ)                                              |
| ਭਾਸ਼ਾ        | **TypeScript 6.0+** — ਟਾਰਗੇਟ `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                |
| ਰਨਟਾਈਮ       | **Node.js** `>=22.22.2 <23` ਜਾਂ `>=24.0.0 <27` (`engines` + `SUPPORTED_NODE_RANGE` ਰਾਹੀਂ ਲਾਗੂ)                       |
| ਡਾਟਾਬੇਸ      | `better-sqlite3` ਰਾਹੀਂ **SQLite** (ਸਿੰਗਲਟਨ, WAL ਜਰਨਲਿੰਗ)                                                             |
| ਡੈਸਕਟਾਪ      | **Electron 41** + `electron-builder` 26.10 (`electron/` ਵਿੱਚ ਵੱਖਰਾ ਵਰਕਸਪੇਸ)                                          |
| ਟੈਸਟ         | **Node ਨੇਟਿਵ ਟੈਸਟ ਰਨਰ** (ਯੂਨਿਟ/ਇੰਟੀਗ੍ਰੇਸ਼ਨ), **Vitest** (MCP, autoCombo, ਕੈਸ਼), **Playwright** (e2e + protocols-e2e) |
| ਬਿਲਡ         | `scripts/build/build-next-isolated.mjs` ਰਾਹੀਂ Next.js ਸਟੈਂਡਅਲੋਨ                                                      |
| ਲਿੰਟ/ਫਾਰਮੈਟ  | ESLint ਫਲੈਟ ਕੌਂਫਿਗ + Prettier (Husky ਪ੍ਰੀ-ਕਮਿਟ ਰਾਹੀਂ `lint-staged`)                                                  |
| ਮੋਡੀਊਲ ਸਿਸਟਮ | ਹਰ ਥਾਂ ESM (`"type": "module"`)                                                                                      |
| ਵਰਕਸਪੇਸ      | npm ਵਰਕਸਪੇਸ — `open-sse` ਇਕੱਲਾ ਸਬ-ਵਰਕਸਪੇਸ ਹੈ                                                                         |

ਪਾਥ ਉਪਨਾਮ (`tsconfig.json`):

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

ਡਿਫਾਲਟ HTTP ਪੋਰਟ: **`20128`** (API ਅਤੇ ਡੈਸ਼ਬੋਰਡ ਇੱਕੋ ਪ੍ਰਕਿਰਿਆ ਸਾਂਝੀ ਕਰਦੇ ਹਨ)। ਡਾਟਾ
ਡਾਇਰੈਕਟਰੀ `DATA_DIR` env var ਹੈ, ਜਿਸ ਦਾ ਡਿਫਾਲਟ `~/.omniroute/` ਹੈ।

---

## 2. ਰਿਪੋਜ਼ਟਰੀ ਲੇਆਉਟ

```
OmniRoute/
├── src/                  Next.js ਐਪਲੀਕੇਸ਼ਨ (App Router, ਲਾਇਬ੍ਰੇਰੀਆਂ, ਡੋਮੇਨ, ਸਰਵਰ, ਸਾਂਝੇ ਹਿੱਸੇ)
├── open-sse/             ਸਟ੍ਰੀਮਿੰਗ ਇੰਜਣ ਵਰਕਸਪੇਸ (@omniroute/open-sse)
├── electron/             ਡੈਸਕਟਾਪ ਰੈਪਰ (Electron 41 ਮੁੱਖ + ਪ੍ਰੀਲੋਡ)
├── 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/           ਰੂਟ-ਪੱਧਰੀ ਮਿਡਲਵੇਅਰ ਉਪਯੋਗਤਾਵਾਂ (Next.js ਗਲੋਬਲ ਮਿਡਲਵੇਅਰ ਨਹੀਂ)
├── scripts/              ਇਨ-ਟ੍ਰੀ ਸਕ੍ਰਿਪਟਾਂ ਜਿਨ੍ਹਾਂ ਨੂੰ ਐਪ ਕੋਡ ਦੁਆਰਾ ਇੰਪੋਰਟ ਕੀਤਾ ਜਾ ਸਕਦਾ ਹੈ
├── types/                ਐਂਬੀਐਂਟ ਅਤੇ ਸਾਂਝੀਆਂ TS ਕਿਸਮਾਂ
├── i18n/                 ਲੋਕੇਲ ਬੰਡਲ
├── instrumentation.ts    Next.js ਇੰਸਟਰੂਮੈਂਟੇਸ਼ਨ ਹੁੱਕ
├── instrumentation-node.ts
└── proxy.ts              ਉੱਪਰੀ-ਪੱਧਰੀ ਪ੍ਰੌਕਸੀ ਬੂਟਸਟਰੈਪ ਸਹਾਇਕ
```

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

App Router ਡੈਸ਼ਬੋਰਡ UI ਅਤੇ ਜਨਤਕ/ਪ੍ਰਬੰਧਨ HTTP API ਦੋਵਾਂ ਨੂੰ ਉਪਲਬਧ ਕਰਵਾਉਂਦਾ ਹੈ।
ਇੱਥੇ **ਕੋਈ ਗਲੋਬਲ ਮਿਡਲਵੇਅਰ ਨਹੀਂ ਹੈ** — ਇੰਟਰਸੈਪਸ਼ਨ ਹਰ ਰੂਟ ਲਈ ਵੱਖਰੇ ਤੌਰ 'ਤੇ ਕੀਤਾ ਜਾਂਦਾ ਹੈ।

`src/app/` ਦੇ ਅਧੀਨ ਉੱਪਰੀ-ਪੱਧਰੀ ਸੈਗਮੈਂਟ:

| ਪਾਥ                                                                           | ਉਦੇਸ਼                                         |
| ----------------------------------------------------------------------------- | --------------------------------------------- |
| `api/`                                                                        | ਸਾਰੇ HTTP API ਰੂਟ (ਹੇਠਾਂ ਵੇਰਵਾ ਦੇਖੋ)          |
| `a2a/`                                                                        | A2A JSON-RPC 2.0 ਐਂਡਪੌਇੰਟ (`POST /a2a`)       |
| `.well-known/agent.json/`                                                     | A2A Agent Card ਖੋਜ ਦਸਤਾਵੇਜ਼                   |
| `(dashboard)/`                                                                | ਡੈਸ਼ਬੋਰਡ UI (ਰੂਟ ਸਮੂਹ, ਕੋਈ 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/` — UI ਪੰਨੇ

`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** (ਸਿਰਫ਼ ਲੂਪਬੈਕ, ਸਖ਼ਤ ਨਿਯਮ #17) ਵਜੋਂ ਵਰਗੀਕ੍ਰਿਤ ਹਨ, ਕਿਉਂਕਿ ਉਹ
`npm install` ਚਲਾ ਸਕਦੇ ਹਨ ਅਤੇ ਚਾਈਲਡ ਪ੍ਰਕਿਰਿਆਵਾਂ ਪੈਦਾ ਕਰ ਸਕਦੇ ਹਨ।

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() ਸਹਾਇਕ
│   ├── install/route.ts    POST — execFile ਰਾਹੀਂ 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 ਕਰੋ
│   ├── 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/                    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` ਬੈਰਲ ਹਟਾ ਦਿੱਤਾ ਗਿਆ ਸੀ — ਉਪਭੋਗਤਾ ਖ਼ਾਸ `src/lib/db/*` ਮੋਡੀਊਲਾਂ ਨੂੰ ਸਿੱਧਾ ਇੰਪੋਰਟ ਕਰਦੇ ਹਨ।
- `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts`
- `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts`
- `cloudSync.ts`, `initCloudSync.ts`
- `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts`
- `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts`
- `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts`
- `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts`
- `piiSanitizer.ts`, `pricingSync.ts`
- `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts`
- `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts`

#### 3.2.1 `src/lib/db/`

ਸਿੰਗਲਟਨ SQLite ਡਾਟਾਬੇਸ (`core.ts` ਵਿੱਚ `getDbInstance()`, 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/` — ਸਟ੍ਰੀਮਿੰਗ ਇੰਜਣ ਵਰਕਸਪੇਸ

`@omniroute/open-sse` ਵਜੋਂ ਪ੍ਰਕਾਸ਼ਿਤ ਵੱਖਰਾ npm ਵਰਕਸਪੇਸ। ਇਹ ਬੇਨਤੀ
ਪ੍ਰੋਸੈਸਿੰਗ, ਐਗਜ਼ੀਕਿਊਟਰਾਂ, ਟ੍ਰਾਂਸਲੇਟਰਾਂ, ਸਰਵਿਸਾਂ, ਟ੍ਰਾਂਸਫਾਰਮਰ ਅਤੇ MCP ਸਰਵਰ ਦਾ ਪ੍ਰਬੰਧ ਕਰਦਾ ਹੈ।

```
open-sse/
├── index.ts                ਜਨਤਕ ਐਕਸਪੋਰਟ
├── package.json            ਵਰਕਸਪੇਸ ਮੈਨੀਫੈਸਟ
├── tsconfig.json
├── types.d.ts
├── config/                 ਪ੍ਰੋਵਾਈਡਰ ਰਜਿਸਟਰੀਆਂ, ਹੈਡਰ ਪ੍ਰੋਫਾਈਲਾਂ, ਪਛਾਣ, …
├── handlers/               ਬੇਨਤੀ ਹੈਂਡਲਰ (ਚੈਟ, ਐਮਬੈਡਿੰਗਾਂ, ਆਡੀਓ, ਚਿੱਤਰ, …)
├── executors/              150 ਪ੍ਰੋਵਾਈਡਰ ਐਗਜ਼ੀਕਿਊਟਰ ਮੋਡੀਊਲ (ਐਗਜ਼ੀਕਿਊਟਰ ਕਲਾਸਾਂ + ਪ੍ਰਤੀ-ਪ੍ਰੋਵਾਈਡਰ ਸਹਾਇਕ)
├── translator/             ਫਾਰਮੈਟ ਰੂਪਾਂਤਰਨ (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Responses API ↔ Chat Completions ਸਟ੍ਰੀਮ ਟ੍ਰਾਂਸਫਾਰਮਰ
├── services/               80+ ਸਰਵਿਸ ਮੋਡੀਊਲ (ਕੌਂਬੋ, ਫਾਲਬੈਕ, ਕੋਟੇ, ਪਛਾਣ, …)
├── utils/                  ਸਟ੍ਰੀਮਿੰਗ ਸਹਾਇਕ, TLS ਕਲਾਇੰਟ, AWS SigV4, ਪ੍ਰੌਕਸੀ ਫੈਚ, …
└── mcp-server/             MCP ਸਰਵਰ (3 ਟ੍ਰਾਂਸਪੋਰਟ, 33 ਸਕੋਪ, 110 ਟੂਲ)
```

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

| ਹੈਂਡਲਰ                  | ਉਦੇਸ਼                                                              |
| ----------------------- | ------------------------------------------------------------------ |
| `chatCore.ts`           | ਮੁੱਖ ਚੈਟ ਪਾਈਪਲਾਈਨ (ਕੈਸ਼, ਦਰ ਸੀਮਾ, ਕੌਂਬੋ ਰੂਟਿੰਗ, ਐਗਜ਼ੀਕਿਊਟਰ ਡਿਸਪੈਚ) |
| `responsesHandler.ts`   | OpenAI Responses API ਦਾ ਪ੍ਰਵੇਸ਼ ਬਿੰਦੂ                              |
| `embeddings.ts`         | ਐਮਬੈਡਿੰਗਾਂ                                                         |
| `imageGeneration.ts`    | ਚਿੱਤਰ ਜਨਰੇਸ਼ਨ                                                      |
| `audioSpeech.ts`        | ਟੈਕਸਟ-ਤੋਂ-ਬੋਲੀ                                                     |
| `audioTranscription.ts` | ਬੋਲੀ-ਤੋਂ-ਟੈਕਸਟ                                                     |
| `videoGeneration.ts`    | ਵੀਡੀਓ ਜਨਰੇਸ਼ਨ                                                      |
| `musicGeneration.ts`    | ਸੰਗੀਤ ਜਨਰੇਸ਼ਨ                                                      |
| `rerank.ts`             | ਮੁੜ-ਰੈਂਕਿੰਗ                                                        |
| `moderations.ts`        | ਮੋਡਰੇਸ਼ਨ                                                           |
| `search.ts`             | ਵੈੱਬ ਖੋਜ                                                           |
| `sseParser.ts`          | SSE ਇਵੈਂਟ ਪਾਰਸਰ                                                    |
| `usageExtractor.ts`     | ਅੱਪਸਟ੍ਰੀਮ ਸਟ੍ਰੀਮਾਂ ਵਿੱਚੋਂ ਟੋਕਨ ਗਿਣਤੀਆਂ ਕੱਢਣਾ                       |
| `responseSanitizer.ts`  | ਪ੍ਰੋਵਾਈਡਰ-ਵਿਸ਼ੇਸ਼ ਗੈਰ-ਜ਼ਰੂਰੀ ਸਮੱਗਰੀ ਹਟਾਉਣਾ                         |
| `responseTranslator.ts` | ਪ੍ਰੋਵਾਈਡਰ ਜਵਾਬ ਅਤੇ ਟ੍ਰਾਂਸਲੇਟਰ ਪਰਤ ਵਿਚਕਾਰ ਜੋੜ                       |

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

150 ਸਿਖਰਲੇ-ਪੱਧਰ ਦੇ ਐਗਜ਼ੀਕਿਊਟਰ ਮੋਡੀਊਲ (`*.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` (ਰਜਿਸਟਰੀ)।

> ਨੋਟ: ਇੱਥੇ ਸੂਚੀਬੱਧ ਨਾ ਕੀਤੇ ਗਏ ਪ੍ਰੋਵਾਈਡਰਾਂ ਨੂੰ ਆਮ
> OpenAI-ਅਨੁਕੂਲ ਐਗਜ਼ੀਕਿਊਟਰ ਦੀ ਵਰਤੋਂ ਕਰਕੇ `default.ts` ਦੁਆਰਾ ਸੇਵਾ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ। ਪੂਰਾ ਪ੍ਰੋਵਾਈਡਰ ਕੈਟਾਲੌਗ (372 ਪ੍ਰੋਵਾਈਡਰ)
> `src/shared/constants/providers.ts` ਵਿੱਚ ਮੌਜੂਦ ਹੈ।

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

ਹੱਬ-ਅਤੇ-ਸਪੋਕ ਅਨੁਵਾਦ (OpenAI ਹੱਬ ਹੈ)।

- **9 ਬੇਨਤੀ ਟ੍ਰਾਂਸਲੇਟਰ** (`translator/request/`):
  `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`,
  `gemini-to-openai`, `openai-responses`, `openai-to-claude`,
  `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`।
- **9 ਜਵਾਬ ਟ੍ਰਾਂਸਲੇਟਰ** (`translator/response/`):
  `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`,
  `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`,
  `openai-to-claude`।
- **9 ਸਹਾਇਕ** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, ਨਾਲ ਹੀ
  ਸਹਾਇਕ ਟੈਸਟ।
- **ਚਿੱਤਰ ਸਹਾਇਕ** (`translator/image/sizeMapper.ts`)।
- ਸਿਖਰਲਾ ਪੱਧਰ: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`।

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

- `responsesTransformer.ts` — `TransformStream`-ਅਧਾਰਿਤ Responses API ↔ Chat
  Completions ਕਨਵਰਟਰ (`responses/` ਰੂਟ ਕੈਚ-ਆਲ ਦੁਆਰਾ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ)।

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

ਮੁੱਖ ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ (ਪੂਰੀ ਸੂਚੀ `open-sse/services/` ਅਧੀਨ):

| ਚਿੰਤਾ ਦਾ ਖੇਤਰ      | ਫ਼ਾਈਲਾਂ                                                                                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ਕੰਬੋ ਰਾਊਟਿੰਗ       | `combo.ts` (19 ਰਣਨੀਤੀਆਂ), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                      |
| ਆਟੋ ਕੰਬੋ ਇੰਜਣ      | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts`             |
| ਲਚੀਲਾਪਣ            | `accountFallback.ts` (ਕੂਲਡਾਊਨ + ਲੌਕਆਊਟ), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                                           |
| ਕੋਟੇ               | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `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` ਵਿੱਚ ਵਾਇਰ ਕੀਤੇ ਗਏ ਹਨ (`schemas/tools.ts` ਵਿੱਚ 45 ਕੈਨੋਨਿਕਲ +
  ਮੈਮੋਰੀ, ਸਕਿੱਲਜ਼, 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`। ਸਵੈਚਲਿਤ ਅੱਪਡੇਟ
GitHub ਰਿਲੀਜ਼ ਫੀਡ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਦੇ `electron-updater` ਰਾਹੀਂ ਹੁੰਦਾ ਹੈ।

---

## 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`                                      | Node ਟੈਸਟ ਰਨਰ ਰਾਹੀਂ ਸਾਰੇ `tests/unit/*.test.ts` (ਸਮਕਾਲੀਤਾ 10) |
| `npm run test:vitest`                                    | Vitest ਸੂਟ (MCP, autoCombo, cache)                            |
| `npm run test:e2e`                                       | Playwright UI ਸੂਟ                                             |
| `npm run test:protocols:e2e`                             | MCP + A2A ਪ੍ਰੋਟੋਕੋਲ e2e                                       |
| `npm run test:coverage`                                  | ਕਵਰੇਜ ਗੇਟ (≥60% ਲਾਈਨਾਂ/ਸਟੇਟਮੈਂਟਾਂ/ਫੰਕਸ਼ਨਾਂ/ਸ਼ਾਖਾਵਾਂ)          |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | ਇੱਕੋ ਫ਼ਾਈਲ ਚਲਾਉਣਾ                                             |

---

## 8. `scripts/`

ਉਦੇਸ਼ ਅਨੁਸਾਰ 6 ਸਬਫੋਲਡਰਾਂ ਵਿੱਚ ਵਿਵਸਥਿਤ।

- **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`,
  `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`,
  `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`,
  `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`,
  `native-binary-compat.mjs`।
- **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`,
  `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`,
  `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`,
  `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`,
  `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`,
  `system-info.mjs`।
- **`scripts/check/`** — `check-cycles.mjs`, `check-docs-sync.mjs`,
  `check-docs-counts-sync.mjs`, `check-env-doc-sync.mjs`,
  `check-deprecated-versions.mjs`, `check-route-validation.mjs`,
  `check-t11-any-budget.mjs`, `check-pr-test-policy.mjs`,
  `check-supported-node-runtime.ts`, `test-report-summary.mjs`।
- **`scripts/docs/`** — `generate-docs-index.mjs`, `gen-provider-reference.ts`।
- **`scripts/i18n/`** — `generate-multilang.mjs`, `run-visual-qa.mjs`,
  `generate-qa-checklist.mjs`, `apply-priority-overrides.mjs`,
  `validate_translation.py`, `check_translations.py`, `i18n_autotranslate.py`,
  `untranslatable-keys.json`।
- **`scripts/ad-hoc/`** — `cursor-tap.cjs`, `sync-cursor-models.mjs`,
  `migrate-env.mjs`, `dbsetup.js`।

---

## 9. ਬੇਨਤੀ ਪਾਈਪਲਾਈਨ (ਸੰਖੇਪ)

![ਬੇਨਤੀ ਪਾਈਪਲਾਈਨ (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> ਸਰੋਤ: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
ਕਲਾਇੰਟ ਬੇਨਤੀ
  → /v1/chat/completions (route.ts)
     CORS ਪ੍ਰੀਫਲਾਈਟ ਜਾਂਚ
     Zod ਪ੍ਰਮਾਣਿਕਤਾ (shared/validation/schemas.ts ਵਿੱਚ chatCompletionsSchema)
     ਪ੍ਰਮਾਣੀਕਰਨ (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 ਹੋਵੇ: open-sse/transformer/responsesTransformer.ts ਰਾਹੀਂ TransformStream
  → ਅਨੁਪਾਲਣਾ ਆਡਿਟ (src/lib/compliance/)
  → ਕਲਾਇੰਟ ਨੂੰ ਜਵਾਬ
```

### ਲਚਕੀਲੇਪਣ ਦੀ ਰਨਟਾਈਮ ਸਥਿਤੀ (ਤਿੰਨ ਵਿਧੀਆਂ)

| ਵਿਧੀ                 | ਦਾਇਰਾ                    | ਕਿੱਥੇ                                                                                                                   |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| ਪ੍ਰਦਾਤਾ ਸਰਕਿਟ ਬ੍ਰੇਕਰ | ਪੂਰਾ ਪ੍ਰਦਾਤਾ             | `src/shared/utils/circuitBreaker.ts`, `domain_circuit_breakers` ਵਿੱਚ ਸਥਾਈ ਤੌਰ 'ਤੇ ਸੁਰੱਖਿਅਤ                              |
| ਕਨੈਕਸ਼ਨ ਕੂਲਡਾਊਨ      | ਇੱਕ ਖਾਤਾ/ਕੁੰਜੀ           | `src/sse/services/auth.ts` ਵਿੱਚ `markAccountUnavailable()`; `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. ਜੇ ਬੇਨਤੀ ਦੀ ਬਣਤਰ ਨਵੀਂ ਹੈ: `src/shared/validation/schemas.ts` ਵਿੱਚ Zod ਸਕੀਮਾ ਸ਼ਾਮਲ ਕਰੋ।
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` ਬਣਾਓ ਅਤੇ `./core.ts` ਤੋਂ `getDbInstance()` ਨੂੰ ਇੰਪੋਰਟ ਕਰੋ।
2. ਆਪਣੇ ਡੋਮੇਨ ਲਈ CRUD ਫੰਕਸ਼ਨ ਐਕਸਪੋਰਟ ਕਰੋ।
3. ਜੇ ਨਵੀਆਂ ਟੇਬਲਾਂ ਹਨ: `src/lib/db/migrations/` ਹੇਠ ਕ੍ਰਮਵਾਰ ਨੰਬਰ ਵਾਲੀ,
   ਆਈਡੈਂਪੋਟੈਂਟ ਅਤੇ ਟ੍ਰਾਂਜ਼ੈਕਸ਼ਨਲ ਮਾਈਗ੍ਰੇਸ਼ਨ ਸ਼ਾਮਲ ਕਰੋ।
4. ਇੰਪੋਰਟਰ `@/lib/db/yourModule` ਤੋਂ ਸਿੱਧੇ ਇੰਪੋਰਟ ਵਰਤਦੇ ਹਨ (ਕੋਈ ਬੈਰਲ ਨਹੀਂ — ਪੁਰਾਣੀ `localDb.ts` ਰੀ-ਐਕਸਪੋਰਟ ਪਰਤ ਹਟਾ ਦਿੱਤੀ ਗਈ ਸੀ)।
5. `tests/unit/` ਹੇਠ ਟੈਸਟ ਸ਼ਾਮਲ ਕਰੋ।

### ਨਵਾਂ MCP ਟੂਲ ਸ਼ਾਮਲ ਕਰੋ

1. `open-sse/mcp-server/tools/` ਹੇਠ ਟੂਲ ਦੀ ਪਰਿਭਾਸ਼ਾ ਸ਼ਾਮਲ ਕਰੋ (ਜਾਂ
   `open-sse/mcp-server/schemas/tools.ts` ਨੂੰ ਵਿਸਤਾਰ ਦਿਓ)।
2. `src/shared/constants/mcpScopes.ts` ਵਿੱਚ ਢੁਕਵੇਂ ਸਕੋਪ ਨਿਰਧਾਰਤ ਕਰੋ।
3. ਟੂਲ ਨੂੰ `open-sse/mcp-server/server.ts` ਵਿੱਚ ਰਜਿਸਟਰ ਕਰੋ।
4. `open-sse/mcp-server/__tests__/` ਹੇਠ ਟੈਸਟ ਸ਼ਾਮਲ ਕਰੋ।
5. [MCP-SERVER.md](../frameworks/MCP-SERVER.md) ਨੂੰ ਅੱਪਡੇਟ ਕਰੋ।

### ਨਵਾਂ A2A ਹੁਨਰ ਸ਼ਾਮਲ ਕਰੋ

[A2A-SERVER.md § ਨਵਾਂ ਹੁਨਰ ਸ਼ਾਮਲ ਕਰਨਾ](../frameworks/A2A-SERVER.md) ਵੇਖੋ। ਹੁਨਰ
`src/lib/a2a/skills/` ਵਿੱਚ ਹੁੰਦੇ ਹਨ ਅਤੇ A2A ਟਾਸਕ ਮੈਨੇਜਰ ਰਾਹੀਂ ਰਜਿਸਟਰ ਕੀਤੇ ਜਾਂਦੇ ਹਨ।

---

## 11. ਰਵਾਇਤਾਂ

- **ਕੋਡ ਸ਼ੈਲੀ**: 2-ਸਪੇਸ ਇੰਡੈਂਟ, ਡਬਲ ਕੋਟ, 100 ਅੱਖਰ ਚੌੜਾਈ, ਸੈਮੀਕੋਲਨ,
  `es5` ਟ੍ਰੇਲਿੰਗ ਕਾਮੇ — `lint-staged` ਰਾਹੀਂ Prettier ਦੁਆਰਾ ਲਾਗੂ ਕੀਤੇ ਜਾਂਦੇ ਹਨ।
- **ਇੰਪੋਰਟ**: ਬਾਹਰੀ → ਅੰਦਰੂਨੀ (`@/`, `@omniroute/open-sse`) → ਰਿਲੇਟਿਵ।
- **ਨਾਮਕਰਨ**: ਫਾਈਲਾਂ `camelCase` ਜਾਂ `kebab-case`, ਕੰਪੋਨੈਂਟ `PascalCase`,
  ਕਾਂਸਟੈਂਟ `UPPER_SNAKE`।
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = ਹਰ ਥਾਂ `error`;
  `no-explicit-any` = `open-sse/` ਅਤੇ `tests/` ਵਿੱਚ `warn`, ਹੋਰ ਥਾਵਾਂ 'ਤੇ error।
- **TypeScript**: `strict: false` (ਵਿਰਾਸਤੀ ਰੁਖ਼)। ਕ੍ਰਾਸ-ਮੋਡੀਊਲ ਸੀਮਾਵਾਂ ਲਈ
  ਇਨਫਰੈਂਸ ਦੀ ਬਜਾਏ ਸਪਸ਼ਟ ਟਾਈਪਾਂ ਨੂੰ ਤਰਜੀਹ ਦਿਓ।
- **ਡਾਟਾਬੇਸ**: ਰੂਟਾਂ ਜਾਂ ਹੈਂਡਲਰਾਂ ਵਿੱਚ ਕਦੇ ਵੀ ਕੱਚੀ SQL ਨਾ ਲਿਖੋ — ਹਮੇਸ਼ਾ
  `src/lib/db/` ਮੋਡੀਊਲਾਂ ਰਾਹੀਂ ਜਾਓ। ਕਦੇ ਵੀ ਬੈਰਲ-ਇੰਪੋਰਟ ਨਾ ਕਰੋ — ਖਾਸ `src/lib/db/*` ਮੋਡੀਊਲ ਸਿੱਧੇ ਵਰਤੋ।
- **DB-ਐਂਟਿਟੀ ਟਾਈਪਿੰਗ (#3512)**: DB ਟੇਬਲ ਦੀ ਕਤਾਰ ਦੀ ਬਣਤਰ ਲਿਖਣ ਜਾਂ ਪੜ੍ਹਨ ਵਾਲੇ
  ਫੰਕਸ਼ਨ ਨੂੰ ਇੱਕ ਨਾਮਿਤ TS ਇੰਟਰਫੇਸ ਲੈਣਾ/ਵਾਪਸ ਕਰਨਾ ਚਾਹੀਦਾ ਹੈ, ਜੋ ਉਸ ਟੇਬਲ ਦੇ
  ਕਾਲਮਾਂ ਨੂੰ 1:1 ਦਰਸਾਉਂਦਾ ਹੋਵੇ; ਕਾਲ ਸਾਈਟ 'ਤੇ `any` ਜਾਂ ਇਨਲਾਈਨ ਬੇਨਾਮ ਟਾਈਪ ਨਹੀਂ। ਇੰਟਰਫੇਸ ਨੂੰ
  ਫੰਕਸ਼ਨ ਦੇ ਕੋਲ ਰੱਖੋ (ਉਦਾਹਰਨ ਲਈ `saveRequestUsage` ਤੋਂ ਉੱਪਰ
  `src/lib/usage/usageHistory.ts` ਵਿੱਚ `export interface UsageEntry`), ਜਦੋਂ ਵੱਖ-ਵੱਖ
  ਰਾਈਟਰ ਕਤਾਰ ਨੂੰ ਪੜਾਅਵਾਰ ਭਰਦੇ ਹਨ ਤਾਂ ਵੱਖਰੇ ਫੀਲਡਾਂ ਨੂੰ ਵਿਕਲਪਿਕ/ਨੱਲਯੋਗ
  ਰੱਖੋ, ਅਤੇ ਅਜਿਹੇ ਫੀਲਡ ਲਈ ਜਿਸ ਦੀ ਬਣਤਰ ਵੱਖ-ਵੱਖ ਕਾਲਰਾਂ ਵਿੱਚ ਬਦਲਦੀ ਹੈ,
  `any` ਦੀ ਬਜਾਏ `unknown` ਨੂੰ ਤਰਜੀਹ ਦਿਓ (ਫੀਲਡ 'ਤੇ ਦਸਤਾਵੇਜ਼ਬੱਧ, ਉਦਾਹਰਨ ਲਈ `UsageEntry.tokens`
  ਕੱਚੀ ਪ੍ਰਦਾਤਾ-ਆਕਾਰ ਵਾਲੀ ਵਰਤੋਂ ਅਤੇ ਨਾਰਮਲਾਈਜ਼ ਕੀਤੀ ਬਣਤਰ ਦੋਵੇਂ ਸਵੀਕਾਰ ਕਰਦਾ ਹੈ)। ਜਦੋਂ ਕਿਸੇ
  ਫਾਈਲ ਦੀ `any` ਗਿਣਤੀ ਇਸ ਤਰ੍ਹਾਂ ਸਿਫ਼ਰ 'ਤੇ ਪਹੁੰਚ ਜਾਵੇ, ਤਾਂ ਉਸ ਨੂੰ
  `check:any-budget:t11` ਅਲਾਊਲਿਸਟ (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`) ਵਿੱਚ ਸ਼ਾਮਲ ਕਰੋ ਤਾਂ ਜੋ ਇਹ ਪਿੱਛੇ ਨਾ ਮੁੜ ਸਕੇ। ਇਹ ਪਹਿਲੇ-ਹਿੱਸੇ ਦੀ ਰਵਾਇਤ ਹੈ —
  ਵਿਆਪਕ "ਕੋਈ ਬੇਨਾਮ `any` ਨਹੀਂ" ਸਫਾਈ ਬਾਕੀ ਕੋਡਬੇਸ ਵਿੱਚ ਦੁਹਰਾਓ ਵਾਲੇ ਢੰਗ ਨਾਲ ਕੀਤੀ ਜਾਂਦੀ ਹੈ।
- **ਗਲਤੀਆਂ**: ਖਾਸ ਐਰਰ ਟਾਈਪਾਂ ਨਾਲ try/catch ਵਰਤੋ, pino ਕਾਂਟੈਕਸਟ ਨਾਲ ਲੌਗ ਕਰੋ। SSE ਸਟ੍ਰੀਮਾਂ ਵਿੱਚ
  ਗਲਤੀਆਂ ਨੂੰ ਕਦੇ ਵੀ ਚੁੱਪਚਾਪ ਨਾ ਦਬਾਓ; ਸਫਾਈ ਲਈ abort ਸਿਗਨਲ ਵਰਤੋ।
- **ਸੁਰੱਖਿਆ**: ਕਦੇ ਵੀ `eval()` / `new Function()` / implied 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. ਭੇਦ ਜਾਂ ਪ੍ਰਮਾਣ-ਪੱਤਰ ਕਦੇ ਵੀ ਕਮਿਟ ਨਾ ਕਰੋ।
2. ਕਦੇ ਵੀ ਬੈਰਲ-ਇੰਪੋਰਟ ਨਾ ਕਰੋ — ਖ਼ਾਸ `src/lib/db/*` ਮੋਡੀਊਲਾਂ ਨੂੰ ਸਿੱਧੇ ਵਰਤੋ।
3. ਕਦੇ ਵੀ `eval()` / `new Function()` / ਅਪ੍ਰਤੱਖ eval ਨਾ ਵਰਤੋ।
4. ਕਦੇ ਵੀ ਸਿੱਧੇ `main` ਵਿੱਚ ਕਮਿਟ ਨਾ ਕਰੋ।
5. ਰੂਟਾਂ ਵਿੱਚ ਕਦੇ ਵੀ ਕੱਚੀ SQL ਨਾ ਲਿਖੋ — ਹਮੇਸ਼ਾ `src/lib/db/` ਮੋਡੀਊਲਾਂ ਰਾਹੀਂ ਜਾਓ।
6. SSE ਸਟ੍ਰੀਮਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਨੂੰ ਕਦੇ ਵੀ ਚੁੱਪਚਾਪ ਅਣਡਿੱਠਾ ਨਾ ਕਰੋ।
7. ਇਨਪੁੱਟਾਂ ਨੂੰ ਹਮੇਸ਼ਾ Zod ਸਕੀਮਾਂ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਕਰੋ।
8. ਪ੍ਰੋਡਕਸ਼ਨ ਕੋਡ ਬਦਲਦੇ ਸਮੇਂ ਹਮੇਸ਼ਾ ਟੈਸਟ ਸ਼ਾਮਲ ਕਰੋ।
9. ਕਵਰੇਜ ≥ 60% ਰਹਿਣੀ ਲਾਜ਼ਮੀ ਹੈ (ਸਟੇਟਮੈਂਟ, ਲਾਈਨਾਂ, ਫੰਕਸ਼ਨ, ਬ੍ਰਾਂਚਾਂ)।

---

## 13. ਇਹ ਵੀ ਵੇਖੋ

- [ARCHITECTURE.md](./ARCHITECTURE.md) — ਉੱਚ-ਪੱਧਰੀ ਆਰਕੀਟੈਕਚਰ ਅਤੇ ਮੋਡੀਊਲਾਂ ਦੀਆਂ
  ਜ਼ਿੰਮੇਵਾਰੀਆਂ।
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — ਜਨਤਕ + ਪ੍ਰਬੰਧਨ API ਹਵਾਲਾ।
- [FEATURES.md](../guides/FEATURES.md) — ਵਿਸ਼ੇਸ਼ਤਾ ਮੈਟ੍ਰਿਕਸ ਅਤੇ ਵਰਜਨ ਦੀਆਂ ਮੁੱਖ ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ।
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — ਸਰਕਿਟ ਬ੍ਰੇਕਰ, ਕੂਲਡਾਊਨ ਅਤੇ
  ਲੌਕਆਊਟ ਬਾਰੇ ਡੂੰਘੀ ਜਾਣਕਾਰੀ।
- [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) — ਏਜੰਟਾਂ ਵੱਲੋਂ ਵਰਤਿਆ ਜਾਣ ਵਾਲਾ ਵਧੇਰੇ ਡੂੰਘਾ ਆਰਕੀਟੈਕਚਰ ਹਵਾਲਾ।