architecture

name architecture description Project architecture and file structure conventions for all process types. Use when: (1) Creating new files or modules, (2) Deciding where code should go, (3) Converting single-file components to directories, (4) Reviewing code for structure compliance, (5) Adding new bridges, services, agents, or workers. 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 & monorepo layout (directory structure, migration status): references/project-layout.md Decision Tree — Where Does New Code Go? 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/ Process Boundary Rules Hard rules — violating them causes runtime crashes. Process Can use Cannot use Main ( packages/desktop/src/process/ ) Node.js, Electron main APIs, fs , path , child_process DOM APIs ( document , window , React) Renderer ( packages/desktop/src/renderer/ ) DOM APIs, React, browser APIs Node.js APIs ( fs , path ), Electron main APIs Worker ( packages/desktop/src/process/worker/ ) Node.js APIs DOM APIs, Electron APIs Preload ( packages/desktop/src/preload/ ) contextBridge , ipcRenderer DOM manipulation, Node.js fs Cross-process communication: Main ↔ Renderer: IPC via packages/desktop/src/preload/ + packages/desktop/src/process/bridge/*.ts Main ↔ Worker: fork protocol via packages/desktop/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 Scope Convention Reason Renderer component/module dirs PascalCase React convention — dir name = component name Everything else lowercase Node.js convention Categorical dirs (everywhere) lowercase components/ , hooks/ , utils/ , services/ Platform dirs (everywhere) lowercase acp/ , codex/ , gemini/ — cross-process consistency Quick test: "Inside packages/desktop/src/renderer/ AND represents a specific component/feature (not a category)?" → PascalCase. Otherwise → lowercase. Files Content Convention Examples React components, classes PascalCase SettingsModal.tsx , CronService.ts Hooks camelCase with use prefix useTheme.ts , useCronJobs.ts Utilities, helpers camelCase formatDate.ts , cronUtils.ts Entry points index.ts / index.tsx Required for directory-based modules Config, types, constants camelCase types.ts , constants.ts Styles kebab-case or Name.module.css chat-layout.css Structural Rules Directory size limit : Max 10 direct children. Split into subdirectories by responsibility when approaching. No single-file directories : Merge into parent or related directory. Single file vs directory : If a component needs a private sub-component or hook, convert to a directory with index.tsx . 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/ subdirectories: Source Test 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 When tests/unit/ exceeds 10 direct children, group into subdirectories matching source structure. 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