129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
# Phase 3: TechnicalImplementationResearcher Decisions
|
|
|
|
## Architecture Choice
|
|
|
|
- Runtime: Electron `39.8.0`
|
|
- Renderer: React + Vite + TypeScript
|
|
- UI motion: Framer Motion, used selectively for layout transitions, state feedback, and utility-drawer choreography
|
|
- Data: SQLite with WAL mode and a single-writer orchestration queue
|
|
- Orchestration: Electron utility process
|
|
- Packaging: electron-builder
|
|
- Updates: `electron-updater`, gated by app settings and environment
|
|
|
|
## Why This Stack
|
|
|
|
- Electron is required by the project constraints and matches the need for local CLI/runtime orchestration.
|
|
- React is already aligned with repo knowledge and keeps renderer iteration fast.
|
|
- SQLite with WAL provides embedded local durability and low setup overhead, matching the PRD requirement to start without external database installation.
|
|
- A utility process avoids freezing the renderer during process supervision, lock management, or log ingestion.
|
|
|
|
Version note:
|
|
|
|
- Electron `41.0.0` was evaluated first, but the shipping baseline moved to `39.8.0` because the current SQLite native dependency did not rebuild cleanly on the newer runtime during packaging verification.
|
|
|
|
## State Ownership
|
|
|
|
### Renderer-only state
|
|
|
|
- split-pane layout and inspector visibility
|
|
- filter/search state
|
|
- command palette visibility
|
|
- form drafts
|
|
- optimistic mutation feedback
|
|
|
|
### Main-process privileged state
|
|
|
|
- windows
|
|
- menus
|
|
- file dialogs
|
|
- notifications
|
|
- backup/import/export paths
|
|
- updater lifecycle
|
|
- safeStorage encryption/decryption
|
|
|
|
### Utility-process orchestration state
|
|
|
|
- connector child process registry
|
|
- run queue
|
|
- workspace write locks
|
|
- per-agent concurrency locks
|
|
- session persistence and resume eligibility
|
|
- unfinished run reconciliation
|
|
|
|
### Persisted local state
|
|
|
|
- companies
|
|
- connectors and connector config documents
|
|
- workspaces
|
|
- agents
|
|
- goals/projects/tasks
|
|
- approvals and comments
|
|
- runs, run events, cost events
|
|
- activity log
|
|
- app settings and window state
|
|
|
|
## IPC Model
|
|
|
|
IPC is split into three layers:
|
|
|
|
1. Renderer to preload:
|
|
- typed methods only
|
|
- no raw channel strings in UI components
|
|
2. Preload to main:
|
|
- schema-validated request/response handlers
|
|
- sender verified in main
|
|
3. Main to utility process:
|
|
- internal command bus over message ports
|
|
- used for orchestration, not for UI privilege elevation
|
|
|
|
## Storage Strategy
|
|
|
|
- Database file: `profile.sqlite` under app profile data directory
|
|
- WAL enabled
|
|
- Attachments/logs/artifacts stored as files, indexed in SQLite
|
|
- Secrets stored via `safeStorage` when available; otherwise fallback encrypted vault plus explicit risk state on Linux
|
|
- Backups stored as timestamped archives under `backups/`
|
|
|
|
## Performance Strategy
|
|
|
|
- Renderer subscribes to normalized event streams instead of raw connector protocol noise
|
|
- Utility process owns long-running child processes
|
|
- Log viewer uses chunked pagination and windowed rendering
|
|
- Expensive derived summaries are computed in main/utility and sent as projections
|
|
|
|
## Connector Strategy
|
|
|
|
Connector contract layers:
|
|
|
|
- required:
|
|
- detect installation
|
|
- health/auth check
|
|
- execute
|
|
- normalize stdout/stderr/events
|
|
- declare capability matrix
|
|
- optional:
|
|
- session resume
|
|
- graceful cancel
|
|
- model discovery
|
|
- structured transcript
|
|
- cost attribution
|
|
|
|
## Updater Strategy
|
|
|
|
- default channel: disabled unless configured
|
|
- manual update check available from app menu and settings
|
|
- before install:
|
|
- write backup manifest
|
|
- flush db/log handles
|
|
- if signature validation fails:
|
|
- reject install
|
|
- record audit event
|
|
|
|
## Failure Model
|
|
|
|
- app restart scans unfinished runs
|
|
- stale running records become `interrupted`
|
|
- retryable runs expose resume/retry actions in UI
|
|
- workspace lock conflicts enqueue runs as `queued`
|
|
- connector health failures block new run dispatch
|