Architecture

Agent Observer is primarily an Electron desktop application with a separate Next.js documentation/product web surface.

System Layers

Desktop Runtime (Electron Main)

Responsibilities:

• lifecycle and window management
• IPC handler registration
• integration with local process/runtime boundaries
• persistent local state for scheduler and todo runner

Key modules:

• src/main/index.ts
• src/main/scheduler.ts
• src/main/todo-runner.ts
• src/main/claude-session.ts

Preload Bridge

Provides typed, constrained renderer access to main-process functionality.

Key module:

• src/preload/index.ts

Renderer (React)

Responsibilities:

• panel layout and interaction state
• settings UI for schedules and todo runner
• status presentation and operator controls

Key modules:

• src/renderer/components/SettingsPanel.tsx
• src/renderer/types.ts

Shared Contracts

Shared typing for renderer/preload interfaces:

• src/shared/electron-api.ts

Web Docs Surface (Next.js)

Separate web app for docs/content:

• web/src/app/*
• web/content/docs/*

Automation Engines

Scheduler

• Time-based recurring task execution.
• Cron parsing and next-run calculation in main process.
• Runtime status persisted to local JSON.

State file:

• ~/.agent-observer/schedules.json

Todo Runner

• Sequential checklist execution until completion or blocked state.
• One todo item per runner invocation.
• Retry and pause semantics built into orchestration loop.

State file:

• ~/.agent-observer/todo-runner.json

Install Telemetry Beacon

• Generates a stable local installationId on first launch.
• Sends one anonymous first-launch beacon using a SHA-256 hash of that ID.
• Retries with bounded exponential backoff and stops after max attempts.

State file:

• ~/.agent-observer/install-beacon.json

Environment override:

• AGENT_OBSERVER_INSTALL_BEACON_URL

Data/Control Flow

1. User configures automation in Settings.
2. Renderer calls preload APIs.
3. Preload forwards to main IPC handlers.
4. Main engine mutates state and executes work.
5. Main broadcasts update events.
6. Renderer reloads lists and updates status UI.

Design Constraints

• Local filesystem and command execution boundaries must remain explicit.
• Long-running work must be resumable.
• UI status should be derived from persisted runtime state where possible.
• Docs and implementation contracts must stay aligned.

Extension Direction

High-value extension points:

• richer run history and artifact storage
• policy controls for runner commands
• stronger contract validation for runner outputs
• richer event stream for observability dashboards