Initialize project and ignore local references

docs/04-technical-implementation-research.md

@@ -0,0 +1,128 @@
+# 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