architecture

アーキテクチャ スキル

Electron のマルチプロセス プロジェクトにおいて、ファイルの正しい配置と構造を決定します。

詳細リファレンス

• レンダラー層（コンポーネント、フック、ユーティリティ、ページ、CSS）: references/renderer.md
• メインプロセスと共有層（ブリッジ、サービス、ワーカー、プリロード）: references/process.md
• プロジェクトルートとモノレポのレイアウト（ディレクトリ構造、移行状況）: references/project-layout.md

---

判断ツリー — 新しいコードはどこに置くか

Is it UI (React components, hooks, pages)?
  └── YES → packages/desktop/src/renderer/              → see references/renderer.md

Is it an IPC handler responding to renderer calls?
  └── YES → packages/desktop/src/process/bridge/        → see references/process.md

Is it business logic running in the main process?
  └── YES → packages/desktop/src/process/services/      → see references/process.md

Is it an AI platform connection (API client, message protocol)?
  └── YES → packages/desktop/src/process/agent/<platform>/

Is it a background task that runs in a worker thread?
  └── YES → packages/desktop/src/process/worker/

Is it used by BOTH main and renderer processes?
  └── YES → packages/desktop/src/common/

Is it an HTTP/WebSocket endpoint?
  └── YES → packages/desktop/src/process/webserver/

Is it a plugin/extension resolver or loader?
  └── YES → packages/desktop/src/process/extensions/

Is it a messaging channel (Lark, DingTalk, Telegram)?
  └── YES → packages/desktop/src/process/channels/

---

プロセス境界のルール

厳格なルールです。違反するとランタイムクラッシュの原因になります。

プロセス	使用可能	使用不可
メイン (packages/desktop/src/process/)	Node.js、Electron メイン API、fs、path、child_process	DOM API（document、window、React）
レンダラー (packages/desktop/src/renderer/)	DOM API、React、ブラウザー API	Node.js API（fs、path）、Electron メイン API
ワーカー (packages/desktop/src/process/worker/)	Node.js API	DOM API、Electron API
プリロード (packages/desktop/src/preload/)	contextBridge、ipcRenderer	DOM 操作、Node.js の fs

プロセス間通信:

• メイン ↔ レンダラー: packages/desktop/src/preload/ + packages/desktop/src/process/bridge/*.ts を経由した IPC
• メイン ↔ ワーカー: packages/desktop/src/process/worker/WorkerProtocol.ts を経由した fork プロトコル

// NEVER in renderer
import { something } from '@process/services/foo'; // crashes at runtime

// Use IPC instead
const result = await window.api.someMethod(); // goes through preload

---

命名規則

ディレクトリ

対象	規則	理由
レンダラー のコンポーネント/モジュールのディレクトリ	PascalCase	React の慣例 — ディレクトリ名 = コンポーネント名
それ以外すべて	lowercase	Node.js の慣例
カテゴリ別ディレクトリ（全体）	lowercase	components/、hooks/、utils/、services/
プラットフォーム別ディレクトリ（全体）	lowercase	acp/、codex/、gemini/ — プロセス間での一貫性

簡易判定: 「packages/desktop/src/renderer/ の内側にあり、かつ特定のコンポーネント/機能を表す（カテゴリではない）か？」→ PascalCase。それ以外 → lowercase。

ファイル

内容	規則	例
React コンポーネント、クラス	PascalCase	SettingsModal.tsx、CronService.ts
フック	use プレフィックスの camelCase	useTheme.ts、useCronJobs.ts
ユーティリティ、ヘルパー	camelCase	formatDate.ts、cronUtils.ts
エントリポイント	index.ts / index.tsx	ディレクトリベースのモジュールで必須
設定、型、定数	camelCase	types.ts、constants.ts
スタイル	kebab-case または Name.module.css	chat-layout.css

---

構造ルール

1. ディレクトリのサイズ上限: 直下の子は最大 10 個までとします。上限に近づいたら、責務ごとにサブディレクトリへ分割してください。
2. 単一ファイルのディレクトリは禁止: 親ディレクトリまたは関連するディレクトリにマージしてください。
3. 単一ファイルかディレクトリか: コンポーネントに非公開のサブコンポーネントやフックが必要になったら、index.tsx を持つディレクトリに変換してください。
4. まずはページ専用に: コードは pages/<PageName>/ に置くことから始めます。2 番目の利用箇所が現れた時点で初めて共有化してください。

テストファイルの対応

テストは tests/ 配下のサブディレクトリで、ソースファイルと対応する構成になります。

ソース	テスト
packages/desktop/src/process/services/CronService.ts	tests/unit/cronService.test.ts
packages/desktop/src/renderer/hooks/ui/useAutoScroll.ts	tests/unit/useAutoScroll.dom.test.ts
packages/desktop/src/process/extensions/ExtensionLoader.ts	tests/unit/extensions/extensionLoader.test.ts

tests/unit/ の直下の子が 10 個を超えた場合は、ソースの構成に合わせたサブディレクトリにまとめてください。

---

クイックチェックリスト

• コードが正しいプロセスのディレクトリにある（プロセス間の import がない）
• レンダラーのコードが Node.js API を使用していない
• メインプロセスのコードが DOM API を使用していない
• 新しい IPC チャネルが preload.ts を経由して橋渡しされている
• レンダラーのコンポーネント/モジュールのディレクトリは PascalCase、カテゴリ別のディレクトリは lowercase を使用している
• プラットフォーム用のディレクトリはすべて lowercase を使用している
• ディレクトリ単位のモジュールが index.tsx / index.ts のエントリポイントを持っている
• ページ専用のコードが pages/<PageName>/ 以下にあり、共有ディレクトリに置かれていない
• 単一ファイルのディレクトリがない
• どのディレクトリも直下の子が 10 個を超えていない
• 新しいソースファイルはカバレッジに自動的に含まれる。vitest.config.ts → coverage.exclude で誤って除外されていないか確認してください
• 新しいサービスでは、純粋なロジックと IO を分離している