# Contributing to OmniRoute (ગુજરાતી)

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

---

Thank you for your interest in contributing! This guide covers everything you need to get started.

---

## વિકાસ સેટઅપ

### પૂર્વજરૂરિયાતો

- **Node.js** `>=22.22.2 <23`, અથવા `>=24.0.0 <27` (ભલામણ: 24 LTS)
- **npm** 10+

> **Node 24 સાથે Windows:** વર્તમાન 24 LTS પેચ રિલીઝનો ઉપયોગ કરો (ઓછામાં ઓછું 24.20.0).
> અગાઉની રિલીઝમાં `--test-force-exit` પ્રક્રિયા બંધ કરે ત્યારે સફળ પરીક્ષણો પછી પ્રક્રિયા અચાનક બંધ થઈ શકે છે.
> Node નું [Windows libuv સુધારણું](https://github.com/nodejs/node/pull/61999) આ રનટાઇમ ક્રેશને ઉકેલે છે; પરીક્ષણ assertions અને runner exit checks સક્રિય રાખો.

> **npm v11+ વપરાશકર્તાઓ (Node 24+):** `npm install` પછી, native modules ઇન્સ્ટોલ થયા છે તેની ચકાસણી કરો:
> `node -e "require('better-sqlite3')"`. જો તે `MODULE_NOT_FOUND` સાથે નિષ્ફળ જાય,
> તો `npm approve-scripts better-sqlite3 && npm install` ચલાવો. જુઓ
> [મુશ્કેલીનિવારણ](docs/guides/TROUBLESHOOTING.md#npm-v11-better-sqlite3-not-installed-cannot-find-module).

- **Git**

### ક્લોન અને ઇન્સ્ટોલ

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install
```

### પર્યાવરણ ચલો

```bash
# તમારા .env ને ટેમ્પલેટમાંથી બનાવો
cp .env.example .env

# જરૂરી secrets જનરેટ કરો
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
```

વિકાસ માટેના મુખ્ય ચલો:

| Variable               | Development Default      | Description                |
| ---------------------- | ------------------------ | -------------------------- |
| `PORT`                 | `20128`                  | સર્વર પોર્ટ                |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | ફ્રન્ટએન્ડ માટેનું બેઝ URL |
| `JWT_SECRET`           | (ઉપર જનરેટ કરો)          | JWT સાઇનિંગ secret         |
| `INITIAL_PASSWORD`     | `CHANGEME`               | પ્રથમ લૉગિન પાસવર્ડ        |
| `APP_LOG_LEVEL`        | `info`                   | લૉગની વિગતનું સ્તર         |

### ડેશબોર્ડ સેટિંગ્સ

ડેશબોર્ડ એવી સુવિધાઓ માટે UI ટૉગલ્સ પ્રદાન કરે છે, જેને પર્યાવરણ ચલો દ્વારા પણ ગોઠવી શકાય છે:

| Setting Location    | Toggle             | Description                       |
| ------------------- | ------------------ | --------------------------------- |
| Settings → Advanced | Debug Mode         | ડિબગ વિનંતી લૉગ્સ સક્રિય કરો (UI) |
| Settings → General  | Sidebar Visibility | સાઇડબાર વિભાગો બતાવો/છુપાવો       |

આ સેટિંગ્સ ડેટાબેઝમાં સંગ્રહિત થાય છે અને પુનઃપ્રારંભ પછી પણ જળવાઈ રહે છે; સેટ કરવામાં આવે ત્યારે તે env var ડિફૉલ્ટ્સને ઓવરરાઇડ કરે છે.

### સ્થાનિક રીતે ચલાવવું

```bash
# વિકાસ મોડ (હોટ રીલોડ)
npm run dev

# પ્રોડક્શન બિલ્ડ
npm run build    # next build → .build/next/ પછી assembleStandalone → dist/
npm run start

# યોગદાનકર્તાના ફેરફારો માટે ઝડપી backend/API-only કમ્પાઇલ
npm run build:contributor

# રિલીઝ બિલ્ડ (સ્વચ્છ પુનઃબિલ્ડ + HEAD sentinel — deploy માટે જરૂરી)
npm run build:release   # rm -rf .build dist અને પછી build + dist/BUILD_SHA લખે છે

# સામાન્ય પોર્ટ ગોઠવણી
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
```

યોગદાનકર્તા બિલ્ડ માત્ર કમ્પાઇલ-આધારિત માન્યતા કરે છે: તે standalone વિતરણ એસેમ્બલ કરતું નથી
અથવા વૈકલ્પિક native packaging assets બિલ્ડ કરતું નથી. જ્યારે મોકલી શકાય તેવા bundle ની
માન્યતા કરવાની જરૂર હોય ત્યારે નિયમિત પ્રોડક્શન બિલ્ડનો ઉપયોગ કરો.

### બિલ્ડ આઉટપુટ લેઆઉટ

| Directory | Contents                                                                          | Tracked |
| --------- | --------------------------------------------------------------------------------- | ------- |
| `src/`    | એપ્લિકેશન સ્રોત (TypeScript / TSX)                                                | હા      |
| `.build/` | મધ્યવર્તી ફાઇલો — `next build` આઉટપુટ (gitignored, `distDir = .build/next`)       | ના      |
| `dist/`   | મોકલી શકાય તેવું bundle — `assembleStandalone` દ્વારા એસેમ્બલ કરાયેલ (gitignored) | ના      |

બિલ્ડ પાઇપલાઇન એક જ પાસમાં ચાલે છે:

```
npm run build
  └─ next build → .build/next/standalone  (Next.js આઉટપુટ)
  └─ assembleStandalone()                 (standalone + static + public + native assets કૉપી કરે છે)
       └─ output: dist/                   (server.js, .next/static/, public/, node_modules/)
```

`npm run build:release` પહેલાં બંને ડિરેક્ટરીઓને સાફ કરે છે અને
`dist/BUILD_SHA` (= `git rev-parse --short HEAD`) ને deploy integrity sentinel તરીકે લખે છે.

`npm run build:contributor` backend-only બિલ્ડ પ્રોફાઇલનો ઉપયોગ કરે છે. બિલ્ડ કરતી વખતે તે
ડેશબોર્ડ UI ફાઇલોને તાત્પુરતી રીતે stubs કરે છે, API route handlers જાળવી રાખે છે અને બિલ્ડ
પછી મૂળ ફાઇલો પુનઃસ્થાપિત કરે છે. ડેશબોર્ડ UI ને અસર કરતા ફેરફારો માટે અથવા સંપૂર્ણ
રિલીઝ માન્યતા માટે `npm run build` નો ઉપયોગ કરો; contributor પ્રોફાઇલ release build નો
વિકલ્પ નથી.

> **VPS deploy નોંધ:** રિમોટ image ડિરેક્ટરી `/usr/lib/node_modules/omniroute/app/`
> બદલાતી નથી. deploy skills તેમાં `dist/` ની સામગ્રીને rsync કરે છે.
> માત્ર રિપોઝિટરીની અંદરનો બિલ્ડ આઉટપુટ પાથ બદલાયો છે (`app/` → `dist/`).

ડિફૉલ્ટ URLs:

- **ડેશબોર્ડ**: `http://localhost:20128/dashboard`
- **API**: `http://localhost:20128/v1`

---

## Git કાર્યપ્રવાહ

> ⚠️ **`main` પર ક્યારેય સીધું commit કરશો નહીં.** હંમેશાં feature branches નો ઉપયોગ કરો.
>
> **PR base:** સક્રિય `release/vX.Y.Z` branch ને લક્ષ્ય બનાવો (`main` ને નહીં). દરેક release માટે અલગ branch + ship સમયે tag ના મોડેલ માટે
> [`docs/ops/BRANCHING_MODEL.md`](docs/ops/BRANCHING_MODEL.md) જુઓ.

```bash
# સક્રિય release ના નવીનતમ સ્થાનથી branch બનાવો (ઉદાહરણ: release/v3.8.49)
git fetch origin
git checkout -b feat/your-feature-name origin/release/v3.8.49
# ... ફેરફારો કરો ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# base = release/v3.8.49 સાથે Pull Request ખોલો
```

### Branch નામકરણ

| Prefix      | હેતુ                      |
| ----------- | ------------------------- |
| `feat/`     | નવી સુવિધાઓ               |
| `fix/`      | Bug સુધારાઓ               |
| `refactor/` | Code નું પુનર્ગઠન         |
| `docs/`     | Documentation માં ફેરફારો |
| `test/`     | Test ઉમેરાઓ/સુધારાઓ       |
| `chore/`    | Tooling, CI, dependencies |

### Commit સંદેશાઓ

[Conventional Commits](https://www.conventionalcommits.org/) ને અનુસરો:

```
feat: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update SECURITY.md with PII protection
test: add observability unit tests
refactor(db): consolidate rate limit tables
```

Scopes (v3.8): `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`.

---

## ટેસ્ટ ચલાવવા

```bash
# બધા ટેસ્ટ (unit + vitest + ecosystem + e2e)
npm run test:all

# એક ટેસ્ટ ફાઇલ (Node.js નેટિવ ટેસ્ટ રનર — મોટાભાગના ટેસ્ટ આનો ઉપયોગ કરે છે)
node --import tsx/esm --test tests/unit/your-file.test.ts

# ફક્ત તમારા ફેરફારથી પ્રભાવિત unit ટેસ્ટ (CI gate જેવું જ TIA selector, #8084)
npm run test:scoped            # છેલ્લા commitમાં થયેલા ફેરફારો (અથવા working treeમાં)
npm run test:scoped:staged     # ફક્ત staged ફેરફારો — pre-commit run સાથે સારી રીતે કામ કરે છે
npm run test:scoped:full       # પહેલાં import-graph map ફરીથી બનાવે છે (ફાઇલો ઉમેર્યા/ખસેડ્યા પછી)
# Exit 1 + "સંપૂર્ણ suite ચલાવો"નો અર્થ છે કે hub file (tsconfig, package.json, …) અથવા
# unmapped source બદલાયો છે — selector સુરક્ષિત રીતે નિષ્ફળ જાય છે, તે ક્યારેય ચૂપચાપ છોડતું નથી.

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

# E2E ટેસ્ટ (Playwright જરૂરી છે)
npm run test:e2e

# Protocol clients E2E (MCP transports, A2A)
npm run test:protocols:e2e

# Ecosystem compatibility ટેસ્ટ
npm run test:ecosystem

# Coverage gate: statements/lines/functions/branches માટે 60%
npm run test:coverage
npm run coverage:report

# Lint + format તપાસ
npm run lint
npm run check

# Gate કરેલું વાસ્તવિક-upstream combo smoke (VPS access + વાસ્તવિક provider credits જરૂરી છે)
# વાસ્તવિક providersને hit કરે છે — થોડો ખર્ચ થાય છે. CIમાં ક્યારેય ચાલતું નથી. Gate વિના સ્વચ્છ રીતે skip થાય છે.
# જરૂરી છે: ssh root@192.168.0.15 access (VPSમાંથી read-only DB snapshot source કરે છે).
RUN_COMBO_LIVE=1 npm run test:combo:live

# Phase-3 VPS live smoke — સાદી Node ESM scripts, live .15 serverને સીધું hit કરે છે.
# જરૂરી છે: ssh root@192.168.0.15 access (combos SSH sqlite દ્વારા બનાવવામાં/દૂર કરવામાં આવે છે).
# વાસ્તવિક providersને hit કરે છે (નાનો ખર્ચ). ફક્ત __live_test__* combos બનાવે/કાઢી નાખે છે. CIમાં ક્યારેય ચાલતું નથી.
# .15 પર REQUIRE_API_KEY=false છે, તેથી API key જરૂરી નથી, પરંતુ જો સેટ કરેલી હોય તો COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEYનું પાલન કરે છે.
npm run test:combo:live:vps              # 7 HTTP scenarios (priority/round-robin/weighted/cost/fusion/auto + health)
npm run test:combo:live:vps:failover     # વાસ્તવિક cross-provider failover scenario ઉમેરે છે (કુલ 8)
```

Coverage નોંધો:

- `npm run test:coverage` મુખ્ય unit test suite માટે source coverage માપે છે, `tests/**`ને બાકાત રાખે છે અને `open-sse/**`ને સમાવે છે
- Pull requestsએ statements/lines/functions/branches માટે coverage gate **60%+** જાળવવો આવશ્યક છે
- જો PR `src/`, `open-sse/`, `electron/` અથવા `bin/`માં production code બદલે છે, તો એ જ PRમાં automated tests ઉમેરવા અથવા અપડેટ કરવા આવશ્યક છે
- `npm run coverage:report` તાજેતરના coverage runનો વિગતવાર file-by-file report પ્રિન્ટ કરે છે
- `npm run test:coverage:legacy` ઐતિહાસિક સરખામણી માટે જૂનું metric જાળવી રાખે છે
- તબક્કાવાર coverage સુધારણા roadmap માટે `docs/ops/COVERAGE_PLAN.md` જુઓ

### Pull Request માટેની આવશ્યકતાઓ

PR ખોલતાં પહેલાં, તમે જે બદલ્યું છે તેના માટે focused loop ચલાવવા
[Contribution Golden Path](docs/ops/CONTRIBUTION_GOLDEN_PATH.md)નો ઉપયોગ કરો. સંપૂર્ણ unit suite (4 CI shards), Vitest, **60%+** coverage gate અને
production build એ CIની જવાબદારી છે — તેમને સ્થાનિક રીતે ચલાવવાથી એવી કોઈ વધારાની માહિતી મળતી નથી જે PR
checks પહેલેથી જ નહીં આપે, અને નાનાં machines પર તે hostને સંપૂર્ણ રીતે વ્યસ્ત કરી શકે છે (#8084):

- તમારા ફેરફારને આવરી લેતી test files ચલાવો: `node --import tsx/esm --test tests/unit/<file>.test.ts`
- `npm run lint` ચલાવો
- જ્યારે પણ production code બદલાય ત્યારે એ જ PRમાં automated tests ઉમેરો અથવા અપડેટ કરો
- `node:test` filesમાં, દરેક top-level `await` (જેમ કે `await import(...)`)ને પ્રથમ `test()` / `describe()` પહેલાં મૂકો: `--test-force-exit` હેઠળ, તેના પછી નોંધાયેલા tests ક્યારેક કોઈ સૂચના વિના ચાલી જ ન શકે (#18045; `npm run check:test-tla-order` દ્વારા લાગુ કરવામાં આવે છે)
- production code બદલાયું હોય ત્યારે PR descriptionમાં બદલેલી અથવા ઉમેરેલી test filesનો સમાવેશ કરો
- જ્યારે project secrets CIમાં configured હોય ત્યારે PR પર SonarQube result તપાસો

હાલની test સ્થિતિ: **122 unit test files**, જે આને આવરી લે છે:

- Provider translators અને format conversion
- Rate limiting, circuit breaker અને resilience
- Semantic cache, idempotency અને progress tracking
- Database operations અને schema (21 DB modules)
- OAuth flows અને authentication
- API endpoint validation (Zod v4)
- MCP server tools અને scope enforcement
- Memory અને Skills systems

---

## કોડ શૈલી

- **ESLint** — કમિટ કરતાં પહેલાં `npm run lint` ચલાવો
- **Prettier** — કમિટ કરતી વખતે `lint-staged` દ્વારા આપમેળે ફોર્મેટ થાય છે (2 સ્પેસ, સેમિકોલન, ડબલ ક્વોટ્સ, 100 અક્ષરની પહોળાઈ, es5 ટ્રેલિંગ કોમા)
- **TypeScript** — `src/` નો તમામ કોડ `.ts`/`.tsx` નો ઉપયોગ કરે છે; `open-sse/` `.ts`/`.js` નો ઉપયોગ કરે છે; TSDoc (`@param`, `@returns`, `@throws`) વડે દસ્તાવેજીકરણ કરો
- **`eval()` નહીં** — ESLint `no-eval`, `no-implied-eval`, `no-new-func` લાગુ કરે છે
- **Zod માન્યતા** — તમામ API ઇનપુટની માન્યતા માટે Zod v4 સ્કીમાનો ઉપયોગ કરો
- **નામકરણ**: ફાઇલો = camelCase/kebab-case, કમ્પોનન્ટ્સ = PascalCase, કોન્સ્ટન્ટ્સ = UPPER_SNAKE

### ભૂલ સંચાલન / ખાલી catch બ્લોક્સ

ક્યારેય `catch` ને સમજૂતી વિના ન છોડો. તેને બેમાંથી એક શ્રેણીમાં વર્ગીકૃત કરો (આ
"SSE સ્ટ્રીમ્સમાં ભૂલોને ક્યારેય ચૂપચાપ અવગણવી નહીં" એવા કડક નિયમને વ્યવહારમાં મૂકે છે):

- **ઇરાદાપૂર્વક (અમારી પોતાની શ્રેષ્ઠ-પ્રયાસવાળી સફાઈ/ટેલિમેટ્રી)** — અહીં નિષ્ફળતા અપેક્ષિત અને
  હાનિરહિત છે; એક લીટીની કારણદર્શક ટિપ્પણી ઉમેરો, લોગિંગ નહીં (દરેક વિનંતી પર લોગિંગ કરવાથી થતો
  ઘોંઘાટ આ પ્રથા ટાળે છે).

  ```ts
  } catch {} // ક્લાયન્ટ ડિસ્કનેક્ટ થયા પછી પહેલેથી બંધ કંટ્રોલરને બંધ કરવાનો પ્રયાસ અપેક્ષિત છે
  ```

- **લોગ કરવું જોઈએ (બાહ્ય/કોલર દ્વારા આપવામાં આવેલ કોડ, અથવા અવગણવાથી નિયંત્રણ પ્રવાહ બદલાય)** — `catch`
  રાખો (તેને ક્યારેય સ્ટ્રીમ તોડવા ન દો), પરંતુ સંદર્ભયુક્ત `console.debug`/`warn` ઉત્સર્જિત કરો જેથી
  નિષ્ફળતા શોધી શકાય.

  ```ts
  } catch (e) {
    console.debug("[STREAM] onFailure callback error:", e);
  }
  ```

અમલમાં મૂકેલા ઉદાહરણો માટે `open-sse/utils/stream.ts` અને `open-sse/utils/streamHandler.ts` જુઓ.

---

## પ્રોજેક્ટ માળખું

```
src/                        # TypeScript (.ts / .tsx)
├── app/                    # Next.js 16 App Router
│   ├── (dashboard)/        # ડૅશબોર્ડ પૃષ્ઠો (23 વિભાગો)
│   ├── api/                # API રૂટ્સ (51 ડિરેક્ટરીઓ)
│   └── login/              # પ્રમાણીકરણ પૃષ્ઠો (.tsx)
├── domain/                 # નીતિ એન્જિન (policyEngine, comboResolver, costRules, વગેરે)
├── lib/                    # મુખ્ય વ્યવસાયિક તર્ક (.ts)
│   ├── a2a/                # Agent-to-Agent v0.3 પ્રોટોકોલ સર્વર
│   ├── acp/                # Agent Communication Protocol રજિસ્ટ્રી
│   ├── compliance/         # અનુપાલન નીતિ એન્જિન
│   ├── db/                 # SQLite ડોમેન મોડ્યુલો + 130 માઇગ્રેશન્સ
│   ├── memory/             # સતત સંવાદાત્મક મેમરી
│   ├── oauth/              # OAuth પ્રદાતાઓ, સેવાઓ અને ઉપયોગિતાઓ
│   ├── skills/             # વિસ્તારી શકાય તેવું કૌશલ્ય ફ્રેમવર્ક
│   ├── usage/              # ઉપયોગ ટ્રૅકિંગ અને ખર્ચ ગણતરી
│   └── localDb.ts          # માત્ર ફરીથી નિકાસ કરતું સ્તર — અહીં ક્યારેય તર્ક ઉમેરશો નહીં
├── middleware/              # વિનંતી મિડલવેર (promptInjectionGuard)
├── mitm/                   # MITM પ્રૉક્સી (પ્રમાણપત્ર, DNS, લક્ષ્ય રૂટિંગ)
├── shared/
│   ├── components/         # React ઘટકો (.tsx)
│   ├── constants/          # પ્રદાતા વ્યાખ્યાઓ (329), MCP સ્કોપ્સ, 20 રૂટિંગ વ્યૂહરચનાઓ
│   ├── utils/              # સર્કિટ બ્રેકર, સેનિટાઇઝર, પ્રમાણીકરણ સહાયકો
│   └── validation/         # Zod v4 સ્કીમા
└── sse/                    # SSE પ્રૉક્સી પાઇપલાઇન

open-sse/                   # @omniroute/open-sse વર્કસ્પેસ
├── executors/              # 150 એક્ઝિક્યુટર મોડ્યુલો (એક્ઝિક્યુટર ક્લાસ + દરેક પ્રદાતા માટેના સહાયકો)
├── handlers/               # 11 વિનંતી હૅન્ડલર્સ (ચેટ, પ્રતિસાદો, એમ્બેડિંગ્સ, છબીઓ, વગેરે)
├── mcp-server/             # MCP સર્વર (110 અનન્ય ટૂલ્સ, 3 ટ્રાન્સપોર્ટ્સ, 33 સ્કોપ્સ)
├── services/               # 178 ટોચના સ્તરની સેવાઓ (combo, autoCombo, rateLimitManager, વગેરે)
├── translator/             # ફોર્મેટ અનુવાદકો (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/            # Responses API ટ્રાન્સફોર્મર
└── utils/                  # 22 ઉપયોગિતા મોડ્યુલો (સ્ટ્રીમ, TLS, પ્રૉક્સી, લૉગિંગ)

electron/                   # Electron ડેસ્કટૉપ ઍપ (ક્રૉસ-પ્લૅટફૉર્મ)

tests/
├── unit/                   # Node.js ટેસ્ટ રનર (1,574 ટેસ્ટ ફાઇલો)
├── integration/            # ઇન્ટિગ્રેશન ટેસ્ટ્સ
├── e2e/                    # Playwright ટેસ્ટ્સ
├── security/               # સુરક્ષા ટેસ્ટ્સ
├── translator/             # અનુવાદક-વિશિષ્ટ ટેસ્ટ્સ
└── load/                   # લોડ ટેસ્ટ્સ

docs/
├── adr/                     # આર્કિટેક્ચર નિર્ણય રેકોર્ડ્સ
├── architecture/            # સિસ્ટમ આર્કિટેક્ચર અને સ્થિતિસ્થાપકતા
├── comparison/              # OmniRoute અને વિકલ્પોની તુલના
├── compression/             # કમ્પ્રેશન માર્ગદર્શિકાઓ અને નિયમો
├── dev/                     # ડેવલપમેન્ટ માર્ગદર્શિકાઓ
├── diagrams/                # આર્કિટેક્ચર આકૃતિઓ
├── frameworks/              # MCP, A2A, OpenCode, Memory, Skills
├── guides/                  # વપરાશકર્તા માર્ગદર્શિકા, Docker, સેટઅપ, સમસ્યાનિવારણ
├── i18n/                    # આંતરરાષ્ટ્રીયકૃત README અનુવાદો
├── marketing/               # માર્કેટિંગ સામગ્રી
├── ops/                     # ડિપ્લોયમેન્ટ, પ્રૉક્સી, કવરેજ, રિલીઝ
├── providers/               # પ્રદાતા-વિશિષ્ટ દસ્તાવેજો
├── reference/               # API સંદર્ભ, પર્યાવરણ ચલો, CLI ટૂલ્સ, મફત સ્તરો
├── releases/                # રિલીઝ નોંધો
├── routing/                 # સ્વચાલિત-કોમ્બો એન્જિન, રીઝનિંગ રીપ્લે
├── screenshots/             # ડૅશબોર્ડ સ્ક્રીનશૉટ્સ
├── security/                # સુરક્ષા નિયંત્રણો, અનુપાલન, સ્ટેલ્થ, ટોકન્સ
└── specs/                   # ડિઝાઇન સ્પષ્ટીકરણો
```

---

## નવો પ્રદાતા ઉમેરવો

### પગલું 1: પ્રદાતાના સ્થિરાંકોની નોંધણી કરો

`src/shared/constants/providers.ts`માં ઉમેરો — મોડ્યુલ લોડ થતી વખતે Zod દ્વારા માન્યતા ચકાસવામાં આવે છે.

### પગલું 2: એક્ઝિક્યુટર ઉમેરો (જો કસ્ટમ લોજિકની જરૂર હોય)

બેઝ એક્ઝિક્યુટરને વિસ્તૃત કરતું એક્ઝિક્યુટર `open-sse/executors/your-provider.ts`માં બનાવો.

### પગલું 3: ટ્રાન્સલેટર ઉમેરો (જો ફોર્મેટ OpenAI ન હોય)

`open-sse/translator/`માં રિક્વેસ્ટ/રિસ્પોન્સ ટ્રાન્સલેટર બનાવો.

### પગલું 4: OAuth કૉન્ફિગ ઉમેરો (જો OAuth-આધારિત હોય)

`src/lib/oauth/constants/oauth.ts`માં OAuth ક્રેડેન્શિયલ્સ અને `src/lib/oauth/services/`માં સર્વિસ ઉમેરો.

જો અપસ્ટ્રીમ પ્રદાતા તેની જાહેર CLI / બ્રાઉઝર બંડલમાં જાહેર OAuth client_id/secret અથવા Firebase Web API કી વિતરિત કરતો હોય, તો તેને સ્ટ્રિંગ લિટરલ તરીકે **એમ્બેડ કરશો નહીં**. `open-sse/utils/publicCreds.ts`માંથી `resolvePublicCred()`નો ઉપયોગ કરો અને `EMBEDDED_DEFAULTS`માં માસ્ક કરેલી બાઇટ એન્ટ્રી ઉમેરો. સંપૂર્ણ ફરજિયાત કાર્યપ્રવાહનું દસ્તાવેજીકરણ [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)માં કરેલું છે.

હેન્ડલર્સ/એક્ઝિક્યુટર્સની અંદર, ક્લાયન્ટ સુધી પહોંચતા ભૂલ સંદેશાઓ `open-sse/utils/error.ts`માંથી `buildErrorBody()` / `sanitizeErrorMessage()` મારફતે જ પસાર થવા જોઈએ — Response બૉડીમાં ક્યારેય કાચું `err.stack` અથવા `err.message` મૂકશો નહીં. [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) જુઓ.

### પગલું 5: મોડેલોની નોંધણી કરો

`open-sse/config/providerRegistry.ts`માં મોડેલની વ્યાખ્યાઓ ઉમેરો.

### પગલું 6: પરીક્ષણો ઉમેરો

ઓછામાં ઓછા નીચેની બાબતોને આવરી લેતા યુનિટ પરીક્ષણો `tests/unit/`માં લખો:

- પ્રદાતાની નોંધણી
- રિક્વેસ્ટ/રિસ્પોન્સ ટ્રાન્સલેશન
- ભૂલ વ્યવસ્થાપન

---

## Pull Request ચેકલિસ્ટ

- [ ] ટેસ્ટ્સ પાસ થાય છે (`npm test`)
- [ ] લિન્ટિંગ પાસ થાય છે (`npm run lint`)
- [ ] બિલ્ડ સફળ થાય છે (`npm run build`)
- [ ] નવા સાર્વજનિક ફંક્શન્સ અને ઇન્ટરફેસ માટે TypeScript પ્રકારો ઉમેર્યા છે
- [ ] કોઈ હાર્ડકોડેડ સિક્રેટ્સ અથવા ફૉલબૅક મૂલ્યો નથી
- [ ] સાર્વજનિક અપસ્ટ્રીમ ક્રેડેન્શિયલ્સ `resolvePublicCred()` મારફતે એમ્બેડ કર્યાં છે ([`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md) જુઓ), ક્યારેય લિટરલ્સ તરીકે નહીં
- [ ] ભૂલ પ્રતિસાદો `buildErrorBody()` / `sanitizeErrorMessage()` મારફતે રૂટ થાય છે — પ્રતિસાદ બોડીમાં કોઈ કાચા સ્ટૅક ટ્રેસ નથી ([`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) જુઓ)
- [ ] શેલ કમાન્ડ્સ (`exec` / `spawn`) રનટાઇમ મૂલ્યોને સ્ટ્રિંગ ઇન્ટરપોલેશન મારફતે નહીં, પરંતુ `env` મારફતે પસાર કરે છે
- [ ] બધા ઇનપુટ્સ Zod સ્કીમા વડે માન્ય કરેલા છે
- [ ] વપરાશકર્તાને અસર કરતા ફેરફારો માટે `changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md` હેઠળ ચેન્જલૉગ **ફ્રેગમેન્ટ** ઉમેર્યો છે ([`changelog.d/README.md`](./changelog.d/README.md) જુઓ) — `CHANGELOG.md`ને સીધું સંપાદિત કરશો **નહીં**; ફ્રેગમેન્ટ્સને રિલીઝ સમયે એકત્રિત કરવામાં આવે છે અને PRs વચ્ચે ક્યારેય સંઘર્ષ થતો નથી
- [ ] દસ્તાવેજીકરણ અપડેટ કર્યું છે (જો લાગુ પડતું હોય)
- [ ] કોઈ નવી CodeQL / Secret-Scanning ચેતવણીઓ ખોલવામાં આવી નથી, અથવા દરેકને સંબંધિત `docs/security/` દસ્તાવેજનો સંદર્ભ આપતા ટેક્નિકલ વાજબીકરણ સાથે રદ કરવામાં આવી છે
- [ ] ચાઇલ્ડ પ્રોસેસ શરૂ કરતા રૂટ્સ (`/api/mcp/`, `/api/cli-tools/runtime/`)ને `src/server/authz/routeGuard.ts`માં `isLocalOnlyPath()` તરીકે વર્ગીકૃત કર્યા છે — [કડક નિયમ #15](docs/security/ROUTE_GUARD_TIERS.md) જુઓ
- [ ] કમિટ સંદેશાઓમાં AI/બોટ `Co-authored-by` ટ્રેલર્સ નથી (કડક નિયમ #16) — જે માનવીય સહયોગીઓના કાર્યનો પુનઃઉપયોગ થયો છે તેમને પ્રમાણભૂત `Co-authored-by: Name <email>` ટ્રેલર્સ દ્વારા શ્રેય આપવામાં આવ્યો છે

---

## રિલીઝિંગ

રિલીઝનું સંચાલન `/generate-release` વર્કફ્લો દ્વારા થાય છે. જ્યારે નવી GitHub Release બનાવવામાં આવે છે, ત્યારે પેકેજ GitHub Actions દ્વારા **આપમેળે npm પર પ્રકાશિત થાય છે**.

VPS ડિપ્લોયમેન્ટ માટે, `npm run build:release` નો ઉપયોગ કરો (`npm run build` નો નહીં) — તે સ્વચ્છ
રીબિલ્ડ કરે છે, બંડલને `dist/` માં એસેમ્બલ કરે છે અને `dist/BUILD_SHA` સેન્ટિનલ લખે છે.
ત્યારબાદ રિમોટ `app/` ડિરેક્ટરીમાં `dist/` ને rsync કરતી `/deploy-vps-*-cc` સ્કિલ્સનો ઉપયોગ કરો.

---

## મદદ મેળવવી

- **આર્કિટેક્ચર**: [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) જુઓ
- **API સંદર્ભ**: [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) જુઓ
- **સુરક્ષા દસ્તાવેજો**: [`docs/security/CLI_TOKEN.md`](docs/security/CLI_TOKEN.md), [`docs/security/ROUTE_GUARD_TIERS.md`](docs/security/ROUTE_GUARD_TIERS.md), [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md), [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)
- **ઓપરેશન્સ દસ્તાવેજો**: [`docs/ops/SQLITE_RUNTIME.md`](docs/ops/SQLITE_RUNTIME.md)
- **સમસ્યાઓ**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)