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

OmniRoute Codebase Documentation (Bahasa Indonesia)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇳🇬 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

---

Versi: v3.8.51 Terakhir diperbarui: 2026-06-28 Audiens: Engineer yang berkontribusi pada OmniRoute atau membangun integrasi di atasnya.

Untuk diagram arsitektur tingkat tinggi dan alasan di balik setiap subsistem, baca ARCHITECTURE.md. Untuk pembahasan mendalam mengenai masing-masing subsistem (Auto Combo, server MCP, server A2A, Skills, Memory, Cloud Agents, Resilience, Compression, dll.), lihat file khususnya di direktori docs/ ini.

File ini menjelaskan apa yang saat ini tersedia di repositori sehingga engineer baru dapat menavigasi struktur direktori, memahami lapisan runtime, dan mengetahui tempat untuk menambahkan kode tanpa membuat modul baru.

---

1. Tumpukan Teknologi

Aspek	Pilihan
Kerangka kerja web	Next.js 16 (App Router, output mandiri, tanpa middleware global)
Bahasa	TypeScript 6.0+ — target ES2022, module: esnext, moduleResolution: bundler, strict: false
Runtime	Node.js >=22.22.2 <23 atau >=24.0.0 <27 (diterapkan melalui engines + SUPPORTED_NODE_RANGE)
Basis data	SQLite melalui better-sqlite3 (singleton, penjurnalan WAL)
Desktop	Electron 41 + electron-builder 26.10 (workspace terpisah di electron/)
Pengujian	Runner pengujian bawaan Node (unit/integrasi), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Next.js mandiri melalui scripts/build/build-next-isolated.mjs
Lint/format	Konfigurasi datar ESLint + Prettier (lint-staged melalui pre-commit Husky)
Sistem modul	ESM di semua tempat ("type": "module")
Workspace	workspace npm — open-sse adalah satu-satunya sub-workspace

Alias jalur (tsconfig.json):

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

Port HTTP default: 20128 (API dan dasbor menggunakan proses yang sama). Direktori data ditentukan oleh variabel lingkungan DATA_DIR, dengan nilai default ~/.omniroute/.

---

2. Tata Letak Repositori

OmniRoute/
├── src/                  Aplikasi Next.js (App Router, pustaka, domain, server, komponen bersama)
├── open-sse/             Workspace mesin streaming (@omniroute/open-sse)
├── electron/             Pembungkus desktop (proses utama + preload Electron 41)
├── bin/                  Titik masuk CLI (omniroute, reset-password)
├── tests/                Unit, integrasi, e2e, protocols-e2e, penerjemah, keamanan, fixture
├── scripts/              Skrip pembantu build, sinkronisasi, pemeriksaan, migrasi, dan runtime
├── docs/                 Dokumentasi publik (direktori ini)
├── public/               Aset statis, manifes PWA, service worker
├── config/               Contoh konfigurasi runtime
├── images/               Aset pemasaran/tangkapan layar
├── _ideia/, _references/, _mono_repo/, _tasks/   Catatan sementara / perencanaan internal (tidak didistribusikan)
├── CLAUDE.md             Aturan repositori untuk Claude Code
├── AGENTS.md             Referensi arsitektur yang lebih mendalam untuk agen
├── package.json          v3.8.51, root workspace
└── tsconfig.json         Alias jalur + opsi inti compiler

---

3. src/ — Aplikasi Next.js

src/
├── app/                  Halaman App Router + rute API
├── lib/                  Pustaka inti (DB, autentikasi, OAuth, skills, memori, …)
├── domain/               Lapisan domain murni (kebijakan, fallback, biaya, penguncian, …)
├── server/               Modul khusus server (otorisasi, cors, autentikasi)
├── shared/               Tipe, konstanta, validasi, kontrak, utilitas (aman lintas batas)
├── mitm/                 Helper proksi man-in-the-middle untuk integrasi CLI
├── models/               Metadata / aliasing model lokal
├── sse/                  Handler SSE lama yang masih berada di bawah src/ (bukan open-sse/)
├── store/                Store state sisi klien
├── middleware/           Utilitas middleware tingkat rute (bukan middleware global Next.js)
├── scripts/              Skrip dalam tree yang dapat diimpor oleh kode aplikasi
├── types/                Tipe TS ambient dan bersama
├── i18n/                 Bundel locale
├── instrumentation.ts    Hook instrumentasi Next.js
├── instrumentation-node.ts
└── proxy.ts              Helper bootstrap proksi tingkat atas

3.1 src/app/ — App Router

App Router mengekspos UI dasbor dan API HTTP publik/manajemen. Tidak ada middleware global — intersepsi dilakukan per rute.

Segmen tingkat atas di bawah src/app/:

Path	Tujuan
api/	Semua rute API HTTP (lihat perincian di bawah)
a2a/	Endpoint A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Dokumen penemuan Agent Card A2A
(dashboard)/	UI dasbor (grup rute, tanpa prefiks URL)
auth/, login/, forgot-password/, callback/	Alur autentikasi
landing/	Halaman pemasaran/landing
docs/	Penampil dokumentasi API tersemat
status/, maintenance/, offline/	Halaman operasional
privacy/, terms/	Halaman legal
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Halaman galat statis
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Batas galat/pemuatan framework
layout.tsx, page.tsx, globals.css, manifest.ts	Shell root

3.1.1 src/app/(dashboard)/dashboard/ — Halaman 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, ditambah page.tsx root, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Grup API tingkat atas

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/   Manajemen layanan tersemat (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API publik yang kompatibel dengan OpenAI
├── v1beta/     Kompatibilitas bergaya Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Manajemen Layanan Tersemat

Rute untuk menginstal, memulai, menghentikan, dan memantau 9Router serta CLIProxyAPI. Semua path diklasifikasikan sebagai LOCAL_ONLY (khusus loopback, aturan tegas #17) karena dapat menjalankan npm install dan membuat proses anak.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             helper getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install melalui 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 versi yang lebih baru
│   ├── rotate-key/route.ts POST — buat kunci API baru + mulai ulang
│   ├── status/route.ts     GET  — status langsung + DB + metadata versi
│   └── auto-start/route.ts POST — aktifkan/nonaktifkan flag auto_start
├── cliproxy/
│   ├── _lib.ts             helper 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 versi yang lebih baru
│   ├── status/route.ts     GET  — status langsung + DB + metadata versi
│   └── auto-start/route.ts POST — aktifkan/nonaktifkan flag auto_start
└── [name]/
    └── logs/route.ts       GET  — tail log SSE (digunakan bersama oleh semua layanan)

UI dasbor terkait: src/app/(dashboard)/dashboard/providers/services/ — halaman dua tab (CLIProxyAPI + 9Router). Proksi balik untuk UI tersemat 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Pembahasan mendalam: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API publik yang kompatibel dengan OpenAI

v1/
├── accounts/[id]/                       pencarian akun
├── agents/tasks/[id]/, agents/tasks/    endpoint tugas bergaya A2A
├── api/                                 helper API internal yang diekspos melalui v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (endpoint utama)
├── completions/                         penyelesaian teks lama
├── embeddings/                          embedding
├── files/[id]/, files/                  Files API
├── _helpers/                            helper rute bersama (tanpa URL publik)
├── images/{edits, generations}/         pembuatan + pengeditan gambar
├── issues/                              endpoint helper triase
├── management/{proxies}/                rute dengan cakupan manajemen di dalam v1
├── messages/{count_tokens}/             kompatibilitas pesan bergaya Anthropic
├── models/                              daftar model (`route.ts`, `catalog.ts`)
├── moderations/                         moderasi
├── music/                               pembuatan musik
├── providers/[provider]/                operasi per penyedia
├── quotas/{check}                       pemeriksaan kuota
├── registered-keys/                     administrasi kunci terdaftar
├── rerank/                              pemeringkatan ulang
├── responses/[...path]/                 OpenAI Responses API (catch-all)
├── search/                              pencarian web
├── videos/                              pembuatan video
├── ws/                                  jembatan WebSocket
└── route.ts                             handler indeks

Setiap file rute mengikuti pola yang sama:

Rute → preflight CORS → validasi body Zod → autentikasi opsional
     → penerapan kebijakan kunci API → delegasi handler (open-sse)

v1beta/ adalah permukaan kompatibilitas bergaya Gemini (pembungkus tipis yang menerjemahkan ke pipeline open-sse/handlers/ yang sama).

3.2 src/lib/ — Pustaka inti

Selalu impor data, sinkronisasi, OAuth, skill, memori, dan sebagainya melalui modul-modul ini. Tabel mengelompokkan direktori aktual dan file tingkat atas yang penting.

Modul	Tujuan
a2a/	Server protokol A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 keterampilan: analisis biaya, laporan kesehatan, penemuan penyedia, pengelolaan kuota, perutean cerdas, daftar kapabilitas)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Pembantu API internal: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (pengaturan ulang kata sandi / hashing)
batches/	Layanan OpenAI Batches API (service.ts)
catalog/	Sinkronisasi katalog OpenRouter (openrouterCatalog.ts)
cloudAgent/	Registri agen cloud: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Pembantu resolusi kombinasi
compliance/	Audit + audit penyedia: index.ts, providerAudit.ts
config/	Perekat konfigurasi runtime
db/	Modul domain SQLite (lihat §3.2.1)
display/	Pembantu UI/tampilan yang digunakan oleh respons API
embeddings/	Registri layanan embedding
env/	Pemuatan + introspeksi lingkungan
evals/	Runtime evaluasi
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Pekerjaan latar belakang (autoUpdate.ts, …)
memory/	Memori persisten: 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/	Modul OAuth/impor penyedia (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, serta services/, utils/, dan constants/oauth.ts
plugins/	Pemuat plugin (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Siklus hidup model terkelola: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Pembantu penyedia: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — pengaturan untuk pemutus sirkuit, periode jeda, penguncian
runtime/	Deteksi fitur runtime
search/	executeWebSearch.ts
services/	Kerangka kerja layanan tertanam: ServiceSupervisor.ts (supervisor proses anak generik dengan kunci operasi, buffer cincin, pemeriksa kesehatan), bootstrap.ts (pendaftaran tingkat proses dan mulai otomatis), registry.ts (peta alat → supervisor), apiKey.ts (penyimpanan kunci AES-256-GCM), modelSync.ts (sinkronisasi model berkala), ringBuffer.ts (buffer log sirkular 5 MB), healthCheck.ts (probe kesehatan HTTP), types.ts, embedWsProxy.ts (proksi WebSocket), installers/{ninerouter,cliproxy}.ts. Lihat docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalog + generator Keterampilan Agen: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → menulis skills/{id}/SKILL.md), openapiParser.ts (mengekstrak endpoint REST dari spesifikasi OpenAPI), cliRegistryParser.ts (mengekstrak subperintah CLI dari bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Digunakan oleh rute REST (/api/agent-skills/*), alat MCP (omniroute_agent_skills_*), dan keterampilan A2A list-capabilities. Lihat AGENT-SKILLS.md.
skills/	Kerangka kerja keterampilan: 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, serta builtin/browser.ts
spend/	batchWriter.ts (buffer tulis-tunda)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Pembantu tingkat sistem
translator/	Perekat penerjemah tingkat atas (mendelegasikan ke open-sse/translator/)
usage/	Akuntansi penggunaan: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Pembaruan otomatis + manifes versi
ws/	Jembatan WebSocket
zed-oauth/	Alur OAuth editor Zed

File tingkat atas di src/lib/:

• Barrel lama localDb.ts telah dihapus — konsumen mengimpor modul src/lib/db/* tertentu secara langsung.
• 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/

Database SQLite singleton (getDbInstance() di core.ts, penjurnalan WAL). Jangan pernah menulis SQL mentah di route atau handler — gunakan modul-modul ini.

Sumber: diagrams/db-schema-overview.mmd

Modul domain (masing-masing memiliki satu atau beberapa tabel): 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/ berisi 168 file .sql berversi (idempoten, transaksional) dan dieksekusi oleh migrationRunner.ts saat boot.

Tabel yang dibuat di seluruh migrasi (total 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 (ditambah tabel virtual FTS5 untuk pencarian memori).

3.3 src/domain/ — Lapisan domain

Logika bisnis murni, tanpa I/O. Diimpor oleh route dan handler.

File	Tujuan
policyEngine.ts	Resolver kebijakan tingkat atas
fallbackPolicy.ts	Pohon keputusan fallback
costRules.ts	Aturan penghitungan biaya
lockoutPolicy.ts	Keputusan penguncian model
tagRouter.ts	Perutean berbasis tag
comboResolver.ts	Resolusi combo dari permintaan → daftar target
connectionModelRules.ts	Filter model per koneksi
modelAvailability.ts	Pemeriksaan ketersediaan model
degradation.ts	Transisi mode terdegradasi
providerExpiration.ts	Deteksi akun/kunci kedaluwarsa
quotaCache.ts	Keputusan kuota yang di-cache
responses.ts, omnirouteResponseMeta.ts	Pembantu bentuk respons
configAudit.ts	Audit perubahan konfigurasi
assessment/	Penilaian model (sesuai RFC, diimplementasikan sebagian)
types.ts	Tipe domain bersama

3.4 src/server/ — Khusus server

Tidak dapat diimpor dari komponen klien.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Mengklasifikasikan route sebagai publik atau manajemen
│   ├── assertAuth.ts      Pembantu assertion
│   ├── context.ts         Konteks authz per permintaan
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline authz
│   ├── policies/          Kebijakan konkret
│   └── types.ts
└── cors/origins.ts        Daftar asal CORS yang diizinkan

3.5 src/shared/ — Aman untuk dibagikan

Dibagi menjadi subdirektori yang berfokus pada fungsi tertentu:

• constants/ — providers.ts (katalog penyedia yang divalidasi dengan Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (daftar larangan), 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 skema Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — kontrak API publik yang didistribusikan ke npm.
• types/ — tipe TS bersama.
• 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, serta hook/komponen dasbor di bawah services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Ruang kerja mesin streaming

Ruang kerja npm terpisah yang dipublikasikan sebagai @omniroute/open-sse. Mengelola pemrosesan permintaan, eksekutor, penerjemah, layanan, transformer, dan server MCP.

open-sse/
├── index.ts                Ekspor publik
├── package.json            Manifes ruang kerja
├── tsconfig.json
├── types.d.ts
├── config/                 Registri penyedia, profil header, identitas, …
├── handlers/               Penangan permintaan (chat, embeddings, audio, gambar, …)
├── executors/              108 eksekutor HTTP khusus penyedia
├── translator/             Konversi format (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer streaming Responses API ↔ Chat Completions
├── services/               80+ modul layanan (kombinasi, fallback, kuota, identitas, …)
├── utils/                  Pembantu streaming, klien TLS, AWS SigV4, pengambilan melalui proksi, …
└── mcp-server/             Server MCP (3 transport, 33 cakupan, 110 alat)

4.1 open-sse/handlers/

Penangan	Tujuan
chatCore.ts	Alur utama chat (cache, batas laju, perutean kombinasi, pengiriman eksekutor)
responsesHandler.ts	Titik masuk OpenAI Responses API
embeddings.ts	Embeddings
imageGeneration.ts	Pembuatan gambar
audioSpeech.ts	Teks-ke-ucapan
audioTranscription.ts	Ucapan-ke-teks
videoGeneration.ts	Pembuatan video
musicGeneration.ts	Pembuatan musik
rerank.ts	Pemeringkatan ulang
moderations.ts	Moderasi
search.ts	Pencarian web
sseParser.ts	Parser peristiwa SSE
usageExtractor.ts	Mengekstrak jumlah token dari streaming upstream
responseSanitizer.ts	Menghapus derau khusus penyedia
responseTranslator.ts	Penghubung antara respons penyedia dan lapisan penerjemah

4.2 open-sse/executors/

108 eksekutor penyedia, masing-masing memperluas 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, serta claudeIdentity.ts (pembantu identitas bersama) dan index.ts (registri).

Catatan: penyedia yang tidak tercantum di sini dilayani oleh default.ts menggunakan eksekutor generik yang kompatibel dengan OpenAI. Katalog penyedia lengkap (355 penyedia) berada di src/shared/constants/providers.ts.

4.3 open-sse/translator/

Penerjemahan hub-and-spoke (OpenAI adalah hub).

• 9 penerjemah permintaan (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 penerjemah respons (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 pembantu (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, serta pengujian pembantu.
• Pembantu gambar (translator/image/sizeMapper.ts).
• Tingkat teratas: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Konverter Responses API ↔ Chat Completions berbasis TransformStream (digunakan oleh catch-all rute responses/).

4.5 open-sse/services/

Sorotan (daftar lengkap berada di bawah open-sse/services/):

Aspek	File
Perutean kombo	combo.ts (19 strategi), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Mesin 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
Ketahanan	accountFallback.ts (masa tunggu + penguncian), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Kuota	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Penyimpanan cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Kecerdasan perutean	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Penanganan model	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Kompresi	compression/ — seluruh pengintegrasian mesin kompresi
Token + sesi	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Tingkat / manifes	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / jaringan	ipFilter.ts, webSearchFallback.ts
Batch	batchProcessor.ts
Penggunaan	usage.ts

4.6 open-sse/mcp-server/

• 110 alat unik yang diintegrasikan dalam server.ts (45 alat kanonis dalam schemas/tools.ts + modul memori, keterampilan, keterampilan GitHub, pool, gamifikasi, plugin, Notion, Obsidian, korpus lokal, dan kompresi — gabungannya dihitung oleh countUniqueMcpTools).
• 3 transportasi: stdio, HTTP Streamable, SSE.
• 33 cakupan diberlakukan saat runtime — daftar dasar terdapat dalam src/shared/constants/mcpScopes.ts, rangkaian lengkapnya merupakan gabungan cakupan yang dideklarasikan oleh setiap modul alat.
• Tabel audit: mcp_tool_audit (diisi oleh audit.ts).
• File: 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, serta pengujian di bawah __tests__/.
• Lihat MCP-SERVER.md untuk katalog alat lengkap.

4.7 open-sse/config/

Registri penyedia (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registri model per format (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), pembantu identitas (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), pembantu kredensial (credentialLoader.ts, codexClient.ts), dan adaptor 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/

Primitif streaming dan helper penyedia: 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/ — Pembungkus desktop

electron/
├── main.js                  Proses utama Electron
├── preload.js               Jembatan preload (contextIsolation diaktifkan)
├── types.d.ts
├── package.json             Konfigurasi electron-builder, versi 3.8.51
├── README.md
├── assets/                  Sumber daya build (ikon, hak akses, …)
├── node_modules/            node_modules khusus (better-sqlite3, electron-updater)
└── dist-electron/           Output build (tidak di-commit)

Lima skrip npm di root workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Pembaruan otomatis dilakukan melalui electron-updater yang mengarah ke feed rilis GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Entri CLI utama (Node ESM)
├── reset-password.mjs      Mereset kata sandi pengelolaan dari CLI
├── mcp-server.mjs          Peluncur server MCP (stdio)
├── nodeRuntimeSupport.mjs  Pemeriksaan versi Node
└── cli/
    ├── program.mjs         Pembuat program Commander
    ├── runtime.mjs         Helper withRuntime (utamakan server/fallback ke DB)
    ├── output.mjs          Pemformat output (json/jsonl/table/csv)
    ├── i18n.mjs            Helper t() dengan locale
    ├── api.mjs             Helper fetch API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Pendaftaran perintah
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (satu file per perintah/grup)

Dua biner diekspos di package.json → bin:

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

---

7. tests/

Direktori	Jenis
tests/unit/	Pengujian unit melalui test runner native Node (1821 file, ditambah subdirektori api/, auth/, authz/)
tests/integration/	Pengujian lintas modul + status DB
tests/e2e/	Pengujian UI Playwright
tests/e2e/protocol-clients.test.ts	Pengujian e2e protokol MCP/A2A
tests/translator/	Pengujian khusus penerjemah
tests/security/	Regresi keamanan
tests/load/	Pengujian beban / stres
tests/golden-set/	Output referensi untuk regresi penerjemah
tests/helpers/, tests/fixtures/, tests/manual/	Pendukung

Perintah umum:

Perintah	Yang dijalankan
npm run test:unit	Semua tests/unit/*.test.ts melalui test runner Node (konkurensi 10)
npm run test:vitest	Suite Vitest (MCP, autoCombo, cache)
npm run test:e2e	Suite UI Playwright
npm run test:protocols:e2e	Pengujian e2e protokol MCP + A2A
npm run test:coverage	Ambang cakupan (≥60% baris/pernyataan/fungsi/cabang)
node --import tsx/esm --test tests/unit/<file>.test.ts	Menjalankan satu file

---

8. scripts/

Diorganisasikan ke dalam 6 subfolder berdasarkan tujuan.

• 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. Alur Permintaan (Ringkasan)

Sumber: diagrams/request-pipeline.mmd

Permintaan klien
  → /v1/chat/completions (route.ts)
     Pemeriksaan preflight CORS
     Validasi Zod (chatCompletionsSchema di shared/validation/schemas.ts)
     Autentikasi (extractApiKey + isValidApiKey ATAU requireManagementAuth)
     Mesin kebijakan (src/server/authz/pipeline.ts)
     Pembatas pengaman (penyamaran PII, injeksi prompt, bridge visi)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Pemeriksaan cache (cache semantik + cache baca)
     Batas laju (rateLimitManager, accountSemaphore)
     Perutean kombo (jika model diresolusikan menjadi kombo)
       comboResolver → perulangan per target → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       pengambilan dari upstream → percobaan ulang/backoff melalui accountFallback
     translateResponse() (open-sse/translator/response/*)
     Aliran SSE ATAU respons JSON
     Jika Responses API: TransformStream melalui open-sse/transformer/responsesTransformer.ts
  → Audit kepatuhan (src/lib/compliance/)
  → Respons kepada klien

Status runtime ketahanan (tiga mekanisme)

Mekanisme	Cakupan	Lokasi
Pemutus sirkuit penyedia	Seluruh penyedia	src/shared/utils/circuitBreaker.ts, disimpan di domain_circuit_breakers
Masa jeda koneksi	Satu akun/kunci	markAccountUnavailable() di src/sse/services/auth.ts; digunakan oleh accountFallback.checkFallbackError()
Penguncian model	Penyedia + koneksi + model	open-sse/services/accountFallback.ts, disimpan di domain_lockout_state

Lihat RESILIENCE_GUIDE.md dan bagian khusus di CLAUDE.md.

---

10. Cara Berkontribusi

Menambahkan provider baru

1. Daftarkan di src/shared/constants/providers.ts (divalidasi oleh Zod saat dimuat).
2. Tambahkan executor di open-sse/executors/ jika memerlukan logika khusus (perluas BaseExecutor).
3. Tambahkan translator di open-sse/translator/ jika tidak menggunakan format OpenAI.
4. Jika berbasis OAuth, tambahkan konfigurasi di src/lib/oauth/providers/ dan src/lib/oauth/services/.
5. Daftarkan model di open-sse/config/providerRegistry.ts (atau registry khusus format di bawah open-sse/config/).
6. Tulis pengujian di bawah tests/unit/.

Menambahkan route API baru

1. Buat src/app/api/your-route/route.ts.
2. Ikuti pola: CORS → validasi body dengan Zod → autentikasi → delegasi ke handler.
3. Jika bentuk request baru: tambahkan skema Zod di src/shared/validation/schemas.ts.
4. Jika khusus manajemen: tambahkan path ke src/shared/constants/publicApiRoutes.ts (denylist untuk permukaan API publik).
5. Tambahkan pengujian di bawah tests/unit/.
6. Perbarui docs/reference/API_REFERENCE.md dan docs/openapi.yaml.

Menambahkan modul DB baru

1. Buat src/lib/db/yourModule.ts dan impor getDbInstance() dari ./core.ts.
2. Ekspor fungsi CRUD untuk domain Anda.
3. Jika ada tabel baru: tambahkan migrasi di bawah src/lib/db/migrations/, dengan nomor berurutan, idempoten, dan transaksional.
4. Pengimpor menggunakan impor langsung dari @/lib/db/yourModule (tanpa barrel — lapisan ekspor ulang localDb.ts yang lama telah dihapus).
5. Tambahkan pengujian di bawah tests/unit/.

Menambahkan alat MCP baru

1. Tambahkan definisi alat di bawah open-sse/mcp-server/tools/ (atau perluas open-sse/mcp-server/schemas/tools.ts).
2. Tetapkan scope yang sesuai di src/shared/constants/mcpScopes.ts.
3. Daftarkan alat di open-sse/mcp-server/server.ts.
4. Tambahkan pengujian di bawah open-sse/mcp-server/__tests__/.
5. Perbarui MCP-SERVER.md.

Menambahkan skill A2A baru

Lihat A2A-SERVER.md § Menambahkan Skill Baru. Skill berada di src/lib/a2a/skills/ dan didaftarkan melalui pengelola tugas A2A.

---

11. Konvensi

• Gaya kode: indentasi 2 spasi, tanda kutip ganda, lebar 100 karakter, titik koma, koma akhir es5 — diterapkan oleh Prettier melalui lint-staged.
• Impor: eksternal → internal (@/, @omniroute/open-sse) → relatif.
• Penamaan: file menggunakan camelCase atau kebab-case, komponen menggunakan PascalCase, konstanta menggunakan UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error di semua tempat; no-explicit-any = warn di open-sse/ dan tests/, error di tempat lain.
• TypeScript: strict: false (pendekatan lama). Utamakan tipe eksplisit daripada inferensi untuk batas antar-modul.
• Database: jangan pernah menulis SQL mentah di route atau handler — selalu gunakan modul src/lib/db/. Jangan pernah melakukan impor melalui barrel — gunakan modul src/lib/db/* tertentu secara langsung.
• Pengetikan entitas DB (#3512): fungsi yang menulis atau membaca bentuk baris tabel DB harus menerima/mengembalikan interface TS bernama yang mencerminkan kolom tabel tersebut secara 1:1, bukan any atau tipe anonim inline di lokasi pemanggilan. Tempatkan interface di dekat fungsi (misalnya export interface UsageEntry di src/lib/usage/usageHistory.ts di atas saveRequestUsage), pertahankan setiap field sebagai opsional/dapat bernilai null ketika writer yang berbeda mengisi baris secara bertahap, dan utamakan unknown daripada any untuk field yang bentuknya berbeda-beda antar-pemanggil (didokumentasikan pada field tersebut, misalnya UsageEntry.tokens menerima data penggunaan mentah dengan bentuk dari provider maupun bentuk yang telah dinormalisasi). Setelah jumlah any dalam sebuah file mencapai nol melalui cara ini, tambahkan file tersebut ke allowlist check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) agar tidak mengalami regresi. Ini adalah konvensi tahap awal — pembersihan "tanpa any anonim" yang lebih luas dilakukan secara iteratif di seluruh codebase lainnya.
• Error: gunakan try/catch dengan tipe error tertentu, catat log dengan konteks pino. Jangan pernah mengabaikan error secara diam-diam dalam stream SSE; gunakan sinyal abort untuk pembersihan.
• Keamanan: jangan pernah menggunakan eval() / new Function() / eval tersirat. Validasi semua input dengan Zod. Enkripsi kredensial saat disimpan (AES-256-GCM). Jaga agar denylist src/shared/constants/upstreamHeaders.ts tetap selaras dengan lapisan sanitasi/validasi.
• Commit: Conventional Commits — feat(scope): subject. Scope yang diizinkan: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branch: awalan feat/, fix/, refactor/, docs/, test/, chore/. Jangan pernah melakukan commit langsung ke main.
• Husky: pre-commit menjalankan lint-staged + check:docs-sync + check:any-budget:t11; pre-push menjalankan check:any-budget:t11 + check:tracked-artifacts (pemeriksaan cepat; mengecualikan test:unit).

---

12. Aturan Ketat (dari CLAUDE.md)

1. Jangan pernah melakukan commit terhadap rahasia atau kredensial.
2. Jangan pernah melakukan barrel import — gunakan modul src/lib/db/* tertentu secara langsung.
3. Jangan pernah menggunakan eval() / new Function() / eval tersirat.
4. Jangan pernah melakukan commit langsung ke main.
5. Jangan pernah menulis SQL mentah di route — selalu gunakan modul src/lib/db/.
6. Jangan pernah mengabaikan error secara diam-diam dalam stream SSE.
7. Selalu validasi input dengan skema Zod.
8. Selalu sertakan pengujian saat mengubah kode produksi.
9. Cakupan pengujian harus tetap ≥ 60% (pernyataan, baris, fungsi, cabang).

---

13. Lihat Juga

• ARCHITECTURE.md — arsitektur tingkat tinggi dan tanggung jawab modul.
• API_REFERENCE.md — referensi API publik + manajemen.
• FEATURES.md — matriks fitur dan sorotan versi.
• RESILIENCE_GUIDE.md — pembahasan mendalam tentang circuit breaker, cooldown, dan lockout.
• AUTO-COMBO.md — penilaian dan strategi Auto Combo.
• MCP-SERVER.md — katalog lengkap alat MCP + transport.
• A2A-SERVER.md — keterampilan dan penemuan protokol A2A.
• COMPRESSION_GUIDE.md — kompresi RTK + Caveman.
• CLI-TOOLS.md — integrasi CLI.
• ELECTRON_GUIDE.md (jika tersedia), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — target deployment.
• TROUBLESHOOTING.md — masalah operasional umum.
• CONTRIBUTING.md — alur kerja kontributor.
• CLAUDE.md — aturan repositori untuk Claude Code (sumber acuan utama bagi banyak konvensi di atas).
• AGENTS.md — referensi arsitektur lebih mendalam yang digunakan oleh agen.