# CLAUDE.md (தமிழ்)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)

---

இந்த கோப்பு இந்த சேமிப்பகத்தில் குறியீட்டுடன் வேலை செய்யும் போது Claude Code (claude.ai/code) க்கு வழிகாட்டுதலை வழங்குகிறது.

## விரைவான தொடக்கம்

```bash
npm install                    # சார்புகளை நிறுவவும் (.env.example இலிருந்து .env ஐ தானாக உருவாக்குகிறது)
npm run dev                    # http://localhost:20128 இல் டெவ் சர்வர்
npm run build                  # உற்பத்தி கட்டமைப்பு (Next.js 16 தனித்தனி)
npm run lint                   # ESLint (0 பிழைகள் எதிர்பார்க்கப்படுகின்றன; எச்சரிக்கைகள் முன்னதாகவே உள்ளன)
npm run typecheck:core         # TypeScript சரிபார்ப்பு (சுத்தமாக இருக்க வேண்டும்)
npm run typecheck:noimplicit:core  # கடுமையான சரிபார்ப்பு (எந்த implicit any இல்லை)
npm run test:coverage          # யூனிட் சோதனைகள் + கவரேஜ் கேட் (75/75/75/70 — அறிக்கைகள்/வரிசைகள்/செயல்பாடுகள்/கிளைகள்)
npm run check                  # lint + சோதனை ஒன்றிணைக்கப்பட்டது
npm run check:cycles           # சுற்றுப்பாதை சார்ந்த சார்புகளை கண்டறியவும்
```

### சோதனைகளை இயக்குதல்

```bash
# ஒற்றை சோதனை கோப்பு (Node.js உள்ளூர் சோதனை இயக்கி — பெரும்பாலான சோதனைகள்)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP சர்வர், autoCombo, cache)
npm run test:vitest

# அனைத்து சோதனைகள்
npm run test:all
```

முழு சோதனை மேட்ரிக்ஸ் க்காக, `CONTRIBUTING.md` → "சோதனைகளை இயக்குதல்" ஐப் பார்க்கவும். ஆழமான கட்டமைப்பிற்காக, `AGENTS.md` ஐப் பார்க்கவும்.

---

## திட்டம் ஒரு பார்வையில்

**OmniRoute** — ஒருங்கிணைந்த AI பிராக்சி/ரூட்டர். ஒரு முடிவிடம், 160+ LLM வழங்குநர்கள், தானாகவே fallback.

| அடுக்கு       | இடம்                    | நோக்கம்                                                                         |
| ------------- | ----------------------- | ------------------------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Next.js ஆப் ரூட்டர் — நுழைவு புள்ளிகள்                                          |
| Handlers      | `open-sse/handlers/`    | கோரிக்கைகளை செயலாக்குதல் (சாட், எம்பெட்டிங்ஸ், மற்றும் பிற)                     |
| Executors     | `open-sse/executors/`   | வழங்குநர்-சிறப்பு HTTP அனுப்புதல்                                               |
| Translators   | `open-sse/translator/`  | வடிவ மாற்றம் (OpenAI↔Claude↔Gemini)                                             |
| Transformer   | `open-sse/transformer/` | பதில்கள் API ↔ சாட் முழுமைகள்                                                   |
| Services      | `open-sse/services/`    | காம்போ ரூட்டிங், விகித வரம்புகள், கச்சா, மற்றும் பிற                            |
| Database      | `src/lib/db/`           | SQLite டொமைன் மாடுல்கள் (45+ கோப்புகள், 55 மைக்ரேஷன்கள்)                        |
| Domain/Policy | `src/domain/`           | கொள்கை இயந்திரம், செலவுக் கட்டுப்பாடுகள், fallback உள்கட்டமைப்பு                |
| MCP Server    | `open-sse/mcp-server/`  | 37 கருவிகள் (30 அடிப்படை + 3 நினைவகம் + 4 திறன்கள்), 3 போக்குகள், ~13 பரப்புகள் |
| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 முகவர் புரொட்டோக்கால்                                              |
| Skills        | `src/lib/skills/`       | விரிவாக்கத்திற்குரிய திறன் கட்டமைப்பு                                           |
| Memory        | `src/lib/memory/`       | நிலையான உரையாடல் நினைவகம்                                                       |

Monorepo: `src/` (Next.js 16 ஆப்), `open-sse/` (ஸ்ட்ரீமிங் இயந்திர வேலைப்பாடு), `electron/` (டெஸ்க்டாப் ஆப்), `tests/`, `bin/` (CLI நுழைவு புள்ளி).

---

## கோரிக்கை குழாய்

```
Client → /v1/chat/completions (Next.js பாதை)
  → CORS → Zod சரிபார்ப்பு → அங்கீகாரம்? → கொள்கை சரிபார்ப்பு → முன்மொழிவு ஊடுருவல் பாதுகாப்பு
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → கச்சா சரிபார்ப்பு → விகிதம் வரம்பு → கம்போ வழிமுறை?
      → resolveComboTargets() → handleSingleModel() ஒவ்வொரு இலக்கத்திற்கும்
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() மேல்நிலை → மீண்டும் முயற்சி w/ backoff
    → பதில்கள் மொழிபெயர்ப்பு → SSE ஓட்டம் அல்லது JSON
    → பதில்கள் API: responsesTransformer.ts TransformStream
```

API பாதைகள் ஒரே மாதிரியான வடிவத்தை பின்பற்றுகின்றன: `Route → CORS முன்பார்வை → Zod உடல் சரிபார்ப்பு → விருப்ப அங்கீகாரம் (extractApiKey/isValidApiKey) → API விசை கொள்கை அமலாக்கம் → கைப்பற்றுதல் ஒப்படைப்பு (open-sse)`. உலகளாவிய Next.js மிடில்வேர் இல்லை — இடைமுகம் பாதை-சிறப்பு.

**கம்போ வழிமுறை** (`open-sse/services/combo.ts`): 14 உத்திகள் (முதன்மை, எடை, நிரப்புதல்-முதல், சுற்று-ரொபின், P2C, சீரற்ற, குறைந்த-பயன்பாடு, செலவுக்கேற்ப, மீட்டமைப்பு-அறிவு, கடுமையான-சீரற்ற, தானாக, lkgp, சூழல்-சீரமைக்கப்பட்ட, சூழல்-மாற்று). ஒவ்வொரு இலக்கமும் `handleSingleModel()` ஐ அழைக்கிறது, இது `handleChatCore()` ஐ ஒவ்வொரு இலக்கத்திற்கும் பிழை கையாளுதல் மற்றும் சுற்று முறையீட்டு சரிபார்ப்புடன் சுற்றி விடுகிறது. 9-உயர்தர Auto-Combo மதிப்பீட்டிற்கான `docs/routing/AUTO-COMBO.md` ஐப் பார்க்கவும் மற்றும் 3 நிலைத்தன்மை அடுக்குகளுக்கான `docs/architecture/RESILIENCE_GUIDE.md` ஐப் பார்க்கவும்.

---

## நிலைத்தன்மை இயக்கநிலை நிலை

OmniRoute இல் மூன்று தொடர்புடைய ஆனால் தனித்துவமான தற்காலிக-தவறுகள் முறைமைகள் உள்ளன. வழிமுறை நடத்தை பிழைகளை சரிசெய்யும் போது அவற்றின் பரப்பை தனியாக வைத்திருக்கவும். ஒரு பார்வையில் வரைபடத்திற்கான
[3-அடுக்கு நிலைத்தன்மை வரைபடம்](./docs/diagrams/exported/resilience-3layers.svg)
(மூல: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)) ஐப் பார்க்கவும்.

### வழங்குநர் சுற்று முறையீட்டு

**பரப்பு**: முழு வழங்குநர், உதாரணமாக `glm`, `openai`, `anthropic`.

**நோக்கம்**: மேல்நிலை/சேவைக் கட்டத்தில் மீண்டும் மீண்டும் தோல்வியுறும் வழங்குநருக்கு போக்குவரத்தை அனுப்புவதை நிறுத்தவும், எனவே ஒரு ஆரோக்கியமற்ற வழங்குநர் ஒவ்வொரு கோரிக்கையையும் மெதுவாக்காது.

**அமலாக்கம்**:

- மைய வகுப்பு: `src/shared/utils/circuitBreaker.ts`
- உரையாடல் வாயில்/செயலாக்க இணைப்பு: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- இயக்கநிலை நிலை API: `src/app/api/monitoring/health/route.ts`
- பகிரப்பட்ட மூடியங்கள்: `open-sse/services/accountFallback.ts`
- நிலைத்த நிலை அட்டவணை: `domain_circuit_breakers`

**நிலைகள்**:

- `CLOSED`: சாதாரண போக்குவரத்து அனுமதிக்கப்படுகிறது.
- `OPEN`: வழங்குநர் தற்காலிகமாக தடைக்கப்பட்டுள்ளது; அழைப்பாளர்கள் வழங்குநர்-சுற்று-திறந்த பதிலைப் பெறுகிறார்கள் அல்லது கம்போ வழிமுறை மற்றொரு இலக்கத்திற்கு தவிர்க்கிறது.
- `HALF_OPEN`: மீட்டமைப்பு காலம் முடிந்தது; ஒரு சோதனை கோரிக்கையை அனுமதிக்கவும். வெற்றி சுற்று முறையீட்டை மூடுகிறது, தோல்வி அதை மீண்டும் திறக்கிறது.

**இயல்புகள்** (`open-sse/config/constants.ts`):

- OAuth வழங்குநர்கள்: தற்காலிகம் `3`, மீட்டமைப்பு காலம் `60s`.
- API-விசை வழங்குநர்கள்: தற்காலிகம் `5`, மீட்டமைப்பு காலம் `30s`.
- உள்ளூர் வழங்குநர்கள்: தற்காலிகம் `2`, மீட்டமைப்பு காலம் `15s`.

மட்டுமே வழங்குநர்-நிலை தோல்வி நிலைகள் வழங்குநர் சுற்று முறையீட்டைத் தூண்ட வேண்டும்:

```ts
(408, 500, 502, 503, 504);
```

சாதாரண கணக்கு/விசை/மாதிரி பிழைகள் போன்ற `401`, `403`, அல்லது `429` வழக்கங்களுக்கு முழு-வழங்குநர் சுற்று முறையீட்டைத் தூண்ட வேண்டாம். அவை பொதுவாக இணைப்பு குளிர்ச்சி அல்லது மாதிரி பூட்டுதலுக்குச் சொந்தமாகும். ஒரு பொதுவான API-விசை வழங்குநர் `403` மீண்டும் பெறக்கூடியதாக இருக்க வேண்டும், அது இறுதி வழங்குநர்/கணக்கு பிழையாக வகைப்படுத்தப்படவில்லை.

சுற்று முறையீடு சோம்பல் மீட்பு பயன்படுத்துகிறது, பின்னணி நேரம் அல்ல. `OPEN` காலம் முடிந்தவுடன், `getStatus()`, `canExecute()`, மற்றும் `getRetryAfterMs()` போன்ற வாசிப்புகள் நிலையை `HALF_OPEN` ஆக புதுப்பிக்கின்றன, எனவே டாஷ்போர்டுகள் மற்றும் கம்போ வேட்பாளர் கட்டுப்படுத்திகள் காலாவதியான வழங்குநரை எப்போதும் தவிர்க்கவில்லை.

### இணைப்பு குளிர்ச்சி

**பரப்பு**: ஒரு வழங்குநர் இணைப்பு/கணக்கு/விசை.

**நோக்கம்**: ஒரே மோசமான விசை/கணக்கை தற்காலிகமாக தவிர்க்கவும், அதே வழங்குநருக்கான பிற இணைப்புகளை கோரிக்கைகளை சேவையளிக்க தொடர அனுமதிக்கவும்.

**அமலாக்கம்**:

- எழுத/புதுப்பிக்க பாதை: `src/sse/services/auth.ts::markAccountUnavailable()`
- கணக்கு தேர்வு/வடிகட்டி: `src/sse/services/auth.ts::getProviderCredentials...`
- குளிர்ச்சி கணக்கீடு: `open-sse/services/accountFallback.ts::checkFallbackError()`
- அமைப்புகள்: `src/lib/resilience/settings.ts`

வழங்குநர் இணைப்பில் முக்கியமான புலங்கள்:

```ts
rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;
```

கணக்கு தேர்வின் போது, ஒரு இணைப்பு தவிர்க்கப்படுகிறது:

```ts
new Date(rateLimitedUntil).getTime() > Date.now();
```

குளிர்ச்சிகள் சோம்பல் ஆகவும் உள்ளன: `rateLimitedUntil` கடந்த காலத்தில் இருந்தால், இணைப்பு மீண்டும் தகுதியானதாக மாறுகிறது. வெற்றிகரமாகப் பயன்படுத்தும் போது, `clearAccountError()` `testStatus`, `rateLimitedUntil`, பிழை புலங்கள், மற்றும் `backoffLevel` ஐ அழிக்கிறது.

இயல்பான இணைப்பு குளிர்ச்சி நடத்தை:

- OAuth அடிப்படை குளிர்ச்சி: `5s`.
- API-விசை அடிப்படை குளிர்ச்சி: `3s`.
- API-விசை `429` கிடைக்கும்போது மேல்நிலை மீண்டும் முயற்சி குறிப்பு (`Retry-After`, மீட்டமைப்பு தலைப்புகள், அல்லது வாசிக்கக்கூடிய மீட்டமைப்பு உரை) என்பவற்றை முன்னுரிமை அளிக்க வேண்டும்.
- மீண்டும் பெறக்கூடிய தோல்விகள் எக்ஸ்போனென்ஷியல் பின்வாங்குதலைப் பயன்படுத்துகின்றன:

```ts
baseCooldownMs * 2 ** failureIndex;
```

எதிர்மறை-தூண்டுதல்-மூடுபனி பாதுகாப்பு ஒரே இணைப்பில் ஒரே நேரத்தில் தோல்விகளை மீண்டும் மீண்டும் குளிர்ச்சியை நீட்டிக்கவோ அல்லது `backoffLevel` ஐ இரட்டிப்பாக அதிகரிக்கவோ தடுக்கும்.

இறுதி நிலைகள் குளிர்ச்சிகள் அல்ல. `banned`, `expired`, மற்றும் `credits_exhausted` ஆகியவை சான்றிதழ்கள்/அமைப்புகள் மாறும் வரை அல்லது ஒரு செயல்பாட்டாளர் அவற்றை மீட்டமைக்கும் வரை கிடைக்காதவையாக இருக்க வேண்டும். தற்காலிக குளிர்ச்சி நிலை மூலம் இறுதி நிலைகளை மீட்டமைக்க வேண்டாம்.

### மாதிரி பூட்டுதல்

**பரப்பு**: வழங்குநர் + இணைப்பு + மாதிரி.

**நோக்கம்**: ஒரு மாதிரி கிடைக்காத அல்லது அந்த இணைப்புக்கான அளவீட்டு-கட்டுப்பாட்டில் உள்ள போது முழு இணைப்பை முடக்காமல் இருக்கவும்.

உதாரணங்கள்:

- மாதிரி-அளவீட்டு வழங்குநர்கள் `429` ஐ திருப்பி அனுப்புவது.
- ஒரு காணாமல் போன மாதிரிக்காக உள்ளூர் வழங்குநர்கள் `404` ஐ திருப்பி அனுப்புவது.
- தேர்ந்தெடுக்கப்பட்ட Grok முறைகள் போன்ற வழங்குநர்-சிறப்பு முறை/மாதிரி அனுமதி தோல்விகள்.

மாதிரி பூட்டுதல் `open-sse/services/accountFallback.ts` இல் வாழ்கிறது மற்றும் அதே இணைப்பை மற்ற மாதிரிகளை சேவையளிக்க தொடர அனுமதிக்கிறது.

### பிழைதிருத்த வழிகாட்டுதல்

- ஒரு வழங்குநருக்கான அனைத்து விசைகளும் தவிர்க்கப்பட்டால், வழங்குநர் சுற்று முறையீட்டு நிலை மற்றும் ஒவ்வொரு இணைப்பின் `rateLimitedUntil`/`testStatus` ஐப் பரிசீலிக்கவும்.
- மீட்டமைப்பு ஜன்னலுக்குப் பிறகு ஒரு வழங்குநர் நிரந்தரமாக தவிர்க்கப்பட்டதாக தோன்றினால், குறியீடு `getStatus()`/`canExecute()` ஐப் பயன்படுத்துவதற்குப் பதிலாக கச்சா `state` ஐப் படிக்கிறதா என்பதைச் சரிபார்க்கவும்.
- ஒரு வழங்குநர் விசை தோல்வியுறும் ஆனால் மற்றவை வேலை செய்ய வேண்டும் என்றால், வழங்குநர் சுற்று முறையீட்டுக்கு பதிலாக இணைப்பு குளிர்ச்சியை முன்னுரிமை அளிக்கவும்.
- ஒரே மாதிரி தோல்வியுறும் போது, மாதிரி பூட்டுதலுக்கு பதிலாக இணைப்பு குளிர்ச்சியை முன்னுரிமை அளிக்கவும்.
- ஒரு நிலை தானாக மீண்டும் பெற வேண்டும் என்றால், அதில் எதிர்கால காலம்/மீட்டமைப்பு காலம் மற்றும் காலாவதியான நிலையை புதுப்பிக்கும் வாசிப்பு பாதை இருக்க வேண்டும். நிரந்தர நிலைகள் கையேடு சான்றிதழ் அல்லது கட்டமைப்பு மாற்றங்களை தேவைப்படுத்துகின்றன.

## முக்கிய ஒழுங்குகள்

### குறியீட்டு பாணி

- **2 இடங்கள்**, செமிகோலன், இரட்டை மேற்கோள்கள், 100 எழுத்து அகலம், es5 பின்னணி கமா (lint-staged மூலம் Prettier மூலம் கட்டாயமாக்கப்பட்டது)
- **இறக்குமதிகள்**: வெளிப்புறம் → உள்ளகம் (`@/`, `@omniroute/open-sse`) → தொடர்புடைய
- **பெயரிடுதல்**: கோப்புகள்=camelCase/kebab, கூறுகள்=PascalCase, நிலையானவை=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = எங்கு வேண்டுமானாலும் பிழை; `no-explicit-any` = `open-sse/` மற்றும் `tests/` இல் எச்சரிக்கை
- **TypeScript**: `strict: false`, இலக்கு ES2022, தொகுப்பு esnext, தீர்வு bundler. தெளிவான வகைகளை முன்னுரிமை கொடுக்கவும்.

### தரவுத்தளம்

- **எப்போதும்** `src/lib/db/` டொமைன் மாடுல்களைப் பயன்படுத்தவும் — **எப்போதும்** வழிகளில் அல்லது கையாளர்களில் கச்சித SQL எழுத வேண்டாம்
- **எப்போதும்** `src/lib/localDb.ts` இல் தரவுத்தொகுப்புகளைச் சேர்க்க வேண்டாம் (மறு-வெளியீட்டு அடுக்கு மட்டும்)
- **எப்போதும்** `localDb.ts` இல் இருந்து ப barrel-import செய்ய வேண்டாம் — குறிப்பிட்ட `db/` மாடுல்களைப் பயன்படுத்தவும்
- DB ஒரே மாதிரியானது: `getDbInstance()` `src/lib/db/core.ts` இல் இருந்து (WAL பதிவேற்றம்)
- மைக்ரேஷன்கள்: `src/lib/db/migrations/` — பதிப்பு கொண்ட SQL கோப்புகள், idempotent, பரிவர்த்தனைகளில் இயக்கவும்

### பிழை கையாளுதல்

- குறிப்பிட்ட பிழை வகைகளுடன் try/catch, pino சூழ்நிலையுடன் பதிவு செய்யவும்
- SSE ஓட்டங்களில் பிழைகளை அடிக்கடி அடிக்க வேண்டாம் — சுத்தம் செய்ய abort சிக்னல்களைப் பயன்படுத்தவும்
- சரியான HTTP நிலை குறியீடுகளை திருப்பவும் (4xx/5xx)

### பாதுகாப்பு

- **எப்போதும்** `eval()`, `new Function()`, அல்லது குறிக்கோள் மதிப்பீடு பயன்படுத்த வேண்டாம்
- அனைத்து உள்ளீடுகளையும் Zod வடிவமைப்புகளுடன் சரிபார்க்கவும்
- ஓய்வில் உள்ள அங்கீகாரங்களை குறியாக்கிக்கொள்ளவும் (AES-256-GCM)
- மேல்நிலை தலைப்பு மறுக்கப்பட்ட பட்டியல்: `src/shared/constants/upstreamHeaders.ts` — திருத்தும்போது சுத்தமாக்கவும், Zod வடிவமைப்புகள் மற்றும் யூனிட் சோதனைகளை ஒத்திசைக்கவும்
- **பொது மேல்நிலை அங்கீகாரங்கள்** (Gemini/Antigravity/Windsurf-பாணி OAuth client_id/secret + Firebase வலை விசைகள் பொதுவான CLIs இல் இருந்து எடுக்கப்பட்டவை): **கட்டாயமாக** `resolvePublicCred()` மூலம் இணைக்கப்பட வேண்டும் `open-sse/utils/publicCreds.ts` — **எப்போதும்** உரை இலக்கணமாக அல்ல. கட்டாய மாதிரி குறித்து `docs/security/PUBLIC_CREDS.md` ஐப் பார்க்கவும்.
- **பிழை பதில்கள்** (HTTP / SSE / executor / MCP கையாளி): **கட்டாயமாக** `buildErrorBody()` அல்லது `sanitizeErrorMessage()` மூலம் வழிமொழிய வேண்டும் `open-sse/utils/error.ts` — **எப்போதும்** கச்சித `err.stack` அல்லது `err.message` ஐ பதில் உடலில் வைக்க வேண்டாம். `docs/security/ERROR_SANITIZATION.md` ஐப் பார்க்கவும்.
- **மாறிலிகள் மூலம் உருவாக்கப்பட்ட ஷெல் கட்டளைகள்**: `exec()`/`spawn()` ஐ இயக்கும் போது, இயக்க நேர மதிப்புகளை தேவைப்படும் ஸ்கிரிப்டுடன், `env` விருப்பத்தின் மூலம் அனுப்பவும் (ஷெல்-எஸ்கேப் தானாகவே) — **எப்போதும்** நம்பமுடியாத/வெளியுறுப்புகளை ஸ்கிரிப்ட் உடலில் உரை-இணைக்க வேண்டாம். குறிப்புரை: `src/mitm/cert/install.ts::updateNssDatabases`.
- **பாதுகாப்பான-முதலில் நூலகங்கள்** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): புதிய பாதுகாப்பு-அனுபவங்களைச் சேர்க்கும்போது Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink ஐ தனிப்பயனாக்கப்பட்ட செயல்பாடுகளை விட முன்னுரிமை கொடுக்கவும்.

---

## பொதுவான திருத்த நிலைகள்

### புதிய வழங்குநரைச் சேர்க்க

1. `src/shared/constants/providers.ts` இல் பதிவு செய்யவும் (ஏற்றுமதி செய்யும் போது Zod-சரிபார்க்கப்பட்டது)
2. தனிப்பயன் தரவுகளை தேவைப்பட்டால் `open-sse/executors/` இல் செயல்பாட்டைச் சேர்க்கவும் ( `BaseExecutor` ஐ விரிவாக்கவும்)
3. OpenAI வடிவமைப்புக்கு அல்லாதால் `open-sse/translator/` இல் மொழிபெயர்ப்பாளர் சேர்க்கவும்
4. OAuth அடிப்படையிலானது என்றால் `src/lib/oauth/constants/oauth.ts` இல் OAuth அமைப்பைச் சேர்க்கவும் — மேல்நிலை CLI ஒரு பொது client_id/secret ஐ வழங்கினால், `resolvePublicCred()` மூலம் இணைக்கவும் ( `docs/security/PUBLIC_CREDS.md` ஐப் பார்க்கவும்), **எப்போதும்** உரை இலக்கணமாக அல்ல
5. `open-sse/config/providerRegistry.ts` இல் மாதிரிகளை பதிவு செய்யவும்
6. `tests/unit/` இல் சோதனைகளை எழுதவும் (புதிய இணைக்கப்பட்ட அடிப்படையைச் சேர்த்தால் publicCreds வடிவமைப்பைச் சேர்க்கவும்)

### புதிய API வழியைச் சேர்க்க

1. `src/app/api/v1/your-route/` இல் அடைவை உருவாக்கவும்
2. `GET`/`POST` கையாளர்களுடன் `route.ts` உருவாக்கவும்
3. மாதிரியைப் பின்பற்றவும்: CORS → Zod உடல் சரிபார்ப்பு → விருப்ப auth → கையாளல் ஒப்படைப்பு
4. கையாளல் `open-sse/handlers/` இல் செல்ல வேண்டும் (அங்கு இறக்குமதி செய்யவும், உள்ளடக்கமாக அல்ல)
5. பிழை பதில்கள் `buildErrorBody()` / `errorResponse()` ஐப் பயன்படுத்த வேண்டும் `open-sse/utils/error.ts` (தானாக சுத்தமாக்கப்பட்டது — எப்போதும் `err.stack` அல்லது `err.message` கச்சிதமாக உடலில் வைக்க வேண்டாம்). `docs/security/ERROR_SANITIZATION.md` ஐப் பார்க்கவும்.
6. சோதனைகளைச் சேர்க்கவும் — பிழை பதில்கள் குவியல் தடங்களை வெளியிடாததை உறுதி செய்யும் குறைந்தது ஒரு உறுதிப்படுத்தலுடன் (`!body.error.message.includes("at /")`)

### புதிய DB மாடுல் சேர்க்க

1. `src/lib/db/yourModule.ts` உருவாக்கவும் — `./core.ts` இல் இருந்து `getDbInstance` ஐ இறக்குமதி செய்யவும்
2. உங்கள் டொமைன் அட்டவணைக்கான CRUD செயல்பாடுகளை வெளியிடவும்
3. புதிய அட்டவணைகள் தேவைப்பட்டால் `src/lib/db/migrations/` இல் மைக்ரேஷன் சேர்க்கவும்
4. `src/lib/localDb.ts` இல் இருந்து மீண்டும் வெளியிடவும் (மீண்டும் வெளியீட்டு பட்டியலில் மட்டும் சேர்க்கவும்)
5. சோதனைகளை எழுதவும்

### புதிய MCP கருவியைச் சேர்க்க

1. Zod உள்ளீட்டு வடிவமைப்புடன் `open-sse/mcp-server/tools/` இல் கருவி வரையறையைச் சேர்க்கவும் + அசிங்க கையாளல்
2. கருவி தொகுப்பில் பதிவு செய்யவும் ( `createMcpServer()` மூலம் இணைக்கப்பட்டது)
3. உரிய அளவுகளில் ஒதுக்கவும்
4. சோதனைகளை எழுதவும் (கருவி அழைப்புகள் `mcp_audit` அட்டவணையில் பதிவு செய்யப்படும்)

### புதிய A2A திறனைச் சேர்க்க

1. `src/lib/a2a/skills/` இல் திறனை உருவாக்கவும் (5 ஏற்கனவே உள்ளன: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. திறன் பணியாளர் சூழ்நிலையைப் பெறுகிறது (செய்திகள், மெட்டாடேட்டா) → கட்டமைக்கப்பட்ட முடிவை திருப்புகிறது
3. `src/lib/a2a/taskExecution.ts` இல் `A2A_SKILL_HANDLERS` இல் பதிவு செய்யவும்
4. `src/app/.well-known/agent.json/route.ts` இல் வெளிப்படுத்தவும் (ஏஜென்ட் கார்ட்)
5. `tests/unit/` இல் சோதனைகளை எழுதவும்
6. `docs/frameworks/A2A-SERVER.md` திறன் அட்டவணையில் ஆவணமாக்கவும்

### புதிய கிளவுட் ஏஜென்டைச் சேர்க்க

1. `src/lib/cloudAgent/agents/` இல் `CloudAgentBase` ஐ விரிவாக்கும் ஏஜென்ட் வகுப்பை உருவாக்கவும் (3 ஏற்கனவே உள்ளன: codex-cloud, devin, jules)
2. `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` ஐ செயல்படுத்தவும்
3. `src/lib/cloudAgent/registry.ts` இல் பதிவு செய்யவும்
4. தேவைப்பட்டால் OAuth/அங்கீகாரங்களை கையாளவும் (`src/lib/oauth/providers/`)
5. சோதனைகள் + `docs/frameworks/CLOUD_AGENT.md` இல் ஆவணமாக்கவும்

### புதிய காப்புறுப்பு / மதிப்பீடு / திறன் / வலைப்பின்னல் நிகழ்வு சேர்க்க

- காப்புறுப்பு: `src/lib/guardrails/` → ஆவணங்கள்: `docs/security/GUARDRAILS.md`
- மதிப்பீட்டு தொகுப்பு: `src/lib/evals/` → ஆவணங்கள்: `docs/frameworks/EVALS.md`
- திறன் (சேதம்): `src/lib/skills/` → ஆவணங்கள்: `docs/frameworks/SKILLS.md`
- வலைப்பின்னல் நிகழ்வு: `src/lib/webhookDispatcher.ts` → ஆவணங்கள்: `docs/frameworks/WEBHOOKS.md`

## குறிப்பு ஆவணம்

எந்தவொரு முக்கியமான மாற்றத்திற்காக, முதலில் பொருத்தமான ஆழமான ஆய்வைப் படிக்கவும்:

| பகுதி                                        | ஆவணம்                                                             |
| -------------------------------------------- | ----------------------------------------------------------------- |
| ரெப்போ நவீனமயமாக்கல்                         | `docs/architecture/REPOSITORY_MAP.md`                             |
| கட்டமைப்பு                                   | `docs/architecture/ARCHITECTURE.md`                               |
| பொறியியல் குறிப்பு                           | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| ஆட்டோ-கொம்போ (9-கூறு மதிப்பீடு, 14 உத்திகள்) | `docs/routing/AUTO-COMBO.md`                                      |
| நிலைத்தன்மை (3 முறைமைகள்)                    | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| காரணம் மீண்டும் விளக்கம்                     | `docs/routing/REASONING_REPLAY.md`                                |
| திறன்கள் கட்டமைப்பு                          | `docs/frameworks/SKILLS.md`                                       |
| நினைவகம் அமைப்பு (FTS5 + Qdrant)             | `docs/frameworks/MEMORY.md`                                       |
| மேக முகவர்கள்                                | `docs/frameworks/CLOUD_AGENT.md`                                  |
| பாதுகாப்பு (PII / ஊட்டம் / பார்வை)           | `docs/security/GUARDRAILS.md`                                     |
| பொது மேல்நிலை அங்கீகாரங்கள் (Gemini/etc.)    | `docs/security/PUBLIC_CREDS.md`                                   |
| பிழை செய்தி சுத்திகரிப்பு                    | `docs/security/ERROR_SANITIZATION.md`                             |
| மதிப்பீடுகள்                                 | `docs/frameworks/EVALS.md`                                        |
| ஒத்திசைவு / ஆய்வு                            | `docs/security/COMPLIANCE.md`                                     |
| வலைக்குறிகள்                                 | `docs/frameworks/WEBHOOKS.md`                                     |
| அங்கீகார குழாய்                              | `docs/architecture/AUTHZ_GUIDE.md`                                |
| மறைமுகம் (TLS / கையொப்பம்)                   | `docs/security/STEALTH_GUIDE.md`                                  |
| முகவர் நெறிமுறைகள் (A2A / ACP / Cloud)       | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| MCP சேவையகம்                                 | `docs/frameworks/MCP-SERVER.md`                                   |
| A2A சேவையகம்                                 | `docs/frameworks/A2A-SERVER.md`                                   |
| API குறிப்பு + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| வழங்குநர் பட்டியல் (தானாக உருவாக்கப்பட்டது)  | `docs/reference/PROVIDER_REFERENCE.md`                            |
| வெளியீட்டு ஓட்டம்                            | `docs/ops/RELEASE_CHECKLIST.md`                                   |

## சோதனை

| என்ன                       | கட்டளை                                                                           |
| -------------------------- | -------------------------------------------------------------------------------- |
| யூனிட் சோதனைகள்            | `npm run test:unit`                                                              |
| ஒற்றை கோப்பு               | `node --import tsx/esm --test tests/unit/file.test.ts`                           |
| Vitest (MCP, autoCombo)    | `npm run test:vitest`                                                            |
| E2E (Playwright)           | `npm run test:e2e`                                                               |
| புரோட்டோகால் E2E (MCP+A2A) | `npm run test:protocols:e2e`                                                     |
| சூழல்                      | `npm run test:ecosystem`                                                         |
| கவரேஜ் கேட்                | `npm run test:coverage` (75/75/75/70 — அறிக்கைகள்/வரிசைகள்/செயல்பாடுகள்/கிளைகள்) |
| கவரேஜ் அறிக்கை             | `npm run coverage:report`                                                        |

**PR விதி**: நீங்கள் `src/`, `open-sse/`, `electron/`, அல்லது `bin/` இல் உற்பத்தி குறியீட்டை மாற்றினால், அதே PR இல் சோதனைகளை சேர்க்க அல்லது புதுப்பிக்க வேண்டும்.

**சோதனை அடுக்கு முன்னுரிமை**: யூனிட் முதலில் → ஒருங்கிணைப்பு (பல-மாடுல் அல்லது DB நிலை) → e2e (UI/செயல்முறை மட்டும்). பிழை மறுபடியும் உருவாக்கங்களை சரிசெய்யும் சோதனைகளாக குறியீடு செய்யவும்.

**Copilot கவரேஜ் கொள்கை**: ஒரு PR உற்பத்தி குறியீட்டை மாற்றும் போது மற்றும் கவரேஜ் 75% (அறிக்கைகள்/வரிசைகள்/செயல்பாடுகள்) அல்லது 70% (கிளைகள்) க்குக் கீழே இருந்தால், வெறும் அறிக்கையிடாதீர்கள் — சோதனைகளை சேர்க்க அல்லது புதுப்பிக்கவும், கவரேஜ் கேட்டை மீண்டும் இயக்கவும், பின்னர் உறுதிப்படுத்தவும் கேளுங்கள். இயக்கப்பட்ட கட்டளைகள், மாற்றப்பட்ட சோதனை கோப்புகள், மற்றும் இறுதி கவரேஜ் முடிவுகளை PR அறிக்கையில் சேர்க்கவும்.

---

## Git வேலைப்பாடு

```bash
# எப்போதும் நேரடியாக முக்கியத்தில் கமிட் செய்யாதீர்கள்
git checkout -b feat/your-feature
git commit -m "feat: describe your change"
git push -u origin feat/your-feature
```

**கிளை முன்னுரிமைகள்**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**கமிட் வடிவம்** (சாதாரண கமிட்): `feat(db): add circuit breaker` — வரம்புகள்: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Husky ஹூக்குகள்**:

- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
- **pre-push**: `npm run test:unit`

---

## சூழல்

- **இயக்க நேரம்**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
- **TypeScript**: 5.9+, இலக்கு ES2022, மாடுல் esnext, தீர்வு bundler
- **பாதை அலியாஸ்**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **இயல்புநிலை போர்ட்**: 20128 (API + dashboard ஒரே போர்டில்)
- **தரவியல் அடைவு**: `DATA_DIR` env var, இயல்பாக `~/.omniroute/`
- **முக்கிய env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- அமைப்பு: `cp .env.example .env` பின்னர் `JWT_SECRET` (`openssl rand -base64 48`) மற்றும் `API_KEY_SECRET` (`openssl rand -hex 32`) உருவாக்கவும்

---

## கடுமையான விதிகள்

1. ரகசியங்கள் அல்லது சான்றிதழ்களை எப்போதும் கமிட் செய்யாதீர்கள்
2. `localDb.ts` இல் லாஜிக்கை எப்போதும் சேர்க்காதீர்கள்
3. `eval()` / `new Function()` / குறிக்கோள் eval ஐ எப்போதும் பயன்படுத்தாதீர்கள்
4. எப்போதும் நேரடியாக `main` இல் கமிட் செய்யாதீர்கள்
5. வழிகளில் கச்சிதமான SQL எழுதாதீர்கள் — `src/lib/db/` மாடுல்களைப் பயன்படுத்தவும்
6. SSE ஓடுகளில் பிழைகளை மௌனமாக உறிஞ்சாதீர்கள்
7. எப்போதும் Zod ஸ்கீமாஸ் மூலம் உள்ளீடுகளை சரிபார்க்கவும்
8. உற்பத்தி குறியீட்டை மாற்றும் போது எப்போதும் சோதனைகளை சேர்க்கவும்
9. கவரேஜ் ≥75% (அறிக்கைகள், வரிசைகள், செயல்பாடுகள்) / ≥70% (கிளைகள்) ஆக இருக்க வேண்டும். தற்போதைய அளவீடு: ~82%.
10. தெளிவான இயக்குனர் அனுமதி இல்லாமல் Husky ஹூக்குகளை ( `--no-verify`, `--no-gpg-sign`) எப்போதும் தவிர்க்காதீர்கள்.
11. பொதுவான மேல்நிலை OAuth client_id/secret அல்லது Firebase Web விசைகளை சரம் எழுத்துக்களாக எப்போதும் உள்ளடக்காதீர்கள் — எப்போதும் `resolvePublicCred()` மூலம் செல்லவும் (`open-sse/utils/publicCreds.ts`). `docs/security/PUBLIC_CREDS.md` ஐப் பார்க்கவும்.
12. HTTP / SSE / செயல்பாட்டாளர் பதில்களில் கச்சிதமான `err.stack` / `err.message` ஐ எப்போதும் திருப்பாதீர்கள் — எப்போதும் `buildErrorBody()` அல்லது `sanitizeErrorMessage()` மூலம் வழி நடத்தவும் (`open-sse/utils/error.ts`). `docs/security/ERROR_SANITIZATION.md` ஐப் பார்க்கவும்.
13. `exec()`/`spawn()` க்கு வழங்கப்படும் ஷெல் ஸ்கிரிப்ட்களில் வெளிப்புற பாதைகள் அல்லது இயக்க நேர மதிப்புகளை எப்போதும் சரம் இடைவெளி செய்யாதீர்கள் — `env` விருப்பத்தின் மூலம் வழங்கவும். குறிப்புரை: `src/mitm/cert/install.ts::updateNssDatabases`.
14. CodeQL / Secret-Scanning எச்சரிக்கையை (a) மேலே உள்ள மாதிரி ஆவணங்களை முதலில் சரிபார்க்காமல் மற்றும் (b) நீக்கம் கருத்தில் தொழில்நுட்ப காரணத்தை பதிவு செய்யாமல் எப்போதும் மறுக்காதீர்கள். முன்னணி: `js/stack-trace-exposure` என்பது ஏற்கனவே `sanitizeErrorMessage()` மூலம் வழி நடத்தப்படும் அழைப்பிடங்களில் எழுப்பப்பட்டது என்பது ஒரு அறியப்பட்ட CodeQL வரம்பு (சாதாரண சுத்திகரிப்புகள் அடையாளம் காணப்படவில்லை) — `docs/security/ERROR_SANITIZATION.md` ஐ மேற்கோள் காட்டி `false positive` ஆக மறுக்கவும்.
15. குழந்தை செயல்முறைகளை உருவாக்கும் வழிகளை ( `/api/mcp/`, `/api/cli-tools/runtime/`) `src/server/authz/routeGuard.ts` இல் `isLocalOnlyPath()` வகைப்படுத்தலின்றி எப்போதும் வெளிப்படுத்தாதீர்கள். எந்த அங்கீகார சோதனைக்கும் முன் கட்டாயமாக லூப்பேக் அமலாக்கம் நடைபெறும் — குழாயில் ஊடுருவிய JWT செயல்முறை உருவாக்கத்தை தூண்ட முடியாது. `docs/security/ROUTE_GUARD_TIERS.md` ஐப் பார்க்கவும்.
16. AI உதவியாளர், LLM அல்லது தானியங்கி கணக்கிற்கு பெருமை வழங்கும் `Co-Authored-By` டிரெய்லர்களை commit செய்திகளில் ஒருபோதும் சேர்க்க வேண்டாம் (உதா. "Claude", "GPT", "Copilot", "Bot" கொண்ட பெயர்கள்; `anthropic.com` / `openai.com` / bot-உரிமை உள்ள `noreply.github.com` முகவரிகளில் மின்னஞ்சல்கள்). இத்தகைய டிரெய்லர்கள் GitHub இல் bot கணக்கிற்கு commit attribution-ஐ வழிநடத்தி, PR வரலாற்றில் உண்மையான ஆசிரியரை (`diegosouzapw`) மறைக்கின்றன. மனித ஒத்துழைப்பாளர்கள் — upstream PR ஆசிரியர்கள் மற்றும் OmniRoute-க்கு port செய்யப்படும் issue அறிக்கையாளர்கள் உட்பட — நிலையான `Co-authored-by: Name <email>` டிரெய்லர்களுடன் பெருமை பெறலாம் மற்றும் வேண்டும்; upstream-port பணி ஓட்டங்கள் (`/port-upstream-features`, `/port-upstream-issues`) இதை சார்ந்துள்ளன.
