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

OmniRoute Codebase Documentation (日本語)

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

---

バージョン: v3.8.51 最終更新日: 2026-06-28 対象読者: OmniRoute にコントリビュートするエンジニア、または OmniRoute 上にインテグレーションを構築するエンジニア。

高レベルのアーキテクチャ図と各サブシステムの設計理由については、 ARCHITECTURE.md を参照してください。個々のサブシステム （Auto Combo、MCP server、A2A server、Skills、Memory、Cloud Agents、Resilience、 Compression など）の詳細については、この docs/ ディレクトリ内にある各専用ファイルを参照してください。

このファイルでは、現在リポジトリに存在するものについて説明します。これにより、新しいエンジニアが ディレクトリツリーを把握し、ランタイムの階層構造を理解し、新しいモジュールを考案することなく コードを追加すべき場所を判断できるようになります。

---

1. 技術スタック

項目	採用技術
Webフレームワーク	Next.js 16（App Router、スタンドアロン出力、グローバルミドルウェアなし）
言語	TypeScript 6.0+ — ターゲット ES2022、module: esnext、moduleResolution: bundler、strict: false
ランタイム	Node.js >=22.22.2 <23 または >=24.0.0 <27（engines + SUPPORTED_NODE_RANGE によって強制）
データベース	better-sqlite3 経由の SQLite（シングルトン、WALジャーナリング）
デスクトップ	Electron 41 + electron-builder 26.10（electron/ に独立したワークスペース）
テスト	Nodeネイティブテストランナー（ユニット／統合）、Vitest（MCP、autoCombo、キャッシュ）、Playwright（e2e + protocols-e2e）
ビルド	scripts/build/build-next-isolated.mjs による Next.js スタンドアロン
リント／フォーマット	ESLint フラット設定 + Prettier（Husky の pre-commit による lint-staged）
モジュールシステム	全体で ESM（"type": "module"）
ワークスペース	npm workspace — open-sse が唯一のサブワークスペース

パスエイリアス（tsconfig.json）:

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

デフォルトのHTTPポート: 20128（APIとダッシュボードは同じプロセスを共有します）。データ ディレクトリは環境変数 DATA_DIR で指定し、デフォルトは ~/.omniroute/ です。

---

2. リポジトリ構成

OmniRoute/
├── src/                  Next.jsアプリケーション（App Router、ライブラリ、ドメイン、サーバー、共有コード）
├── open-sse/             ストリーミングエンジンのワークスペース（@omniroute/open-sse）
├── electron/             デスクトップラッパー（Electron 41のメイン + preload）
├── bin/                  CLIエントリーポイント（omniroute、reset-password）
├── tests/                ユニット、統合、e2e、protocols-e2e、トランスレーター、セキュリティ、フィクスチャ
├── scripts/              ビルド、同期、チェック、マイグレーション、ランタイム用の補助スクリプト
├── docs/                 公開ドキュメント（このディレクトリ）
├── public/               静的アセット、PWAマニフェスト、サービスワーカー
├── config/               ランタイム設定のサンプル
├── images/               マーケティング／スクリーンショット用アセット
├── _ideia/, _references/, _mono_repo/, _tasks/   内部の作業用／計画用（配布対象外）
├── CLAUDE.md             Claude Code向けのリポジトリルール
├── AGENTS.md             エージェント向けの詳細なアーキテクチャリファレンス
├── package.json          v3.8.51、ワークスペースルート
└── tsconfig.json         パスエイリアス + コアコンパイラオプション

---

3. src/ — Next.js アプリケーション

src/
├── app/                  App Router ページ + API ルート
├── lib/                  コアライブラリ（DB、認証、OAuth、スキル、メモリなど）
├── domain/               純粋なドメインレイヤー（ポリシー、フォールバック、コスト、ロックアウトなど）
├── server/               サーバー専用モジュール（認可、CORS、認証）
├── shared/               型、定数、バリデーション、コントラクト、ユーティリティ（境界をまたいで安全に利用可能）
├── mitm/                 CLI 統合用の中間者プロキシヘルパー
├── models/               ローカルモデルのメタデータ / エイリアス設定
├── sse/                  src/ 配下に残っているレガシー SSE ハンドラー（open-sse/ ではない）
├── store/                クライアント側の状態ストア
├── middleware/           ルートレベルのミドルウェアユーティリティ（Next.js のグローバルミドルウェアではない）
├── scripts/              アプリケーションコードからインポート可能なツリー内スクリプト
├── types/                アンビエントおよび共有 TS 型
├── i18n/                 ロケールバンドル
├── instrumentation.ts    Next.js インストルメンテーションフック
├── instrumentation-node.ts
└── proxy.ts              トップレベルのプロキシブートストラップヘルパー

3.1 src/app/ — App Router

App Router は、ダッシュボード UI と公開・管理用 HTTP API の両方を提供します。 グローバルミドルウェアは存在せず、インターセプトはルートごとに実行されます。

src/app/ 配下のトップレベルセグメント：

パス	目的
api/	すべての HTTP API ルート（内訳は以下を参照）
a2a/	A2A JSON-RPC 2.0 エンドポイント（POST /a2a）
.well-known/agent.json/	A2A Agent Card 検出ドキュメント
(dashboard)/	ダッシュボード UI（ルートグループ、URL プレフィックスなし）
auth/, login/, forgot-password/, callback/	認証フロー
landing/	マーケティング / ランディングページ
docs/	組み込み API ドキュメントビューアー
status/, maintenance/, offline/	運用ページ
privacy/, terms/	法的情報ページ
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	静的エラーページ
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	フレームワークのエラー / ローディング境界
layout.tsx, page.tsx, globals.css, manifest.ts	ルートシェル

3.1.1 src/app/(dashboard)/dashboard/ — UI ページ

agents、analytics、api-manager、audit、auto-combo、batch、cache、 changelog、cli-tools、cloud-agents、combos、compression、context、 costs、endpoint、health、limits、logs、memory、onboarding、 playground、providers、search-tools、settings、skills、system、 translator、usage、webhooks、およびルートの page.tsx、HomePageClient.tsx、 BootstrapBanner.tsx。

3.1.2 src/app/api/ — トップレベル API グループ

src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   組み込みサービス管理（9router、cliproxy）— LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         OpenAI 互換の公開 API
├── v1beta/     Gemini 形式との互換性
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — 組み込みサービス管理

9Router および CLIProxyAPI のインストール、起動、停止、監視を行うためのルートです。 npm install を実行し、子プロセスを生成できるため、すべてのパスは LOCAL_ONLY （ループバックのみ、厳格なルール #17）に分類されます。

src/app/api/services/
├── 9router/
│   ├── _lib.ts             getOrInitSupervisor() ヘルパー
│   ├── install/route.ts    POST — execFile 経由で npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — より新しいバージョンを npm install
│   ├── rotate-key/route.ts POST — 新しい API キーを生成して再起動
│   ├── status/route.ts     GET  — ライブ状態 + DB 状態 + バージョンメタデータ
│   └── auto-start/route.ts POST — auto_start フラグを切り替え
├── cliproxy/
│   ├── _lib.ts             getOrInitSupervisor() ヘルパー
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — より新しいバージョンを npm install
│   ├── status/route.ts     GET  — ライブ状態 + DB 状態 + バージョンメタデータ
│   └── auto-start/route.ts POST — auto_start フラグを切り替え
└── [name]/
    └── logs/route.ts       GET  — SSE ログ末尾の取得（全サービスで共有）

対応するダッシュボード UI： src/app/(dashboard)/dashboard/providers/services/ — 2 タブ構成のページ（CLIProxyAPI + 9Router）。 9Router 組み込み UI 用のリバースプロキシ： src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

詳細解説：docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — OpenAI 互換の公開 API

v1/
├── accounts/[id]/                       アカウント検索
├── agents/tasks/[id]/, agents/tasks/    A2A 形式のタスクエンドポイント
├── api/                                 v1/api 配下で公開される内部 API ヘルパー
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions（メインエンドポイント）
├── completions/                         レガシーなテキスト補完
├── embeddings/                          埋め込み
├── files/[id]/, files/                  Files API
├── _helpers/                            共有ルートヘルパー（公開 URL なし）
├── images/{edits, generations}/         画像生成 + 編集
├── issues/                              トリアージ用ヘルパーエンドポイント
├── management/{proxies}/                v1 内の管理スコープルート
├── messages/{count_tokens}/             Anthropic 形式のメッセージ互換
├── models/                              モデル一覧（`route.ts`、`catalog.ts`）
├── moderations/                         モデレーション
├── music/                               音楽生成
├── providers/[provider]/                プロバイダーごとの操作
├── quotas/{check}                       クォータ検査
├── registered-keys/                     登録済みキーの管理
├── rerank/                              再ランキング
├── responses/[...path]/                 OpenAI Responses API（キャッチオール）
├── search/                              Web 検索
├── videos/                              動画生成
├── ws/                                  WebSocket ブリッジ
└── route.ts                             インデックスハンドラー

すべてのルートファイルは同じパターンに従います：

ルート → CORS プリフライト → Zod によるボディ検証 → オプションの認証
       → API キーポリシーの適用 → ハンドラーへの委譲（open-sse）

v1beta/ は Gemini 形式の互換インターフェースです（同じ open-sse/handlers/ パイプライン向けに変換する薄いラッパー）。

3.2 src/lib/ — コアライブラリ

データ、同期、OAuth、スキル、メモリなどは、常にこれらのモジュールを通じてインポートしてください。 以下の表では、実際のディレクトリと主要なトップレベルファイルをグループ化しています。

モジュール	目的
a2a/	A2A プロトコルサーバー: taskManager.ts、streaming.ts、taskExecution.ts、routingLogger.ts、skills/（6つのスキル: コスト分析、ヘルスレポート、プロバイダー検出、クォータ管理、スマートルーティング、機能一覧）
acp/	Agent-Control-Protocol: index.ts、manager.ts、registry.ts
api/	内部 API ヘルパー: requireManagementAuth.ts、requireCliToolsAuth.ts、errorResponse.ts
auth/	managementPassword.ts（パスワードのリセット / ハッシュ化）
batches/	OpenAI Batches API サービス（service.ts）
catalog/	OpenRouter カタログ同期（openrouterCatalog.ts）
cloudAgent/	クラウドエージェントレジストリ: api.ts、baseAgent.ts、db.ts、index.ts、registry.ts、types.ts、agents/{codex, devin, jules}.ts
combos/	コンボ解決ヘルパー
compliance/	監査 + プロバイダー監査: index.ts、providerAudit.ts
config/	ランタイム設定の統合
db/	SQLite ドメインモジュール（§3.2.1を参照）
display/	API レスポンスで使用される UI / 表示ヘルパー
embeddings/	埋め込みサービスレジストリ
env/	環境変数の読み込み + イントロスペクション
evals/	評価ランタイム
guardrails/	piiMasker.ts、promptInjection.ts、visionBridge.ts、visionBridgeHelpers.ts、registry.ts、base.ts
jobs/	バックグラウンドジョブ（autoUpdate.ts、…）
memory/	永続メモリ: store.ts、cache.ts、retrieval.ts、summarization.ts、extraction.ts、injection.ts、qdrant.ts、settings.ts、verify.ts、schemas.ts、types.ts
monitoring/	observability.ts
oauth/	OAuth / インポートプロバイダーモジュール（22個）: agy、antigravity、claude、cline、codebuddy-cn、codex、cursor、devin-desktop、ghe-copilot、github、gitlab-duo、grok-cli-oauth、grok-cli、kilocode、kimi-coding、kiro、openference、qoder、trae、xai-oauth、zed-hosted、zed、および services/、utils/、constants/oauth.ts
plugins/	プラグインローダー（index.ts）
promptCache/	prefixAnalyzer.ts、index.ts
providerModels/	管理対象モデルのライフサイクル: modelDiscovery.ts、managedModelImport.ts、managedAvailableModels.ts、cursorAgent.ts
providers/	プロバイダーヘルパー: catalog.ts、validation.ts、imageValidation.ts、claudeExtraUsage.ts、codexConnectionDefaults.ts、codexFastTier.ts、webCookieAuth.ts、managedAvailableModels.ts、requestDefaults.ts
resilience/	settings.ts — サーキットブレーカー、クールダウン、ロックアウトの設定
runtime/	ランタイム機能の検出
search/	executeWebSearch.ts
services/	組み込みサービスフレームワーク: ServiceSupervisor.ts（操作ロック、リングバッファ、ヘルスチェッカーを備えた汎用子プロセススーパーバイザー）、bootstrap.ts（プロセスレベルの登録と自動起動）、registry.ts（ツール → スーパーバイザーのマップ）、apiKey.ts（AES-256-GCM キーストア）、modelSync.ts（定期的なモデル同期）、ringBuffer.ts（5 MB の循環ログバッファ）、healthCheck.ts（HTTP ヘルスプローブ）、types.ts、embedWsProxy.ts（WebSocket プロキシ）、installers/{ninerouter,cliproxy}.ts。docs/frameworks/EMBEDDED-SERVICES.md を参照
agentSkills/	Agent Skills カタログ + ジェネレーター: catalog.ts（getCatalog/getSkillById/filterCatalog/computeCoverage）、generator.ts（generateAgentSkills → skills/{id}/SKILL.md に書き込み）、openapiParser.ts（OpenAPI 仕様から REST エンドポイントを抽出）、cliRegistryParser.ts（bin/cli-registry から CLI サブコマンドを抽出）、schemas.ts（Zod: AgentSkillSchema、SkillCoverageSchema、ListQuerySchema、GenerateBodySchema）、types.ts（AgentSkill、SkillCoverage、SkillMarkdown、GeneratorReport）。REST ルート（/api/agent-skills/*）、MCP ツール（omniroute_agent_skills_*）、A2A スキル list-capabilities から利用されます。AGENT-SKILLS.md を参照してください。
skills/	スキルフレームワーク: registry.ts、executor.ts、interception.ts、injection.ts、sandbox.ts、custom.ts、hybrid.ts、builtins.ts、a2a.ts、providerSettings.ts、schemas.ts、skillssh.ts、types.ts、および builtin/browser.ts
spend/	batchWriter.ts（ライトビハインドバッファ）
sync/	bundle.ts、tokens.ts（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/	自動更新 + バージョンマニフェスト
ws/	WebSocket ブリッジ
zed-oauth/	Zed エディターの OAuth フロー

src/lib/ 直下のファイル:

• 旧 localDb.ts バレルは削除されました。利用側では、個別の src/lib/db/* モジュールを直接インポートします。
• proxyHealth.ts, proxyLogger.ts, tokenHealthCheck.ts, localHealthCheck.ts
• apiBridgeServer.ts, cacheLayer.ts, semanticCache.ts, settingsCache.ts
• cloudSync.ts, initCloudSync.ts
• cloudflaredTunnel.ts, ngrokTunnel.ts, tailscaleTunnel.ts
• consoleInterceptor.ts, container.ts, gracefulShutdown.ts, idempotencyLayer.ts
• ipUtils.ts, logEnv.ts, logPayloads.ts, logRotation.ts
• modelAliasSeed.ts, modelCapabilities.ts, modelMetadataRegistry.ts, modelsDevSync.ts
• piiSanitizer.ts, pricingSync.ts
• apiKeyExposure.ts, cacheControlSettings.ts, dataPaths.ts, toolPolicy.ts
• translatorEvents.ts, usageDb.ts, usageAnalytics.ts, webhookDispatcher.ts

3.2.1 src/lib/db/

シングルトン SQLite データベース（core.ts の getDbInstance()、WAL ジャーナリング）。 ルートやハンドラーに生の SQL を記述しないでください — 必ずこれらのモジュールを経由してください。

出典: diagrams/db-schema-overview.mmd

ドメインモジュール（各モジュールが1つ以上のテーブルを管理）: 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/ には、バージョン管理された .sql ファイルが168個（冪等かつトランザクショナル）格納されており、起動時に migrationRunner.ts によって実行されます。

マイグレーション全体で作成されるテーブル（合計123個）:

a, account_key_limits, api_keys, batches, call_logs, combo_adaptation_state, combos, command_code_auth_sessions, compression_analytics, compression_cache_stats, compression_combo_assignments, compression_combos, context_handoffs, daily_usage_summary, db_meta, domain_budgets, domain_circuit_breakers, domain_cost_history, domain_fallback_chains, domain_lockout_state, eval_cases, eval_runs, eval_suites, files, hourly_usage_summary, key_value, mcp_tool_audit, memories, model_combo_mappings, provider_connections, provider_key_limits, provider_nodes, proxy_assignments, proxy_logs, proxy_registry, quota_snapshots, reasoning_cache, registered_keys, request_detail_logs, routing_decisions, semantic_cache, session_account_affinity, skill_executions, skills, sync_tokens, tier_assignments, tier_config, upstream_proxy_config, usage_history, version_manager, webhooks（およびメモリ検索用の FTS5 仮想テーブル）。

3.3 src/domain/ — ドメインレイヤー

I/O を含まない純粋なビジネスロジックです。ルートおよびハンドラーからインポートされます。

ファイル	目的
policyEngine.ts	最上位のポリシーリゾルバー
fallbackPolicy.ts	フォールバック決定ツリー
costRules.ts	コスト計算ルール
lockoutPolicy.ts	モデルのロックアウト判定
tagRouter.ts	タグベースのルーティング
comboResolver.ts	リクエストからターゲットリストへのコンボ解決
connectionModelRules.ts	接続ごとのモデルフィルター
modelAvailability.ts	モデルの可用性チェック
degradation.ts	縮退モードへの遷移
providerExpiration.ts	期限切れアカウント／キーの検出
quotaCache.ts	キャッシュされたクォータ判定
responses.ts, omnirouteResponseMeta.ts	レスポンス形式のヘルパー
configAudit.ts	設定変更の監査
assessment/	モデル評価（RFC に準拠、一部実装済み）
types.ts	共有ドメイン型

3.4 src/server/ — サーバー専用

クライアントコンポーネントからはインポートできません。

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        ルートを公開用または管理用として分類
│   ├── assertAuth.ts      アサーションヘルパー
│   ├── context.ts         リクエストごとの認可コンテキスト
│   ├── headers.ts
│   ├── pipeline.ts        認可パイプライン
│   ├── policies/          具体的なポリシー
│   └── types.ts
└── cors/origins.ts        CORS オリジン許可リスト

3.5 src/shared/ — 安全に共有可能

用途別のサブディレクトリに分割されています:

• constants/ — providers.ts（Zod で検証されるプロバイダーカタログ）、models.ts、 modelSpecs.ts、modelCompat.ts、pricing.ts、cliTools.ts、 cliCompatProviders.ts、routingStrategies.ts、comboConfigMode.ts、 headers.ts、upstreamHeaders.ts（拒否リスト）、mcpScopes.ts、 errorCodes.ts、publicApiRoutes.ts、batch.ts、batchEndpoints.ts、 bodySize.ts、colors.ts、appConfig.ts、config.ts、 sidebarVisibility.ts、visionBridgeDefaults.ts。
• validation/ — schemas.ts（約80個の Zod スキーマ）、compressionConfigSchemas.ts、 providerSchema.ts、settingsSchemas.ts、helpers.ts。
• contracts/ — npm に公開されるパブリック API コントラクト。
• types/ — 共有 TS 型。
• utils/ — circuitBreaker.ts、apiAuth.ts、apiKey.ts、apiKeyPolicy.ts、 api.ts、classify429.ts、cliCompat.ts、clipboard.ts、cloud.ts、cn.ts、 cors.ts、featureFlags.ts、 fetchTimeout.ts、formatting.ts、inputSanitizer.ts、logger.ts、 machine.ts、machineId.ts、maskEmail.ts、modelCatalogSearch.ts、 nodeRuntimeSupport.ts、parseApiKeys.ts、providerHints.ts、 providerModelAliases.ts、rateLimiter.ts、releaseNotes.ts、 a11yAudit.ts、および services/、network/、 middleware/、schemas/、hooks/、components/ 配下のダッシュボード用フック／コンポーネント。

---

4. open-sse/ — ストリーミングエンジンワークスペース

@omniroute/open-sse として公開される独立した npm ワークスペース。リクエスト 処理、エグゼキューター、トランスレーター、サービス、トランスフォーマー、および MCP サーバーを管理します。

open-sse/
├── index.ts                公開エクスポート
├── package.json            ワークスペースマニフェスト
├── tsconfig.json
├── types.d.ts
├── config/                 プロバイダーレジストリ、ヘッダープロファイル、アイデンティティ、…
├── handlers/               リクエストハンドラー（チャット、埋め込み、音声、画像、…）
├── executors/              プロバイダー固有の HTTP エグゼキューター 108 個
├── translator/             フォーマット変換（OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro）
├── transformer/            Responses API ↔ Chat Completions ストリームトランスフォーマー
├── services/               80 以上のサービスモジュール（コンボ、フォールバック、クォータ、アイデンティティ、…）
├── utils/                  ストリーミングヘルパー、TLS クライアント、AWS SigV4、プロキシフェッチ、…
└── mcp-server/             MCP サーバー（3 つのトランスポート、33 のスコープ、110 のツール）

4.1 open-sse/handlers/

ハンドラー	目的
chatCore.ts	メインのチャットパイプライン（キャッシュ、レート制限、コンボルーティング、エグゼキューターへのディスパッチ）
responsesHandler.ts	OpenAI Responses API のエントリーポイント
embeddings.ts	埋め込み
imageGeneration.ts	画像生成
audioSpeech.ts	テキスト読み上げ
audioTranscription.ts	音声テキスト変換
videoGeneration.ts	動画生成
musicGeneration.ts	音楽生成
rerank.ts	再ランキング
moderations.ts	モデレーション
search.ts	Web 検索
sseParser.ts	SSE イベントパーサー
usageExtractor.ts	アップストリームのストリームからトークン数を抽出
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（レジストリ）。

注：ここに記載されていないプロバイダーは、汎用の OpenAI 互換エグゼキューターを使用する default.ts によって提供されます。完全なプロバイダーカタログ（355 プロバイダー）は src/shared/constants/providers.ts にあります。

4.3 open-sse/translator/

ハブ・アンド・スポーク型の変換（OpenAI がハブ）。

• 9 個のリクエストトランスレーター（translator/request/）： antigravity-to-openai, claude-to-gemini, claude-to-openai, gemini-to-openai, openai-responses, openai-to-claude, openai-to-cursor, openai-to-gemini, openai-to-kiro。
• 9 個のレスポンストランスレーター（translator/response/）： claude-to-openai, cursor-to-openai, gemini-to-claude, gemini-to-openai, kiro-to-openai, openai-responses, openai-to-antigravity, openai-to-claude。
• 9 個のヘルパー（translator/helpers/）： claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper、および ヘルパーテスト。
• 画像ヘルパー（translator/image/sizeMapper.ts）。
• トップレベル：bootstrap.ts, formats.ts, registry.ts, index.ts。

4.4 open-sse/transformer/

• responsesTransformer.ts — TransformStream ベースの Responses API ↔ Chat Completions コンバーター（responses/ ルートの包括的ハンドラーで使用）。

4.5 open-sse/services/

主な項目（完全な一覧は open-sse/services/ 配下）：

関心領域	ファイル
Combo ルーティング	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（クールダウン + ロックアウト）、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/ — 圧縮エンジン全体の配線
トークン + セッション	tokenRefresh.ts、sessionManager.ts、apiKeyRotator.ts、contextManager.ts、contextHandoff.ts、systemPrompt.ts、roleNormalizer.ts、responsesInputSanitizer.ts、toolSchemaSanitizer.ts、toolLimitDetector.ts、thinkingBudget.ts
ティア / マニフェスト	tierResolver.ts、tierConfig.ts、tierDefaults.json、tierTypes.ts、manifestAdapter.ts
IP / ネットワーク	ipFilter.ts、webSearchFallback.ts
バッチ	batchProcessor.ts
使用量	usage.ts

4.6 open-sse/mcp-server/

• server.ts に接続された 110 個の一意なツール（schemas/tools.ts 内の 45 個の正規ツール + メモリ、スキル、GitHub スキル、プール、ゲーミフィケーション、プラグイン、Notion、Obsidian、 ローカルコーパス、圧縮モジュール — countUniqueMcpTools により和集合をカウント）。
• 3 種類のトランスポート：stdio、HTTP Streamable、SSE。
• ランタイムで適用される 33 個のスコープ — 基本リストは src/shared/constants/mcpScopes.ts にあり、完全なセットは各ツールモジュールで宣言されたスコープの和集合です。
• 監査テーブル：mcp_tool_audit（audit.ts によりデータ投入）。
• ファイル：server.ts、index.ts、httpTransport.ts、audit.ts、scopeEnforcement.ts、 runtimeHeartbeat.ts、descriptionCompressor.ts、schemas/{tools, a2a, audit, index}.ts、 tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts、 および __tests__/ 配下のテスト。
• ツールカタログの全一覧については、MCP-SERVER.md を参照してください。

4.7 open-sse/config/

プロバイダーレジストリ（providerRegistry.ts、providerModels.ts、 providerHeaderProfiles.ts）、フォーマット別モデルレジストリ（audioRegistry.ts、 embeddingRegistry.ts、imageRegistry.ts、moderationRegistry.ts、 musicRegistry.ts、rerankRegistry.ts、searchRegistry.ts、videoRegistry.ts）、 アイデンティティヘルパー（codexIdentity.ts、codexInstructions.ts、 anthropicHeaders.ts、antigravityUpstream.ts、antigravityModelAliases.ts、 cliFingerprints.ts、toolCloaking.ts、defaultThinkingSignature.ts）、 認証情報ヘルパー（credentialLoader.ts、codexClient.ts）、およびクラウド アダプター（azureAi.ts、bedrock.ts、datarobot.ts、glmProvider.ts、 maritalk.ts、oci.ts、petals.ts、runway.ts、sap.ts、watsonx.ts、 ollamaModels.ts、errorConfig.ts、constants.ts、registryUtils.ts）。

4.8 open-sse/utils/

ストリーミングプリミティブとプロバイダーヘルパー：stream.ts、streamHandler.ts、 streamHelpers.ts、streamPayloadCollector.ts、streamReadiness.ts、 sseHeartbeat.ts、proxyFetch.ts、proxyDispatcher.ts、tlsClient.ts、 networkProxy.ts、awsSigV4.ts、cacheControlPolicy.ts、 cursorChecksum.ts、cursorAgentProtobuf.ts、cursorVersionDetector.ts、 comfyuiClient.ts、kieTask.ts、bypassHandler.ts、aiSdkCompat.ts、 thinkTagParser.ts、urlSanitize.ts、usageTracking.ts、requestLogger.ts、 progressTracker.ts、cors.ts、error.ts、logger.ts、sleep.ts、 ollamaTransform.ts。

---

5. electron/ — デスクトップラッパー

electron/
├── main.js                  Electron メインプロセス
├── preload.js               プリロードブリッジ（contextIsolation 有効）
├── types.d.ts
├── package.json             electron-builder の設定、バージョン 3.8.51
├── README.md
├── assets/                  ビルド用リソース（アイコン、エンタイトルメントなど）
├── node_modules/            専用の node_modules（better-sqlite3、electron-updater）
└── dist-electron/           ビルド出力（コミット対象外）

ワークスペースルートには、electron:dev、electron:build、 electron:build:{win,mac,linux}、electron:smoke:packaged の5つの npm スクリプトがあります。自動更新には、 GitHub のリリースフィードを参照する electron-updater を使用します。

---

6. bin/ — CLI

bin/
├── omniroute.mjs           メインの CLI エントリ（Node ESM）
├── reset-password.mjs      CLI から管理パスワードをリセット
├── mcp-server.mjs          MCP サーバーランチャー（stdio）
├── nodeRuntimeSupport.mjs  Node バージョンガード
└── cli/
    ├── program.mjs         Commander プログラムビルダー
    ├── runtime.mjs         withRuntime ヘルパー（サーバー優先／DB フォールバック）
    ├── output.mjs          出力フォーマッター（json/jsonl/table/csv）
    ├── i18n.mjs            ロケール対応の t() ヘルパー
    ├── api.mjs             API fetch ヘルパー
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    コマンド登録
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             （コマンド／グループごとに1ファイル）

package.json → bin では、2つのバイナリが公開されています。

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

---

7. tests/

ディレクトリ	種類
tests/unit/	Node ネイティブテストランナーによる単体テスト（1821ファイルに加え、api/、auth/、authz/ サブディレクトリ）
tests/integration/	モジュール横断および DB 状態のテスト
tests/e2e/	Playwright UI テスト
tests/e2e/protocol-clients.test.ts	MCP/A2A プロトコルの E2E テスト
tests/translator/	トランスレーター固有のテスト
tests/security/	セキュリティのリグレッションテスト
tests/load/	負荷／ストレステスト
tests/golden-set/	トランスレーターのリグレッション用参照出力
tests/helpers/, tests/fixtures/, tests/manual/	サポート

よく使用するコマンド：

コマンド	実行内容
npm run test:unit	Node テストランナーですべての tests/unit/*.test.ts を実行（並行数10）
npm run test:vitest	Vitest スイート（MCP、autoCombo、キャッシュ）
npm run test:e2e	Playwright UI スイート
npm run test:protocols:e2e	MCP + A2A プロトコルの E2E テスト
npm run test:coverage	カバレッジゲート（行／ステートメント／関数／分岐が60%以上）
node --import tsx/esm --test tests/unit/<file>.test.ts	単一ファイルの実行

---

8. scripts/

用途別に6つのサブフォルダーに整理されています。

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

---

9. リクエストパイプライン（概要）

ソース: diagrams/request-pipeline.mmd

クライアントリクエスト
  → /v1/chat/completions (route.ts)
     CORSプリフライトチェック
     Zodバリデーション（shared/validation/schemas.tsのchatCompletionsSchema）
     認証（extractApiKey + isValidApiKey、またはrequireManagementAuth）
     ポリシーエンジン（src/server/authz/pipeline.ts）
     ガードレール（PIIマスカー、プロンプトインジェクション、ビジョンブリッジ）
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     キャッシュチェック（セマンティックキャッシュ + 読み取りキャッシュ）
     レート制限（rateLimitManager、accountSemaphore）
     コンボルーティング（モデルがコンボとして解決される場合）
       comboResolver → ターゲットごとのループ → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       アップストリームをfetch → accountFallbackによる再試行／バックオフ
     translateResponse() (open-sse/translator/response/*)
     SSEストリームまたはJSONレスポンス
     Responses APIの場合: open-sse/transformer/responsesTransformer.tsを介したTransformStream
  → コンプライアンス監査（src/lib/compliance/）
  → クライアントへのレスポンス

レジリエンスのランタイム状態（3つのメカニズム）

メカニズム	スコープ	場所
プロバイダーサーキットブレーカー	プロバイダー全体	src/shared/utils/circuitBreaker.ts、domain_circuit_breakersに永続化
接続クールダウン	1つのアカウント／キー	src/sse/services/auth.tsのmarkAccountUnavailable()。accountFallback.checkFallbackError()が使用
モデルロックアウト	プロバイダー + 接続 + モデル	open-sse/services/accountFallback.ts、domain_lockout_stateに永続化

RESILIENCE_GUIDE.mdおよび CLAUDE.mdの専用セクションを参照してください。

---

10. コントリビューション方法

新しいプロバイダーを追加する

1. src/shared/constants/providers.ts に登録します（読み込み時に Zod で検証されます）。
2. カスタムロジックが必要な場合は、open-sse/executors/ に executor を追加します （BaseExecutor を継承します）。
3. OpenAI 形式に対応していない場合は、open-sse/translator/ に translator を追加します。
4. OAuth ベースの場合は、src/lib/oauth/providers/ および src/lib/oauth/services/ 配下に設定を追加します。
5. open-sse/config/providerRegistry.ts（または open-sse/config/ 配下の形式固有の registry）にモデルを登録します。
6. tests/unit/ 配下にテストを作成します。

新しい API ルートを追加する

1. src/app/api/your-route/route.ts を作成します。
2. CORS → Zod によるリクエストボディの検証 → 認証 → handler への委譲、というパターンに従います。
3. 新しいリクエスト形式の場合は、Zod スキーマを src/shared/validation/schemas.ts に追加します。
4. 管理専用の場合は、パスを src/shared/constants/publicApiRoutes.ts （公開 API サーフェス用の denylist）に追加します。
5. tests/unit/ 配下にテストを追加します。
6. docs/reference/API_REFERENCE.md と docs/openapi.yaml を更新します。

新しい DB モジュールを追加する

1. src/lib/db/yourModule.ts を作成し、./core.ts から getDbInstance() をインポートします。
2. 対象ドメインの CRUD 関数をエクスポートします。
3. 新しいテーブルを追加する場合は、src/lib/db/migrations/ 配下に、連番で、 冪等かつトランザクショナルな migration を追加します。
4. インポート側では @/lib/db/yourModule から直接インポートします（barrel は使用しません。旧 localDb.ts の再エクスポート層は削除されています）。
5. tests/unit/ 配下にテストを追加します。

新しい MCP ツールを追加する

1. open-sse/mcp-server/tools/ 配下にツール定義を追加します（または open-sse/mcp-server/schemas/tools.ts を拡張します）。
2. src/shared/constants/mcpScopes.ts で適切な scope を割り当てます。
3. open-sse/mcp-server/server.ts にツールを登録します。
4. open-sse/mcp-server/__tests__/ 配下にテストを追加します。
5. MCP-SERVER.md を更新します。

新しい A2A スキルを追加する

A2A-SERVER.md § 新しいスキルの追加を参照してください。スキルは src/lib/a2a/skills/ に配置し、A2A タスクマネージャーを通じて登録します。

---

11. 規約

• コードスタイル: 2 スペースのインデント、ダブルクォート、100 文字幅、セミコロン、 es5 の trailing comma — lint-staged を介して Prettier により強制されます。
• インポート: 外部 → 内部（@/、@omniroute/open-sse）→ 相対。
• 命名: ファイルは camelCase または kebab-case、コンポーネントは PascalCase、 定数は UPPER_SNAKE。
• ESLint: no-eval、no-implied-eval、no-new-func は全体で error。 no-explicit-any は open-sse/ と tests/ では warn、それ以外では error。
• TypeScript: strict: false（レガシーな方針）。モジュール間の境界では、 型推論より明示的な型を優先します。
• データベース: ルートや handler に生の SQL を記述せず、必ず src/lib/db/ モジュールを経由します。barrel import は行わず、特定の src/lib/db/* モジュールを直接使用します。
• DB エンティティの型付け（#3512）: DB テーブルの行形式を読み書きする関数は、 呼び出し箇所で any やインラインの匿名型を使用するのではなく、そのテーブルの カラムを 1:1 で反映した名前付きの TS interface を引数または戻り値として使用する必要があります。 interface は関数の近くに配置します（例: src/lib/usage/usageHistory.ts の saveRequestUsage の上にある export interface UsageEntry）。複数の書き込み元が 行を段階的に設定する場合は、個々のフィールドを optional/nullable に保ちます。 呼び出し元によって形式が異なるフィールドには any より unknown を優先し、 その旨をフィールド上に記載します（例: UsageEntry.tokens はプロバイダー固有の 生の usage と正規化済みの形式の両方を受け入れます）。この方法でファイル内の any がゼロになったら、リグレッションを防止するために check:any-budget:t11 の allowlist（scripts/check/check-t11-any-budget.mjs、 maxAny: 0）へ追加します。これは最初の段階における規約です。より広範な 「匿名 any の禁止」対応は、コードベースの残りの部分に対して段階的に進めます。
• エラー: 具体的なエラー型を指定した try/catch を使用し、pino のコンテキスト付きでログを記録します。 SSE ストリーム内のエラーを暗黙に握りつぶさず、クリーンアップには abort signal を使用します。
• セキュリティ: eval() / new Function() / implied eval は絶対に使用しません。 すべての入力を Zod で検証します。保存時の認証情報を暗号化します（AES-256-GCM）。 src/shared/constants/upstreamHeaders.ts の denylist を サニタイズ／検証レイヤーと一致させます。
• コミット: Conventional Commits — feat(scope): subject。許可される scope: db、sse、oauth、dashboard、api、cli、docker、ci、mcp、 a2a、memory、skills。
• ブランチ: prefix は feat/、fix/、refactor/、docs/、test/、 chore/。main へ直接コミットしてはいけません。
• Husky: pre-commit では lint-staged + check:docs-sync + check:any-budget:t11 を実行します。pre-push では check:any-budget:t11 + check:tracked-artifacts を実行します（高速な gate。test:unit は除外されます）。

---

12. 厳守事項（CLAUDE.md より）

1. シークレットや認証情報は絶対にコミットしないこと。
2. バレルインポートは絶対に使用せず、特定の src/lib/db/* モジュールを直接使用すること。
3. eval() / new Function() / 暗黙的な eval は絶対に使用しないこと。
4. main に直接コミットしないこと。
5. ルート内に生の SQL を絶対に記述せず、必ず src/lib/db/ モジュールを経由すること。
6. SSE ストリーム内のエラーを通知せずに握りつぶさないこと。
7. 入力は必ず Zod スキーマで検証すること。
8. 本番コードを変更する際は、必ずテストを含めること。
9. カバレッジ（ステートメント、行、関数、分岐）は 60% 以上を維持すること。

---

13. 関連項目

• ARCHITECTURE.md — 上位レベルのアーキテクチャとモジュールの 責務。
• API_REFERENCE.md — パブリック API および管理 API のリファレンス。
• FEATURES.md — 機能マトリックスとバージョンごとの主要な変更点。
• RESILIENCE_GUIDE.md — サーキットブレーカー、クールダウン、 ロックアウトの詳細解説。
• AUTO-COMBO.md — Auto Combo のスコアリングと戦略。
• MCP-SERVER.md — MCP ツールの完全なカタログとトランスポート。
• 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 — エージェントが使用する、より詳細なアーキテクチャリファレンス。