AgentCompany/docs/2026-03-17-architecture-freeze.md

# 2026-03-17 Architecture Freeze

## Supported Platform Target

The product target remains cross-platform:

- macOS
- Windows
- Linux

The current codebase can build on the local host, but release readiness is not equivalent across targets yet.

### Platform-specific constraints to preserve

- macOS
  - hidden inset title bar
  - signing and notarization required for public release
  - `safeStorage` may block on keychain access
- Windows
  - App User Model ID is required for correct notifications and taskbar integration
  - NSIS is the release target
  - code signing required for updater trust
- Linux
  - safe storage backend can fall back to weaker semantics when no secret store exists
  - Wayland window behavior is more limited than X11
  - AppImage is the primary packaged target today

## External Research Decisions

### Electron security

Based on the current Electron security checklist:

- keep `nodeIntegration: false`
- keep `contextIsolation: true`
- keep `sandbox: true`
- keep the custom `app://` protocol instead of `file://`
- validate sender URLs on every IPC entry point
- do not expose raw IPC objects in preload
- define a restrictive CSP in local renderer content

### Utility process

The current choice of `utilityProcess.fork()` is still the right worker primitive.

Reasoning:

- it keeps heavy connector execution off the renderer
- it is more aligned with Electron security guidance than broad use of `ELECTRON_RUN_AS_NODE`
- it is compatible with future fuse hardening around `runAsNode`

### Secret storage

`safeStorage` remains the primary storage contract.

Fallback rules:

- use OS-backed `safeStorage` when real encryption is available
- reject insecure runtime environments by default
- allow AES vault fallback only in explicitly allowed test/insecure modes

### Updater

`electron-updater` remains acceptable, but only if release lanes are made real.

Required implications:

- real publish endpoint
- signed macOS app
- Windows signing
- explicit metadata handling for the generic provider
- download/apply UX in-app, not just “check available”

## Process Boundary Freeze

### Main process

Owns:

- app lifecycle
- BrowserWindow creation
- custom protocol registration
- native menus / tray / dialogs / notifications
- database initialization
- worker process lifecycle
- updater lifecycle
- browser automation windows
- privileged IPC handlers

Must not:

- become the place where all query, mutation, aggregation, and orchestration code accumulates

### Preload

Owns:

- typed, minimal bridge from renderer to approved use-cases

Must not:

- expose raw `ipcRenderer`
- expose generic file-system or shell primitives
- become a mirror of every DB method

### Renderer

Owns:

- operator workflows
- presentation logic
- optimistic local UI state
- command palette / shell navigation
- empty / loading / error / review states

Must not:

- talk in raw CRUD terms when the user is performing operator flows
- own privileged state
- load whole-world snapshots forever as the only data pattern

### Utility process

Owns:

- connector execution
- per-run stream forwarding
- cancellation
- run queue scheduling local to worker

Must not:

- become the persistence layer
- own security policy decisions that belong in main

## State Ownership Model

### Renderer-local state

- selected entities
- open panels / modals
- search queries
- console UI state
- transient filter/sort state

### Persisted domain state

- companies
- connectors
- workspaces
- agents
- goals / projects / tasks
- approvals
- runs
- cost entries
- activity
- secrets
- automation rules
- workflows
- browser actions

### Runtime execution state

- active worker jobs
- agent concurrency map
- workspace lock ownership
- pending wakes
- update progress
- browser action queue

### Derived read models

These should be separated from write repositories:

- overview metrics
- inbox
- standup
- run queue / attention views
- workload and review summaries

## Storage Decision

### Current decision

Keep SQLite + WAL for this tranche.

### Constraints

- single-writer semantics remain acceptable if heavy aggregations are not kept in the same giant repository
- crash recovery must preserve unfinished run semantics
- backup / restore must remain profile-local and reversible

### Required follow-up

- split read models from write repositories
- add offset-based log readers
- keep artifacts and logs on disk, indexed in SQLite

## IPC Contract Strategy

### Contract rules

- every mutating IPC call must stay company-scoped when relevant
- large payloads should use typed request objects, not positional args
- contract names stay explicit and descriptive
- result envelopes stay structured

### Next contract change

The next contract slice will add:

- dedicated run listing / filtering reads
- chunked log reads
- connector selection in onboarding

## Renderer Information Architecture Freeze

Primary desktop sections:

1. Overview
2. Runs
3. Tasks
4. Approvals
5. Messages
6. Agents
7. Workspaces
8. Connectors
9. Costs
10. Activity
11. Settings

Secondary knowledge/operations surfaces can remain, but they should not dominate the shell.

## Milestone Mapping

### Architecture Freeze

- this document accepted

### Interactive Prototype

- shell reordered around operator workflows
- run console and runs list coherent

### Internal Alpha

- onboarding, connector health, task run, approval, message routing, and workspace inspection work together

### Cross-Platform Validation

- menu, tray, notification, and package behavior documented per OS

### Signed Beta

- updater feed real
- signing path documented and testable

### Release Candidate

- all repo quality gates green

### Production Ready

- security audit, release hardening, and operator workflow polish complete