Architecture Skill

Determine correct file placement and structure for an Electron multi-process project.

Detailed References

• Renderer layer (components, hooks, utils, pages, CSS): references/renderer.md
• Main process & shared layer (bridges, services, worker, preload): references/process.md
• Project root & src/ layout (directory structure, migration status): references/project-layout.md

Decision Tree — Where Does New Code Go?

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

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

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

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

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

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

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

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

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

Process Boundary Rules

Hard rules — violating them causes runtime crashes.

src/process/

fs

path

child_process

document

window

src/renderer/

fs

path

src/process/worker/

src/preload.ts

contextBridge

ipcRenderer

fs

Cross-process communication:

• Main ↔ Renderer: IPC via

  src/preload.ts

  +

  src/process/bridge/*.ts

• Main ↔ Worker: fork protocol via

  src/process/worker/WorkerProtocol.ts

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

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

Naming Conventions

Directories

components/

hooks/

utils/

services/

acp/

codex/

gemini/

Quick test: "Inside

src/renderer/

AND represents a specific component/feature (not a category)?" → PascalCase. Otherwise → lowercase.

Files

SettingsModal.tsx

CronService.ts

use

useTheme.ts

useCronJobs.ts

formatDate.ts

cronUtils.ts

index.ts

index.tsx

types.ts

constants.ts

Name.module.css

chat-layout.css

Structural Rules

1. Directory size limit: Max 10 direct children. Split into subdirectories by responsibility when approaching.
2. No single-file directories: Merge into parent or related directory.
3. Single file vs directory: If a component needs a private sub-component or hook, convert to a directory with

   index.tsx

   .
4. Page-private first: Start code in

   pages/<PageName>/

   . Promote to shared only when a second consumer appears.

Test File Mapping

Tests mirror source files in

tests/

src/process/services/CronService.ts

tests/unit/cronService.test.ts

src/renderer/hooks/ui/useAutoScroll.ts

tests/unit/useAutoScroll.dom.test.ts

src/process/extensions/ExtensionLoader.ts

tests/unit/extensions/extensionLoader.test.ts

When

tests/unit/

Quick Checklist

• Code is in the correct process directory (no cross-process imports)
• Renderer code does not use Node.js APIs
• Main process code does not use DOM APIs
• New IPC channels are bridged through

  preload.ts

• Renderer component/module dirs use PascalCase; categorical dirs use lowercase
• Platform dirs use lowercase everywhere
• Directory-based modules have

  index.tsx

  /

  index.ts

  entry point
• Page-private code is under

  pages/<PageName>/

  , not in shared dirs
• No single-file directories
• No directory exceeds 10 direct children
• New source files are auto-included in coverage — verify they are not accidentally excluded in

  vitest.config.ts

  →

  coverage.exclude

• New services separate pure logic from IO