OmniRoute/docs/i18n/el/docs/architecture/CODEBASE_DOCUMENTATION.md

CODEBASE_DOCUMENTATION (Ελληνικά)

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

---

---

title: "OmniRoute Codebase Documentation" version: 3.8.40 lastUpdated: 2026-06-28

Τεκμηρίωση Κώδικα OmniRoute

Έκδοση: v3.8.51 Τελευταία ενημέρωση: 2026-06-28 Κοινό: Μηχανικοί που συνεισφέρουν στο OmniRoute ή δημιουργούν ενσωματώσεις πάνω σε αυτό.

Για διαγράμματα αρχιτεκτονικής υψηλού επιπέδου και την αιτιολόγηση κάθε υποσυστήματος, διαβάστε το ARCHITECTURE.md. Για εκτενή ανάλυση μεμονωμένων υποσυστημάτων (Auto Combo, MCP server, A2A server, Skills, Memory, Cloud Agents, Resilience, Compression, κ.λπ.) δείτε τα αντίστοιχα αρχεία σε αυτόν τον κατάλογο docs/.

Αυτό το αρχείο περιγράφει ό,τι υπάρχει σήμερα στο αποθετήριο, ώστε ένας νέος μηχανικός να μπορεί να πλοηγηθεί στο δέντρο αρχείων, να κατανοήσει τη στρωματοποίηση του χρόνου εκτέλεσης και να γνωρίζει πού να προσθέσει κώδικα χωρίς να εφευρίσκει νέα modules.

---

1. Τεχνολογική Στοίβα

Θέμα	Επιλογή
Web framework	Next.js 16 (App Router, standalone output, χωρίς global middleware)
Γλώσσα	TypeScript 6.0+ — target ES2022, module: esnext, moduleResolution: bundler, strict: false
Runtime	Node.js >=22.22.2 <23 ή >=24.0.0 <27 (επιβάλλεται μέσω engines + SUPPORTED_NODE_RANGE)
Βάση δεδομένων	SQLite μέσω better-sqlite3 (singleton, WAL journaling)
Desktop	Electron 41 + electron-builder 26.10 (ξεχωριστός χώρος εργασίας στο electron/)
Δοκιμές	Node native test runner (unit/integration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Next.js standalone μέσω scripts/build/build-next-isolated.mjs
Lint/format	ESLint flat config + Prettier (lint-staged μέσω Husky pre-commit)
Σύστημα modules	ESM παντού ("type": "module")
Workspaces	npm workspace — το open-sse είναι το μοναδικό υπο-workspace

Ψευδώνυμα διαδρομών (tsconfig.json):

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

Προεπιλεγμένη θύρα HTTP: 20128 (το API και το dashboard μοιράζονται την ίδια διεργασία). Ο κατάλογος δεδομένων ορίζεται από τη μεταβλητή περιβάλλοντος DATA_DIR, με προεπιλογή ~/.omniroute/.

---

2. Δομή Αποθετηρίου

OmniRoute/
├── src/                  # Εφαρμογή Next.js (App Router, libs, domain, server, shared)
├── open-sse/             # Χώρος εργασίας streaming engine (@omniroute/open-sse)
├── electron/             # Desktop wrapper (Electron 41 main + preload)
├── bin/                  # Σημεία εισόδου CLI (omniroute, reset-password)
├── tests/                # Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              # Σενάρια build, sync, check, migration και runtime helper
├── docs/                 # Δημόσια τεκμηρίωση (αυτός ο κατάλογος)
├── public/               # Στατικά assets, PWA manifest, service worker
├── config/               # Δείγματα ρυθμίσεων runtime
├── images/               # Assets μάρκετινγκ/στιγμιότυπα οθόνης
├── _ideia/, _references/, _mono_repo/, _tasks/   # Εσωτερικό scratch / σχεδιασμός (δεν αποστέλλεται)
├── CLAUDE.md             # Κανόνες αποθετηρίου για το Claude Code
├── AGENTS.md             # Εκτενής αναφορά αρχιτεκτονικής για agents
├── package.json          # v3.8.51, ρίζα workspace
└── tsconfig.json         # Ψευδώνυμα διαδρομών + βασικές επιλογές μεταγλωττιστή

---

3. src/ — Εφαρμογή Next.js

src/
├── app/                  Σελίδες App Router + διαδρομές API
├── lib/                  Βασικές βιβλιοθήκες (DB, auth, OAuth, skills, memory, …)
├── domain/               Καθαρό επίπεδο domain (policy, fallback, cost, lockout, …)
├── server/               Μόνο-διακομιστή modules (authz, cors, auth)
├── shared/               Τύποι, σταθερές, επικύρωση, contracts, utils (ασφαλές διαμοιρασμού)
├── mitm/                 Βοηθητικά man-in-the-middle proxy για ενσωμάτωση CLI
├── models/               Μεταδεδομένα / aliasing τοπικών μοντέλων
├── sse/                  Παλαιοί SSE handlers που παραμένουν στο src/ (όχι open-sse/)
├── store/                Αποθήκες κατάστασης πλευράς πελάτη
├── middleware/           Βοηθητικά middleware επιπέδου διαδρομής (όχι global middleware του Next.js)
├── scripts/              Εσωτερικά scripts που μπορούν να εισαχθούν από κώδικα εφαρμογής
├── types/                Περιβαλλοντικοί και κοινόχρηστοι τύποι TS
├── i18n/                 Δέσμες locale
├── instrumentation.ts    Άγκιστρο instrumentation του Next.js
├── instrumentation-node.ts
└── proxy.ts              Βοηθητικό bootstrap proxy ανώτατου επιπέδου

3.1 src/app/ — App Router

Το App Router εκθέτει τόσο το UI του πίνακα ελέγχου όσο και το δημόσιο/διαχειριστικό HTTP API. Δεν υπάρχει global middleware — η παρεμβολή γίνεται ανά διαδρομή.

Τμήματα ανώτατου επιπέδου στο 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/	Σελίδα marketing/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	Όρια σφαλμάτων/φόρτωσης του framework
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/         Δημόσιο API συμβατό με OpenAI
├── v1beta/     Συμβατότητα τύπου Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Διαχείριση ενσωματωμένων υπηρεσιών

Διαδρομές για εγκατάσταση, εκκίνηση, διακοπή και παρακολούθηση 9Router και CLIProxyAPI. Όλες οι διαδρομές ταξινομούνται ως LOCAL_ONLY (μόνο loopback, αυστηρός κανόνας #17) επειδή μπορούν να καλέσουν npm install και να δημιουργήσουν θυγατρικές διεργασίες.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             βοηθητικό getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install μέσω execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install νεότερης έκδοσης
│   ├── rotate-key/route.ts POST — δημιουργία νέου API key + επανεκκίνηση
│   ├── 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). Αντίστροφο proxy για ενσωματωμένο UI 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Εις βάθος ανάλυση: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — Δημόσιο API συμβατό με OpenAI

v1/
├── accounts/[id]/                       αναζήτηση λογαριασμού
├── agents/tasks/[id]/, agents/tasks/    τελικά σημεία task τύπου A2A
├── api/                                 εσωτερικά βοηθητικά API εκτεθειμένα στο v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API Batches του OpenAI
├── chat/completions/                    Chat Completions (το κύριο τελικό σημείο)
├── completions/                         Παλαιές text completions
├── embeddings/                          Embeddings
├── files/[id]/, files/                  Files API
├── _helpers/                            Κοινόχρηστα βοηθητικά διαδρομής (χωρίς δημόσιο URL)
├── images/{edits, generations}/         Δημιουργία + επεξεργασία εικόνων
├── issues/                              Τελικά σημεία βοηθητικού triage
├── management/{proxies}/                Διαδρομές εύρους διαχείρισης εντός v1
├── messages/{count_tokens}/             Συμβατότητα μηνυμάτων τύπου Anthropic
├── models/                              Καταχώρηση μοντέλων (`route.ts`, `catalog.ts`)
├── moderations/                         Moderation
├── music/                               Δημιουργία μουσικής
├── providers/[provider]/                Λειτουργίες ανά πάροχο
├── quotas/{check}                       Έλεγχοι ποσοστώσεων
├── registered-keys/                     Διαχείριση εγγεγραμμένων κλειδιών
├── rerank/                              Επαναταξινόμηση
├── responses/[...path]/                 API Responses του OpenAI (catch-all)
├── search/                              Αναζήτηση στο διαδίκτυο
├── videos/                              Δημιουργία βίντεο
├── ws/                                  Γέφυρα WebSocket
└── route.ts                             Χειριστής ευρετηρίου

Κάθε αρχείο διαδρομής ακολουθεί το ίδιο μοτίβο:

Route → CORS preflight → Επικύρωση Zod body → προαιρετικό auth
      → Εφαρμογή πολιτικής API key → ανάθεση στον χειριστή (open-sse)

Το v1beta/ είναι η επιφάνεια συμβατότητας τύπου Gemini (ένας λεπτός wrapper που μεταφράζει στον ίδιο αγωγό open-sse/handlers/).

3.2 src/lib/ — Βασικές βιβλιοθήκες

Πάντα να εισάγετε δεδομένα, sync, OAuth, skill, memory κ.λπ. μέσω αυτών των modules. Ο πίνακας ομαδοποιεί τους πραγματικούς καταλόγους και αξιοσημείωτα αρχεία ανώτατου επιπέδου.

Module	Σκοπός
a2a/	Διακομιστής πρωτοκόλλου A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 skills: ανάλυση κόστους, αναφορά υγείας, ανακάλυψη παρόχων, διαχείριση ποσοστώσεων, έξυπνη δρομολόγηση, list-capabilities)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Εσωτερικά βοηθητικά API: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (επαναφορά κωδικού / hashing)
batches/	Υπηρεσία API Batches του OpenAI (service.ts)
catalog/	Συγχρονισμός καταλόγου OpenRouter (openrouterCatalog.ts)
cloudAgent/	Μητρώο cloud agent: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Βοηθητικά επίλυσης combo
compliance/	Έλεγχος + έλεγχος παρόχου: index.ts, providerAudit.ts
config/	Συγκόλληση ρυθμίσεων χρόνου εκτέλεσης
db/	Modules domain SQLite (βλ. §3.2.1)
display/	Βοηθητικά UI/εμφάνισης που χρησιμοποιούνται από αποκρίσεις API
embeddings/	Μητρώο υπηρεσίας 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/	Modules 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/	Φορτωτής plugin (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 — ρυθμίσεις για circuit breaker, cooldown, lockout
runtime/	Ανίχνευση χαρακτηριστικών χρόνου εκτέλεσης
search/	executeWebSearch.ts
services/	Framework ενσωματωμένων υπηρεσιών: ServiceSupervisor.ts (γενικός επιτηρητής θυγατρικής διεργασίας με κλείδωμα λειτουργίας, ring buffer, έλεγχο υγείας), bootstrap.ts (εγγραφή επιπέδου διεργασίας και αυτόματη εκκίνηση), registry.ts (χαρτογράφηση εργαλείου → επιτηρητή), apiKey.ts (αποθήκη κλειδιών AES-256-GCM), modelSync.ts (περιοδικός συγχρονισμός μοντέλων), ringBuffer.ts (κυκλικό buffer καταγραφής 5 MB), healthCheck.ts (ανιχνευτής υγείας HTTP), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Βλ. docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Κατάλογος + γεννήτρια Agent Skills: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → εγγράφει skills/{id}/SKILL.md), openapiParser.ts (εξάγει τελικά σημεία REST από προδιαγραφή OpenAPI), cliRegistryParser.ts (εξάγει υποεντολές CLI από bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Χρησιμοποιείται από διαδρομές REST (/api/agent-skills/*), εργαλεία MCP (omniroute_agent_skills_*) και A2A skill list-capabilities. Βλ. AGENT-SKILLS.md.
skills/	Framework 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 (buffer εγγραφής με καθυστέρηση)
sync/	bundle.ts, tokens.ts (Cloud Sync)
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/	Αυτόματη ενημέρωση + manifest έκδοσης
ws/	Γέφυρα WebSocket
zed-oauth/	Ροή OAuth επεξεργαστή Zed

Αρχεία ανώτατου επιπέδου στο src/lib/:

• Το παλαιό barrel localDb.ts αφαιρέθηκε — οι καταναλωτές εισάγουν απευθείας συγκεκριμένα modules src/lib/db/*.
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

Singleton βάση δεδομένων SQLite (getDbInstance() στο core.ts, καταγραφή WAL). Μην γράφετε ποτέ raw SQL σε διαδρομές ή χειριστές — χρησιμοποιήστε αυτά τα modules.

Πηγή: diagrams/db-schema-overview.mmd

Modules domain (καθένα ανήκει σε έναν ή περισσότερους πίνακες): 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 κατά την εκκίνηση.

Πίνακες που δημιουργήθηκαν στις migrations (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/ — Επίπεδο domain

Καθαρή επιχειρηματική λογική, χωρίς I/O. Εισάγεται από διαδρομές και χειριστές.

Αρχείο	Σκοπός
policyEngine.ts	Επιλύτης πολιτικής ανώτατου επιπέδου
fallbackPolicy.ts	Δέντρο αποφάσεων fallback
costRules.ts	Κανόνες υπολογισμού κόστους
lockoutPolicy.ts	Αποφάσεις αποκλεισμού μοντέλου
tagRouter.ts	Δρομολόγηση βασισμένη σε tags
comboResolver.ts	Επίλυση combo από αίτημα → λίστα στόχου
connectionModelRules.ts	Φίλτρα μοντέλου ανά σύνδεση
modelAvailability.ts	Έλεγχος διαθεσιμότητας μοντέλου
degradation.ts	Μεταβάσεις υποβαθμισμένης λειτουργίας
providerExpiration.ts	Ανίχνευση ληγμένου λογαριασμού/κλειδιού
quotaCache.ts	Αποθηκευμένες αποφάσεις ποσοστώσεων
responses.ts, omnirouteResponseMeta.ts	Βοηθητικά μορφής απόκρισης
configAudit.ts	Έλεγχος αλλαγών ρυθμίσεων
assessment/	Αξιολόγηση μοντέλου (ανά RFC, μερικώς υλοποιημένο)
types.ts	Κοινόχρηστοι τύποι domain

3.4 src/server/ — Μόνο-διακομιστή

Δεν μπορεί να εισαχθεί από components πελάτη.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Ταξινομεί διαδρομές ως δημόσιες ή διαχειριστικές
│   ├── assertAuth.ts      Βοηθητικό assertion
│   ├── context.ts         Περιβάλλον authz ανά αίτημα
│   ├── headers.ts
│   ├── pipeline.ts        Αγωγός authz
│   ├── policies/          Συγκεκριμένες πολιτικές
│   └── types.ts
└── cors/origins.ts        Λίστα επιτρεπόμενων origins 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/ — δημόσια contracts API που αποστέλλονται στο npm.
• 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, καθώς και hooks/components πίνακα ελέγχου στους services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Χώρος εργασίας μηχανής ροής (streaming)

Ξεχωριστός χώρος εργασίας npm που δημοσιεύεται ως @omniroute/open-sse. Διαχειρίζεται την επεξεργασία αιτημάτων, τους εκτελεστές, τους μεταφραστές, τις υπηρεσίες, τον μετασχηματιστή και τον διακομιστή MCP.

open-sse/
├── index.ts                Δημόσιες εξαγωγές
├── package.json            Δήλωση χώρου εργασίας
├── tsconfig.json
├── types.d.ts
├── config/                 Μητρώα παρόχων, προφίλ κεφαλίδων, ταυτότητα, …
├── handlers/               Χειριστές αιτημάτων (chat, embeddings, ήχος, εικόνα, …)
├── executors/              108 εκτελεστές HTTP ανά πάροχο
├── translator/             Μετατροπή μορφής (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Μετασχηματιστής ροής Responses API ↔ Chat Completions
├── services/               80+ ενότητες υπηρεσιών (combos, fallback, quotas, ταυτότητα, …)
├── utils/                  Βοηθητικά streaming, TLS client, AWS SigV4, proxy fetch, …
└── mcp-server/             Διακομιστής MCP (3 μεταφορές, 33 εμβέλειες, 110 εργαλεία)

4.1 open-sse/handlers/

Χειριστής	Σκοπός
chatCore.ts	Κύρια αγωγός chat (cache, rate limit, δρομολόγηση combo, αποστολή σε εκτελεστή)
responsesHandler.ts	Σημείο εισόδου OpenAI Responses API
embeddings.ts	Ενσωματώσεις (Embeddings)
imageGeneration.ts	Δημιουργία εικόνας
audioSpeech.ts	Κείμενο σε ομιλία (Text-to-speech)
audioTranscription.ts	Ομιλία σε κείμενο (Speech-to-text)
videoGeneration.ts	Δημιουργία βίντεο
musicGeneration.ts	Δημιουργία μουσικής
rerank.ts	Επαναταξινόμηση (Reranking)
moderations.ts	Συντονισμός περιεχομένου
search.ts	Αναζήτηση στο διαδίκτυο
sseParser.ts	Αναλυτής συμβάντων SSE
usageExtractor.ts	Εξαγωγή μετρήσεων token από upstream ροές
responseSanitizer.ts	Αφαίρεση θορύβου ειδικού παρόχου
responseTranslator.ts	Σύνδεσμος μεταξύ απόκρισης παρόχου και επιπέδου μεταφραστή

4.2 open-sse/executors/

108 εκτελεστές παρόχων, καθένας εκτείνει το BaseExecutor (base.ts):

antigravity, azure-openai, blackbox-web, cliproxyapi, chatgpt-web-codex, cloudflare-ai, codex, commandCode, cursor, default, devin-cli, muse-spark-web, nlpcloud, opencode, perplexity-web, petals, pollinations, qoder, vertex, devin-desktop, καθώς και claudeIdentity.ts (κοινόχρηστος βοηθός ταυτότητας) και index.ts (μητρώο).

Σημείωση: οι πάροχοι που δεν αναφέρονται εδώ εξυπηρετούνται από το default.ts χρησιμοποιώντας τον γενικό εκτελεστή συμβατό με OpenAI. Ο πλήρης κατάλογος παρόχων (355 πάροχοι) βρίσκεται στο src/shared/constants/providers.ts.

4.3 open-sse/translator/

Μετάφραση κόμβου-και-ακτίνων (hub-and-spoke), με το 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 — Μετατροπέας Responses API ↔ Chat Completions βασισμένος σε TransformStream (χρησιμοποιείται από τη διαδρομή catch-all responses/).

4.5 open-sse/services/

Κύρια στοιχεία (πλήρης λίστα στο open-sse/services/):

Τομέας	Αρχεία
Δρομολόγηση combo	combo.ts (19 στρατηγικές), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Μηχανή Auto Combo	autoCombo/ — engine.ts, scoring.ts, taskFitness.ts, virtualFactory.ts, modePacks.ts, autoPrefix.ts, persistence.ts, providerDiversity.ts, providerRegistryAccessor.ts, routerStrategy.ts, selfHealing.ts, index.ts
Ανθεκτικότητα	accountFallback.ts (cooldown + lockout), errorClassifier.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, 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/ — πλήρης καλωδίωση μηχανής συμπίεσης
Token και σύνοδος	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Επίπεδο / manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / δίκτυο	ipFilter.ts, webSearchFallback.ts
Δέσμες εργασιών	batchProcessor.ts
Χρήση	usage.ts

4.6 open-sse/mcp-server/

• 110 μοναδικά εργαλεία καλωδιωμένα στο server.ts (45 κανονικά στο schemas/tools.ts + ενότητες μνήμης, δεξιοτήτων, GitHub-skills, pool, gamification, plugin, Notion, Obsidian, local-corpus και συμπίεσης — σύνολο που μετράται από το 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 για τον πλήρη κατάλογο εργαλείων.

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), και προσαρμογείς cloud (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/

Πρωτόγονα streaming και βοηθητικά παρόχων: 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               # Γέφυρα preload (contextIsolation ενεργοποιημένο)
├── types.d.ts
├── package.json             # Ρύθμιση electron-builder, έκδοση 3.8.51
├── README.md
├── assets/                  # Πόροι κατασκευής (εικονίδια, entitlements, …)
├── node_modules/            # Αποκλειστικά node_modules (better-sqlite3, electron-updater)
└── dist-electron/           # Έξοδος κατασκευής (δεν δεσμεύεται)

Πέντε npm scripts στη ρίζα του workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Η αυτόματη ενημέρωση γίνεται μέσω electron-updater που δείχνει στη ροή εκδόσεων GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           # Κύρια είσοδος CLI (Node ESM)
├── reset-password.mjs      # Επαναφορά κωδικού διαχείρισης από CLI
├── mcp-server.mjs          # Εκκινητής διακομιστή MCP (stdio)
├── nodeRuntimeSupport.mjs  # Έλεγχος έκδοσης Node
└── cli/
    ├── program.mjs         # Κατασκευαστής προγράμματος Commander
    ├── runtime.mjs         # Βοηθός withRuntime (server-first/db-fallback)
    ├── 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/	Δοκιμές μονάδας μέσω του εγγενούς test runner του Node (1821 αρχεία, συν υποκαταλόγους api/, auth/, authz/)
tests/integration/	Δοκιμές διαμόρφωσης μεταξύ ενοτήτων + κατάστασης βάσης δεδομένων
tests/e2e/	Δοκιμές UI με Playwright
tests/e2e/protocol-clients.test.ts	Δοκιμές e2e πρωτοκόλλου MCP/A2A
tests/translator/	Δοκιμές ειδικά για τον μεταφραστή
tests/security/	Παλινδρομήσεις ασφαλείας
tests/load/	Δοκιμές φορτίου / αντοχής
tests/golden-set/	Έξοδοι αναφοράς για παλινδρομήσεις μεταφραστή
tests/helpers/, tests/fixtures/, tests/manual/	Υποστήριξη

Συνήθεις εντολές:

Εντολή	Τι εκτελεί
npm run test:unit	Όλα τα tests/unit/*.test.ts μέσω Node test runner (ταυτόχρονα 10)
npm run test:vitest	Σουίτα Vitest (MCP, autoCombo, cache)
npm run test:e2e	Σουίτα UI Playwright
npm run test:protocols:e2e	Δοκιμές e2e πρωτοκόλλου MCP + A2A
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. Αγωγός Αιτημάτων (Σύνοψη)

Πηγή: diagrams/request-pipeline.mmd

Αίτημα πελάτη
  → /v1/chat/completions (route.ts)
     Έλεγχος CORS preflight
     Επικύρωση Zod (chatCompletionsSchema στο shared/validation/schemas.ts)
     Αυθεντικοποίηση (extractApiKey + isValidApiKey Ή requireManagementAuth)
     Μηχανισμός πολιτικής (src/server/authz/pipeline.ts)
     Φραγμοί ασφαλείας (μασκάρισμα PII, έγχυση prompt, γέφυρα vision)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Έλεγχος cache (σημασιολογικό + cache ανάγνωσης)
     Περιορισμός ρυθμού (rateLimitManager, accountSemaphore)
     Δρομολόγηση combo (εάν το μοντέλο επιλυθεί ως combo)
       comboResolver → βρόχος ανά στόχο → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       ανάκτηση upstream → επανάληψη/backoff μέσω accountFallback
     translateResponse() (open-sse/translator/response/*)
     Ροή SSE Ή απόκριση JSON
     Εάν Responses API: TransformStream μέσω open-sse/transformer/responsesTransformer.ts
  → Έλεγχος συμμόρφωσης (src/lib/compliance/)
  → Απόκριση στον πελάτη

Κατάσταση χρόνου εκτέλεσης ανθεκτικότητας (τρεις μηχανισμοί)

Μηχανισμός	Εμβέλεια	Πού
Αποσβεστήρας κυκλώματος παρόχου	Ολόκληρος ο πάροχος	src/shared/utils/circuitBreaker.ts, διατηρείται στο domain_circuit_breakers
Ψύξη σύνδεσης	Ένας λογαριασμός/κλειδί	markAccountUnavailable() στο src/sse/services/auth.ts· χρησιμοποιείται από το accountFallback.checkFallbackError()
Κλείδωμα μοντέλου	Πάροχος + σύνδεση + μοντέλο	open-sse/services/accountFallback.ts, διατηρείται στο domain_lockout_state

Δείτε RESILIENCE_GUIDE.md και την αφιερωμένη ενότητα στο CLAUDE.md.

---

10. Πώς να Συνεισφέρετε

Προσθήκη νέου παρόχου

1. Καταχωρίστε στο src/shared/constants/providers.ts (επαληθεύεται με Zod κατά τη φόρτωση).
2. Προσθέστε έναν executor στο open-sse/executors/ εάν απαιτείται προσαρμοσμένη λογική (επεκτείνετε το BaseExecutor).
3. Προσθέστε έναν translator στο open-sse/translator/ εάν δεν υποστηρίζει μορφή OpenAI.
4. Εάν βασίζεται σε OAuth, προσθέστε ρυθμίσεις στο src/lib/oauth/providers/ και src/lib/oauth/services/.
5. Καταχωρίστε μοντέλα στο open-sse/config/providerRegistry.ts (ή στο μητρώο ειδικού τύπου στο open-sse/config/).
6. Γράψτε δοκιμές στο tests/unit/.

Προσθήκη νέου API route

1. Δημιουργήστε το src/app/api/your-route/route.ts.
2. Ακολουθήστε το μοτίβο: CORS → επαλήθευση body με Zod → πιστοποίηση → ανάθεση σε handler.
3. Εάν υπάρχει νέα μορφή αιτήματος: προσθέστε το σχήμα Zod στο src/shared/validation/schemas.ts.
4. Εάν αφορά αποκλειστικά τη διαχείριση: προσθέστε το μονοπάτι στο src/shared/constants/publicApiRoutes.ts (λίστα άρνησης για την επιφάνεια του δημόσιου API).
5. Προσθέστε δοκιμές στο tests/unit/.
6. Ενημερώστε τα docs/reference/API_REFERENCE.md και docs/openapi.yaml.

Προσθήκη νέου DB module

1. Δημιουργήστε το src/lib/db/yourModule.ts και εισαγάγετε το getDbInstance() από το ./core.ts.
2. Εξαγάγετε συναρτήσεις CRUD για τον τομέα σας.
3. Εάν υπάρχουν νέοι πίνακες: προσθέστε ένα migration στο src/lib/db/migrations/, με αριθμητική σειρά, ιδεμποτεντικό και εντός συναλλαγής.
4. Τα modules που εισάγουν χρησιμοποιούν άμεσες εισαγωγές από το @/lib/db/yourModule (χωρίς barrel — το παλαιό επίπεδο επανεξαγωγής localDb.ts αφαιρέθηκε).
5. Προσθέστε δοκιμές στο tests/unit/.

Προσθήκη νέου MCP tool

1. Προσθέστε τον ορισμό του εργαλείου στο open-sse/mcp-server/tools/ (ή επεκτείνετε το open-sse/mcp-server/schemas/tools.ts).
2. Αναθέστε τα κατάλληλα scope(s) στο src/shared/constants/mcpScopes.ts.
3. Καταχωρίστε το εργαλείο στο open-sse/mcp-server/server.ts.
4. Προσθέστε δοκιμές στο open-sse/mcp-server/__tests__/.
5. Ενημερώστε το MCP-SERVER.md.

Προσθήκη νέου A2A skill

Δείτε A2A-SERVER.md § Adding a New Skill. Τα skills βρίσκονται στο src/lib/a2a/skills/ και καταχωρίζονται μέσω του A2A task manager.

---

11. Συμβάσεις

• Στυλ κώδικα: εσοχή 2 κενών, διπλά εισαγωγικά, πλάτος 100 χαρακτήρων, ερωτηματικά, es5 trailing commas — επιβάλλεται από το Prettier μέσω lint-staged.
• Εισαγωγές: εξωτερικές → εσωτερικές (@/, @omniroute/open-sse) → σχετικές.
• Ονοματολογία: αρχεία camelCase ή kebab-case, components PascalCase, σταθερές UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error παντού· no-explicit-any = warn στα open-sse/ και tests/, error αλλού.
• TypeScript: strict: false (παλαιά στάση). Προτιμήστε ρητούς τύπους αντί συμπερασμού για cross-module όρια.
• Βάση δεδομένων: μην γράφετε ποτέ ακατέργαστη SQL σε routes ή handlers — χρησιμοποιείτε πάντα τα modules του src/lib/db/. Μην χρησιμοποιείτε ποτέ barrel-import — χρησιμοποιείτε απευθείας συγκεκριμένα modules του src/lib/db/*.
• Τυποποίηση οντοτήτων ΒΔ (#3512): μια συνάρτηση που γράφει ή διαβάζει τη μορφή γραμμής ενός πίνακα ΒΔ πρέπει να δέχεται/επιστρέφει ένα ονομαστό TS interface που αντικατοπτρίζει 1:1 τις στήλες του πίνακα, όχι any ή ανώνυμο τύπο στο σημείο κλήσης. Τοποθετήστε το interface δίπλα στη συνάρτηση (π.χ. export interface UsageEntry στο src/lib/usage/usageHistory.ts πάνω από το saveRequestUsage), διατηρήστε μεμονωμένα πεδία ως optional/nullable όταν διαφορετικοί writers συμπληρώνουν τη γραμμή σταδιακά, και προτιμήστε unknown αντί any για ένα πεδίο του οποίου η μορφή ποικίλλει μεταξύ callers (τεκμηριωμένο στο πεδίο, π.χ. το UsageEntry.tokens δέχεται τόσο χρήση ακατέργαστης μορφής παρόχου όσο και την κανονικοποιημένη μορφή). Μόλις ο αριθμός any ενός αρχείου φτάσει στο μηδέν με αυτόν τον τρόπο, προσθέστε το στη λίστα επιτρεπομένων του check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) ώστε να μην μπορεί να υποστεί παλινδρόμηση. Αυτή είναι μια σύμβαση πρώτης εφαρμογής — η ευρύτερη εκκαθάριση «χωρίς ανώνυμο any» είναι επαναληπτική σε όλο τον υπόλοιπο κώδικα.
• Σφάλματα: try/catch με συγκεκριμένους τύπους σφαλμάτων, καταγραφή με pino context. Μην αποσιωπάτε ποτέ σφάλματα σε SSE streams· χρησιμοποιείτε abort signals για εκκαθάριση.
• Ασφάλεια: μην χρησιμοποιείτε ποτέ eval() / new Function() / implied eval. Επαληθεύετε όλες τις εισόδους με Zod. Κρυπτογραφείτε τα credentials σε κατάσταση ηρεμίας (AES-256-GCM). Διατηρείτε τη λίστα άρνησης του src/shared/constants/upstreamHeaders.ts ευθυγραμμισμένη με το επίπεδο sanitize/validation.
• Commits: Conventional Commits — feat(scope): subject. Επιτρεπόμενα scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branches: προθέματα feat/, fix/, refactor/, docs/, test/, chore/. Μην κάνετε ποτέ commit απευθείας στο 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. Ποτέ μην χρησιμοποιείτε barrel-import — χρησιμοποιείτε απευθείας συγκεκριμένα modules src/lib/db/*.
3. Ποτέ μην χρησιμοποιείτε eval() / new Function() / implied eval.
4. Ποτέ μην κάνετε commit απευθείας στο main.
5. Ποτέ μην γράφετε raw SQL σε routes — πάντα να χρησιμοποιείτε τα modules του src/lib/db/.
6. Ποτέ μην αποκρύπτετε αθόρυβα σφάλματα σε SSE streams.
7. Πάντα να επικυρώνετε τα inputs με σχήματα Zod.
8. Πάντα να συμπεριλαμβάνετε tests όταν αλλάζετε κώδικα παραγωγής.
9. Η κάλυψη πρέπει να παραμένει ≥ 60% (statements, lines, functions, branches).

---

13. Δείτε Επίσης

• ARCHITECTURE.md — αρχιτεκτονική υψηλού επιπέδου και ευθύνες module.
• API_REFERENCE.md — αναφορά δημόσιου + διαχειριστικού API.
• FEATURES.md — πίνακας χαρακτηριστικών και κύρια σημεία εκδόσεων.
• RESILIENCE_GUIDE.md — αναλυτική παρουσίαση circuit breaker, cooldown και lockout.
• AUTO-COMBO.md — βαθμολόγηση και στρατηγικές Auto Combo.
• MCP-SERVER.md — πλήρης κατάλογος εργαλείων MCP + transports.
• A2A-SERVER.md — δεξιότητες πρωτοκόλλου A2A και ανακάλυψη.
• COMPRESSION_GUIDE.md — συμπίεση RTK + Caveman.
• CLI-TOOLS.md — ενσωματώσεις CLI.
• ELECTRON_GUIDE.md (εάν υπάρχει), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — στόχοι ανάπτυξης/εγκατάστασης.
• TROUBLESHOOTING.md — συνηθισμένα λειτουργικά προβλήματα.
• CONTRIBUTING.md — ροή εργασίας συνεισφερόντων.
• CLAUDE.md — κανόνες αποθετηρίου για το Claude Code (η πηγή αλήθειας για πολλές από τις παραπάνω συμβάσεις).
• AGENTS.md — βαθύτερη αναφορά αρχιτεκτονικής που χρησιμοποιείται από agents.