メインプロセス設計

メインプロセスは Elftia の中核であり、すべてのビジネスロジック、外部 API 呼び出し、データベース操作、セキュリティ制御を担当します。エントリーファイルは packages/desktop/app/main/index.ts です。

サービスモジュール概要

メインプロセスには 45 個以上のサービスモジュールが含まれており、packages/desktop/app/main/services/ 配下で機能ドメインごとに整理されています。

graph LR
    subgraph "Core Infrastructure"
        Core[core/]
        Config[config/]
        Settings[settings/]
    end

    subgraph "Auth & Accounts"
        Auth[auth/]
        Account[account/]
        OAuth[oauth/]
    end

    subgraph "AI Engines"
        Engine[engine/]
        Completion[completion/]
        LLM[llm/]
        Prompt[prompt/]
    end

    subgraph "Agent Orchestration"
        Magi[magi/]
        Agent[agent/]
        Plugin[plugin/]
    end

    subgraph "Messaging Channels"
        Channel[channel/]
        Security[security/]
    end

    subgraph "Media & Content"
        Media[media/]
        Project[project/]
        Search[search/]
    end

    Core --> Engine
    Core --> Channel
    Engine --> Magi
    LLM --> Completion
    Completion --> Engine
    Magi --> Agent
    Channel --> Security

ドメイン別サービス一覧

Domain	Service	Description
Core (core/)	`LoggerService`	Winston + daily-rotate-file によるロギング
	`AppPaths`	アプリケーションパスの解決（userData、dbPath、configDir など）
	`RuntimeService`	ランタイム情報（バージョン、チャネル、プラットフォーム）
	`CacheService`	汎用キャッシュ（TTL 期限切れクリーンアップ）
	`ConfigManager`	設定ファイル管理
	`SecurityService`	AES-256-GCM 暗号化サービス
	`CryptoService`	PBKDF2 鍵導出 + 暗号化/復号
	`PerformanceMonitor`	パフォーマンス監視とアラート
	`ErrorHandler`	グローバルエラー処理
	`PluginManager`	プラグインライフサイクル管理
	`DatabaseOptimizer`	SQLite 最適化（VACUUM、ANALYZE）
	`CommandService`	コマンド実行サービス
Auth (auth/)	`AuthService`	IPC 認証トークン検証
	`AuthSessionService`	ログインセッション + Deep Link 処理
	`AuthTokenStore`	認証トークンの永続化
	`TokenRefreshService`	認証トークンの自動更新
Account (account/)	`AccountService`	ユーザー認証情報管理
	`AccountTokensService`	OAuth トークン管理
	`LimitsService`	メンバーシップ制限チェック
LLM (llm/)	`LLMConfigService`	プロバイダー/モデル設定 CRUD
	`TransformerService`	リクエスト形式変換チェーン
Completion (completion/)	`CompletionService`	LLM API 呼び出しのエントリーポイント
	`ApiKeyPoolService`	複数キーのラウンドロビン + セッションアフィニティ
Engine (engine/)	`EngineDispatcher`	エンジン登録とルーティング
	`ApiEngine`	メディア API エンジン
	`ChatEngine`	汎用チャットエンジン
	`ClaudeSdkEngine`	Claude Agent SDK エンジン
	`TinyElfEngine`	組み込み Agent エンジン
	`CliRunnerEngine`	CLI サブプロセスエンジン
	`STChatEngine`	RP チャットパイプラインエンジン
Magi Orchestration (magi/)	`MagiService`	コアメッセージ処理サービス（Clawia の MCP セットを `services/capabilities/tools/mcp-builtin/` レジストリ経由で収集する `assembleMagiMcps` を含む。`buildTinyElfDirectMcpServers` は TinyElf のエントリーポイント）
	`MagiSessionService`	セッション永続化管理
	`MagiWorkspaceService`	ワークスペースディレクトリ管理
	`MagiSdkOptionsBuilder`	プロンプト構築（V1-V4）+ ユーザー MCP 注入（`setUserMcpServers` / `getMcpServers(allowedUserMcpNames)` / `getDirectMcpServers`）+ Channel プローブ。組み込み MCP アセンブリは Phase 5.9 以降 `mcp-providers/` に移行済み
	`AgentOrchestrator`	Agent ディスパッチとオーケストレーション
	`AgentDiscovery`	スケジュール可能な Agent 名簿
	`MessageRouter`	デュアルモードメッセージルーティング
	`ChannelMagiBridge`	Channel から Magi へのブリッジ
	`SessionEventBus`	セッションイベントバス
	`SessionDispatcherImpl`	クロスセッションディスパッチ実装
	`SubagentRegistry`	サブエージェント状態追跡
Built-in MCP Registry (mcp-providers/)	`McpProviderRegistry`	12 個の組み込みプロバイダー + 動的 ScriptPlugin プロバイダーファクトリ。すべての組み込み MCP ハンドラーはインプロセスで実行されます。SDK は直接呼び出し、TinyElf は ITool として登録し、CLI は中央の `BuiltinMcpHttpServer` HTTP ブリッジ経由でアクセスします。`DispatchServer` / `ChannelServer` / `VisionAssistServer` HTTP ブリッジは `cleanup-legacy-mcp`（2026-05-19）で削除されました
	`BuiltinMcpHttpServer`	中央 HTTP MCP ブリッジ（セッション単位スコープ）。すべてのインプロセス MCP はこれを通じて CLI エンジンに公開されます
	`assembleMcpForSession(ctx)`	統一アセンブリエントリー（SDK + TinyElf。`sdkServers` / `tinyElfServers` / `promptFragments` / `allowedTools` / `cleanups` を含む `McpAssembly` を返します）
	`applyAssembly.ts`	`applyAssemblyToSdkOptions` / `applyAssemblyToTinyElfConfig` — `McpAssembly` をエンジンオプションにマージします
	`contextBuilders.ts`	`buildAssemblyContextFor{Clawia,Agent}` — 呼び出し元の視点から `AssemblyContext` を構築します
	`registerBuiltinMcpProviders.ts`	1 回限りの起動時アセンブリポイント（ScriptPlugin の同名エイリアス処理を含む）
	`builtin/<Name>Provider.ts`	組み込み MCP ごとに 1 つの Provider モジュール（12 個の静的 + 動的 ScriptPlugin ファクトリ）
Channel (channel/)	`ChannelPluginLoader`	プラグインの検出と読み込み
	`ChannelPluginRegistry`	プラグイン登録とインスタンス管理
	`ChannelMessageRouter`	メッセージトリガールーティング
	`ChannelMarketplaceService`	プラグインマーケットプレイス
Security (security/)	`ExecutionFirewall`	ファイルパスファイアウォール
	`GuardianAgent`	AI ツール呼び出しレビュー
	`PromptGuardian`	プロンプトインジェクション検出
	`RateLimiter`	レート制限
	`InputSanitizer`	入力サニタイズ
	`UserPermissionService`	ユーザー権限管理
	`ChannelPermissionGate`	Channel 権限確認
	`AuditLogger`	セキュリティ監査ログ
Media (media/)	`ImageGenerationService`	画像生成
	`MusicGenerationService`	音楽生成
	`MediaStorageService`	メディアファイルストレージ
	`MediaResourceService`	コンテンツアドレス指定リソースストレージ
	`MediaConfigService`	メディアプロバイダー設定
	`AsrService` / `TtsService`	音声認識/合成
Project (project/)	`ProjectService`	プロジェクト CRUD
	`FileIndexService`	ファイルインデックスサービス
	`GitService`	Git 操作
Search (search/)	`WebSearchService`	統一検索エントリーポイント
	`JinaProvider` / `TavilyProvider` / `SearxngProvider`	検索エンジンアダプター
UI (ui/)	`ThemeService`	テーマ管理
	`WindowControlsService`	ウィンドウコントロール
	`TrayService`	システムトレイ
	`NotificationService`	デスクトップ通知
Config (config/)	`ConfigStore`	electron-store + fs.watch ホットリロード
Cron (cron/)	`CronService`	Cron スケジュールタスクのディスパッチ
MCP (mcp/)	`McpService`	MCP サーバー管理
Plugins (plugin/)	`ScriptPluginLoader`	スクリプトプラグイン読み込み
	`ScriptPluginRegistry`	スクリプトプラグインレジストリ
	`ScriptPluginBridgeManager`	プラグインブリッジ管理

IPC Router アーキテクチャ

フロントエンドからバックエンドへのすべての通信は IPC Router レイヤーを経由します。現在 68 個以上のルーターモジュールが登録されています。

secureHandle パターン

各 IPC チャネルは secureHandle でラップされ、認証トークン検証が強制されます。

{/* packages/desktop/app/main/ipc/safe-handle.ts */}
function secureHandle(
  channel: string,
  handler: (event: IpcMainInvokeEvent, params: unknown) => Promise<unknown>,
  validateToken: (token: string) => boolean,
): void;

フロー:

sequenceDiagram
    participant R as Renderer
    participant P as Preload
    participant S as secureHandle
    participant H as Router Handler

    R->>P: window.api.someMethod(params)
    P->>S: ipcRenderer.invoke(channel, {token, ...params})
    S->>S: validateToken(token)
    alt token invalid
        S-->>P: throw AuthError
    else token valid
        S->>H: handler(event, params)
        H-->>S: result
        S-->>P: result
        P-->>R: result
    end

ルート登録

すべてのルートは registerAllRouters() に一元登録されます。各 Router クラスは BaseRouter を継承し、register() メソッドでチャネルを登録します。

{/* Simplified Router structure */}
class SomeRouter extends BaseRouter {
  register() {
    secureHandle('domain:action', async (_event, params) => {
      const validated = SomeSchema.parse(params);
      return this.service.doSomething(validated);
    }, this.validate);
  }
}

ルートカテゴリと件数

Router Directory/File	Channel Prefix	Main Channel Count
`auth/`	`auth:*`	5+
`account/`	`accounts:`, `accountTokens:`	8+
`session/`	`sessions:`, `sessionOrganizer:`	10+
`chat/`	`chatMessages:`, `chatAssistants:`, `chatControl:`, `mediaSession:`	15+
`completion/`	`completion:*`	5+
`capabilities/llm/`	`llmProviders:`, `llmModels:`, `apiKeys:`, `transformers:`	15+
`project/`	`projects:`, `files:`, `git:*`	10+
`media/`	`media:`, `imageProviders:`, `musicProviders:`, `videoProviders:`, `asr:`, `tts:`	20+
`settings/`	`settings:`, `appPreferences:`	8+
`ui/`	`theme:`, `window:`	6+
`MagiRouter`	`magi:*`	10+
`ChannelPluginRouter`	`channels:*`	8+
`sillytavern/`	`characterCards:`, `worldInfo:`, `regexScripts:`, `groupChat:`, etc.	25+
Others	`mcp:`, `webSearch:`, `todo:`, `tasks:`, `notes:`, `tags:`, `cron:`, `elfi:`, etc.	30+

Worker スレッドパターン

時間のかかる I/O 操作は、メインスレッドをブロックしないように Worker Threads で実行されます。

DbClient — データベース Worker

DbClient は最も重要な Worker であり、SQLite データベースとのすべてのやり取りをカプセル化します。

sequenceDiagram
    participant S as Service
    participant C as DbClient
    participant W as db.worker.ts
    participant D as SQLite (WAL)

    S->>C: db.someMethod(params)
    C->>C: seq++, create Promise
    C->>W: postMessage({id: seq, method, params})
    W->>D: Execute SQL query
    D-->>W: Result
    W-->>C: postMessage({id: seq, result})
    C->>C: resolve(pending[seq])
    C-->>S: Promise<result>

{/* Simplified DbClient RPC pattern */}
class DbClient extends EventEmitter implements DbRpc {
  private worker: Worker;
  private seq = 0;
  private pending = Map<number, {resolve, reject}>;

  async send(method: string, params: unknown): Promise<unknown> {
    const id = ++this.seq;
    return new Promise((resolve, reject) => {
      this.pending.set(id, { resolve, reject });
      this.worker.postMessage({ id, method, params });
    });
  }

  async ready(): Promise<void>;
}

主要な設計ポイント:

Async RPC: 各呼び出しには一意のシーケンス番号が割り当てられ、リクエストは postMessage で送信されます
Ready wait: await db.ready() により、Worker の初期化（スキーマ作成）が完了してから使用することを保証します
Error forwarding: Worker エラーは EventEmitter を通じて上位へ伝播します

Worker スレッド一覧

Worker File	Purpose	Communication
`db.worker.ts`	SQLite データベースの読み書き（100 個以上の RPC メソッド）	DbClient RPC
`fileSearch.worker.ts`	ファイル検索（あいまい一致）	MessagePort
`fileWatcher.worker.ts`	ファイルシステム監視（chokidar）	MessagePort
`mcp.worker.ts`	MCP サーバープロセス管理	MessagePort
`diagnostics.worker.ts`	システム診断データ収集	MessagePort
`project.worker.ts`	プロジェクトファイルインデックス構築	MessagePort
`fileSnapshot.worker.ts`	ファイルスナップショット差分	MessagePort

主要インフラストラクチャ

LoggerService

Winston をベースにしており、ログレベルのフィルタリングとログファイルの自動ローテーションをサポートします。

{/* Simplified LoggerService interface */}
class LoggerService {
  info(message: string, meta?: Record<string, unknown>): void;
  warn(message: string, err?: Error, meta?: Record<string, unknown>): void;
  error(message: string, err?: unknown, meta?: Record<string, unknown>): void;
  debug(message: string, meta?: Record<string, unknown>): void;
}

ログの場所: {userData}/logs/
ローテーションポリシー: daily-rotate-file、14 日間保持
形式: JSON + timestamp

SecurityService / CryptoService

{/* Core encryption service interface */}
class SecurityService {
  encrypt(plaintext: string): string;
  decrypt(ciphertext: string): string;
}

class CryptoService {
  deriveKey(password: string, salt: Buffer): Buffer;
  encrypt(data: string, key: Buffer): EncryptedData;
  decrypt(data: EncryptedData, key: Buffer): string;
}

AppPaths

すべてのアプリケーションディレクトリパスを一元管理します。

Property	Path	Purpose
`userData`	`{appData}/elftia/`	アプリケーションデータルート
`dbPath`	`{userData}/elftia.db`	SQLite データベース
`configDir`	`{userData}/config/`	設定ファイルディレクトリ
`resourcesDir`	`{userData}/resources/`	メディアリソース
`diagnosticsDir`	`{userData}/diagnostics/`	診断データ
`logsDir`	`{userData}/logs/`	ログファイル

File	Description
`packages/desktop/app/main/index.ts`	メインプロセスのエントリー。すべてのサービスの作成と起動
`packages/desktop/app/main/services/routers/index.ts`	ルート登録センター、`registerAllRouters()`
`packages/desktop/app/main/services/routers/BaseRouter.ts`	Router ベースクラス
`packages/desktop/app/main/ipc/safe-handle.ts`	`secureHandle` IPC セキュリティラッパー
`packages/desktop/app/main/workers/DbClient.ts`	データベース Worker クライアント
`packages/desktop/app/main/workers/db.worker.ts`	データベース Worker 実装
`packages/desktop/app/main/workers/types.ts`	Worker RPC 型定義
`packages/desktop/app/main/services/infra/logger/LoggerService.ts`	ロギングサービス
`packages/desktop/app/main/services/platform/security/SecurityService.ts`	暗号化サービス
`packages/desktop/app/main/services/infra/paths/paths.ts`	パス管理
`packages/desktop/app/main/services/agent-core/engine/EngineDispatcher.ts`	エンジンディスパッチャー

サービスモジュール概要​

ドメイン別サービス一覧​

IPC Router アーキテクチャ​

secureHandle パターン​

ルート登録​

ルートカテゴリと件数​

Worker スレッドパターン​

DbClient — データベース Worker​

Worker スレッド一覧​

主要インフラストラクチャ​

LoggerService​

SecurityService / CryptoService​

AppPaths​

関連ファイル​