AgentCompany/docs/04-technical-implementation-research.md

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