Toju/electron/CONTEXT.md

Desktop Shell (electron)

Owns the desktop runtime: the Electron main process, the preload bridge that exposes window.api to the renderer, IPC handlers, the local TypeORM + sql.js database, the plugin loader, OS-integration adapters (window controls, idle detection, game detection, audio), update flow, and the Local API server that hosts the Docusaurus bundle inside the app.

Format reference:

• Vocabulary — bold term, one-sentence definition, aliases to avoid.
• Relationships — bullets with bold terms and cardinality.
• Boundaries / IO — what this subdomain exposes and consumes.
• Invariants — rules that always hold.
• Flagged ambiguities — terms in dispute with proposed resolutions.

See agents-docs/AGENTS_CONTEXT.md for the contract. Update in the same turn a trigger fires (see agents-docs/AGENT_WORKFLOW.md § CONTEXT.md upkeep).

Vocabulary

Term	Definition	Aliases to avoid
Preload bridge	electron/preload.ts — the only surface that the renderer can call into Node through; exposes window.api.* after contextBridge.exposeInMainWorld.	"preloader"
IPC handler	A main-process function registered against an IPC channel name; lives under electron/ipc/ (system, window-controls) and electron/cqrs.ts.	"rpc handler"
CQRS handler	Command or query handler dispatched through electron/ipc/cqrs.ts; pattern shared with server/src/cqrs/.	"command processor"
Local API server	An in-process HTTP server (electron/api/local-api-server.ts) that serves the prebuilt Docusaurus docs and OpenAPI views to the renderer over http://localhost:<port>/.	"internal API"
Plugin library	The plugin loader (electron/plugin-library.ts) — resolves manifests, validates entry points, and prepares the sandbox the renderer mounts plugins into.	"plugin manager"
Data archive	The export/import format implemented in electron/data-archive.ts for moving a user's local database between installs.	"backup"

Relationships

• The Preload bridge is the only path between the Renderer (toju-app) and Main; the renderer cannot import Electron, Node, or TypeORM directly.
• An IPC channel maps 1:1 to a method on window.api.*. Adding a method on the preload requires registering its handler in electron/ipc/ or electron/cqrs.ts.
• The Plugin library loads manifests at startup and on user action; it owns the contract the renderer's plugins domain consumes (defined in toju-app/src/app/shared-kernel/plugin-system.contracts.ts).
• TypeORM migrations in electron/migrations/ are applied on startup against the per-user SQLite file resolved by electron/runtime-paths.ts.
• The Local API server serves the Docusaurus bundle built into docs-site/build/ and the OpenAPI artifacts under electron/api/openapi.ts.

Boundaries / IO

• Exposes:
  • window.api.* surface (preload bridge) — the canonical IPC contract for the renderer.
  • IPC channel names registered in electron/ipc/index.ts, electron/ipc/cqrs.ts, electron/ipc/system.ts, electron/ipc/window-controls.ts.
  • Local API HTTP endpoints (electron/api/router.ts) under http://localhost:<port>/.
  • Plugin host contract (electron/plugin-library.ts) — defines what plugin manifests must declare and what the plugin runtime can call back into.
• Consumes:
  • The renderer (toju-app) via IPC invoke/handle and event emitters.
  • The local SQLite database via electron/data-source.ts and entities under electron/entities/.
  • OS APIs: window controls, idle detection (electron/idle/), game detection (electron/game-detection/), process list (electron/process-list.ts).
  • The audio worklet bundle (toju-app/public/rnnoise-worklet.js built from @timephy/rnnoise-wasm).

Invariants

• The Renderer never has direct access to Node, the filesystem, or the database — every privileged operation goes through an IPC handler.
• Every schema change is accompanied by a TypeORM migration; the database is never mutated outside the migration system.
• IPC handler errors are translated to typed error envelopes before crossing back into the renderer — the renderer never sees a raw Error from main.
• The Preload bridge exposes a frozen, allow-listed set of methods; adding a method requires touching both preload.ts and the matching handler.

Flagged ambiguities

• None recorded yet — add entries when an IPC channel name or plugin contract term resists clean definition.

---

Agent-procedural rules (TDD, lint, build) live in /AGENTS.md. Cross-context contract details (IPC envelope shapes, plugin manifest schema) belong in agents-docs/features/. This file is the bounded-context domain artefact for the desktop shell.