# System Architecture

This document describes the end-to-end architecture of Agent Orchestrator — how the Rust backend, Svelte 5 frontend, and Node.js/Deno sidecar processes work together to provide a multi-project AI agent orchestration dashboard.

---

## High-Level Overview

Agent Orchestrator is a Tauri 2.x desktop application. Tauri provides a Rust backend process and a WebKit2GTK-based webview for the frontend. The application manages AI agent sessions by spawning sidecar child processes that communicate with AI provider APIs (Claude, Codex, Ollama).

```
┌────────────────────────────────────────────────────────────────┐
│  Agent Orchestrator (Tauri 2.x)                                │
│                                                                │
│  ┌─────────────────┐    Tauri IPC     ┌────────────────────┐  │
│  │  WebView         │ ◄─────────────► │  Rust Backend      │  │
│  │  (Svelte 5)      │   invoke/listen │                    │  │
│  │                   │                │  ├── PtyManager     │  │
│  │  ├── ProjectGrid  │                │  ├── SidecarManager │  │
│  │  ├── AgentPane    │                │  ├── SessionDb      │  │
│  │  ├── TerminalPane │                │  ├── BtmsgDb        │  │
│  │  ├── StatusBar    │                │  ├── SearchDb       │  │
│  │  └── Stores       │                │  ├── SecretsManager │  │
│  └─────────────────┘                 │  ├── RemoteManager  │  │
│                                       │  └── FileWatchers   │  │
│                                       └────────────────────┘  │
│                                           │                    │
└───────────────────────────────────────────┼────────────────────┘
                                            │ stdio NDJSON
                                            ▼
                                    ┌───────────────────┐
                                    │ Sidecar Processes  │
                                    │ (Deno or Node.js)  │
                                    │                    │
                                    │ claude-runner.mjs  │
                                    │ codex-runner.mjs   │
                                    │ ollama-runner.mjs  │
                                    └───────────────────┘
```

### Why Three Layers?

1. **Rust backend** — Manages OS-level resources (PTY processes, file watchers, SQLite databases) with memory safety and low overhead. Exposes everything to the frontend via Tauri IPC commands and events.

2. **Svelte 5 frontend** — Renders the UI with fine-grained reactivity (no VDOM). Svelte 5 runes (`$state`, `$derived`, `$effect`) provide signal-based reactivity comparable to Solid.js but with a larger ecosystem.

3. **Sidecar processes** — The Claude Agent SDK, OpenAI Codex SDK, and Ollama API are all JavaScript/TypeScript libraries. They cannot run in Rust or in the WebKit2GTK webview (no Node.js APIs). The sidecar layer bridges this gap: Rust spawns a JS process, communicates via stdio NDJSON, and forwards structured messages to the frontend.

---

## Rust Backend (`src-tauri/`)

The Rust backend is the central coordinator. It owns all OS resources and database connections.

### Cargo Workspace

The Rust code is organized as a Cargo workspace with three members:

```
v2/
├── Cargo.toml              # Workspace root
├── agor-core/          # Shared crate
│   └── src/
│       ├── lib.rs
│       ├── pty.rs           # PtyManager (portable-pty)
│       ├── sidecar.rs       # SidecarManager (multi-provider)
│       ├── supervisor.rs    # SidecarSupervisor (crash recovery)
│       ├── sandbox.rs       # Landlock sandbox
│       └── event.rs         # EventSink trait
├── agor-relay/         # Remote machine relay
│   └── src/main.rs          # WebSocket server + token auth
└── src-tauri/               # Tauri application
    └── src/
        ├── lib.rs           # AppState + setup + handler registration
        ├── commands/        # 16 domain command modules
        ├── btmsg.rs         # Inter-agent messaging (SQLite)
        ├── bttask.rs        # Task board (SQLite, shared btmsg.db)
        ├── search.rs        # FTS5 full-text search
        ├── secrets.rs       # System keyring (libsecret)
        ├── plugins.rs       # Plugin discovery
        ├── notifications.rs # Desktop notifications
        ├── session/         # SessionDb (sessions, layout, settings, agents, metrics, anchors)
        ├── remote.rs        # RemoteManager (WebSocket client)
        ├── ctx.rs           # Read-only ctx database access
        ├── memora.rs        # Read-only Memora database access
        ├── telemetry.rs     # OpenTelemetry tracing
        ├── groups.rs        # Project groups config
        ├── watcher.rs       # File watcher (notify crate)
        ├── fs_watcher.rs    # Per-project filesystem watcher (inotify)
        ├── event_sink.rs    # TauriEventSink implementation
        ├── pty.rs           # Thin re-export from agor-core
        └── sidecar.rs       # Thin re-export from agor-core
```

### Why a Workspace?

The `agor-core` crate exists so that both the Tauri application and the standalone `agor-relay` binary can share PtyManager and SidecarManager code. The `EventSink` trait abstracts event emission — TauriEventSink wraps Tauri's AppHandle, while the relay uses a WebSocket-based EventSink.

### AppState

All backend state lives in `AppState`, initialized during Tauri setup:

```rust
pub struct AppState {
    pub pty_manager: Mutex<PtyManager>,
    pub sidecar_manager: Mutex<SidecarManager>,
    pub session_db: Mutex<SessionDb>,
    pub remote_manager: Mutex<RemoteManager>,
    pub telemetry: Option<TelemetryGuard>,
}
```

### SQLite Databases

The backend manages two SQLite databases, both in WAL mode with 5-second busy timeout for concurrent access:

| Database | Location | Purpose |
|----------|----------|---------|
| `sessions.db` | `~/.local/share/agor/` | Sessions, layout, settings, agent state, metrics, anchors |
| `btmsg.db` | `~/.local/share/agor/` | Inter-agent messages, tasks, agents registry, audit log |

WAL checkpoints run every 5 minutes via a background tokio task to prevent unbounded WAL growth.

All queries use **named column access** (`row.get("column_name")`) — never positional indices. Rust structs use `#[serde(rename_all = "camelCase")]` so TypeScript interfaces receive camelCase field names on the wire.

### Command Modules

Tauri commands are organized into 16 domain modules under `commands/`:

| Module | Commands | Purpose |
|--------|----------|---------|
| `pty` | spawn, write, resize, kill | Terminal management |
| `agent` | query, stop, ready, restart | Agent session lifecycle |
| `session` | session CRUD, layout, settings | Session persistence |
| `persistence` | agent state, messages | Agent session continuity |
| `knowledge` | ctx, memora queries | External knowledge bases |
| `claude` | profiles, skills | Claude-specific features |
| `groups` | load, save | Project group config |
| `files` | list_directory, read/write file | File browser |
| `watcher` | start, stop | File change monitoring |
| `remote` | 12 commands | Remote machine management |
| `bttask` | list, create, update, delete, comments | Task board |
| `search` | init, search, rebuild, index | FTS5 search |
| `secrets` | store, get, delete, list, has_keyring | Secrets management |
| `plugins` | discover, read_file | Plugin discovery |
| `notifications` | send_desktop | OS notifications |
| `misc` | test_mode, frontend_log | Utilities |

---

## Svelte 5 Frontend (`src/`)

The frontend uses Svelte 5 with runes for reactive state management. The UI follows a VSCode-inspired layout with a left icon rail, expandable drawer, project grid, and status bar.

### Component Hierarchy

```
App.svelte                           [Root — VSCode-style layout]
├── CommandPalette.svelte            [Ctrl+K overlay, 18+ commands]
├── SearchOverlay.svelte             [Ctrl+Shift+F, FTS5 Spotlight-style]
├── NotificationCenter.svelte        [Bell icon + dropdown]
├── GlobalTabBar.svelte              [Left icon rail, 2.75rem wide]
├── [Sidebar Panel]                  [Expandable drawer, max 50%]
│   └── SettingsTab.svelte           [Global settings + group/project CRUD]
├── ProjectGrid.svelte               [Flex + scroll-snap, adaptive count]
│   └── ProjectBox.svelte            [Per-project container, 11 tab types]
│       ├── ProjectHeader.svelte     [Icon + name + status + badges]
│       ├── AgentSession.svelte      [Main Claude session wrapper]
│       │   ├── AgentPane.svelte     [Structured message rendering]
│       │   └── TeamAgentsPanel.svelte [Tier 1 subagent cards]
│       ├── TerminalTabs.svelte      [Shell/SSH/agent-preview tabs]
│       │   ├── TerminalPane.svelte  [xterm.js + Canvas addon]
│       │   └── AgentPreviewPane.svelte [Read-only agent activity]
│       ├── DocsTab.svelte           [Markdown file browser]
│       ├── ContextTab.svelte        [LLM context visualization]
│       ├── FilesTab.svelte          [Directory tree + CodeMirror editor]
│       ├── SshTab.svelte            [SSH connection manager]
│       ├── MemoriesTab.svelte       [Memora database viewer]
│       ├── MetricsPanel.svelte      [Health + history sparklines]
│       ├── TaskBoardTab.svelte      [Kanban board, Manager only]
│       ├── ArchitectureTab.svelte   [PlantUML viewer, Architect only]
│       └── TestingTab.svelte        [Selenium/test files, Tester only]
└── StatusBar.svelte                 [Agent counts, burn rate, attention queue]
```

### Stores (Svelte 5 Runes)

All store files use the `.svelte.ts` extension — this is required for Svelte 5 runes (`$state`, `$derived`, `$effect`). Files with plain `.ts` extension will compile but fail at runtime with "rune_outside_svelte".

| Store | Purpose |
|-------|---------|
| `workspace.svelte.ts` | Project groups, active group, tabs, focus |
| `agents.svelte.ts` | Agent sessions, messages, cost, parent/child hierarchy |
| `health.svelte.ts` | Per-project health tracking, attention scoring, burn rate |
| `conflicts.svelte.ts` | File overlap + external write detection |
| `anchors.svelte.ts` | Session anchor management (auto/pinned/promoted) |
| `notifications.svelte.ts` | Toast + history (6 types, unread badge) |
| `plugins.svelte.ts` | Plugin command registry, event bus |
| `theme.svelte.ts` | 17 themes, font restoration |
| `machines.svelte.ts` | Remote machine state |
| `wake-scheduler.svelte.ts` | Manager auto-wake (3 strategies, per-manager timers) |

### Adapters (IPC Bridge Layer)

Adapters wrap Tauri `invoke()` calls and `listen()` event subscriptions. They isolate the frontend from IPC details and provide typed TypeScript interfaces.

| Adapter | Backend Module | Purpose |
|---------|---------------|---------|
| `agent-bridge.ts` | sidecar + commands/agent | Agent query/stop/restart |
| `pty-bridge.ts` | pty + commands/pty | Terminal spawn/write/resize |
| `claude-messages.ts` | — (frontend-only) | Parse Claude SDK NDJSON → AgentMessage |
| `codex-messages.ts` | — (frontend-only) | Parse Codex ThreadEvents → AgentMessage |
| `ollama-messages.ts` | — (frontend-only) | Parse Ollama chunks → AgentMessage |
| `message-adapters.ts` | — (frontend-only) | Provider registry for message parsers |
| `provider-bridge.ts` | commands/claude | Generic provider bridge (profiles, skills) |
| `btmsg-bridge.ts` | btmsg | Inter-agent messaging |
| `bttask-bridge.ts` | bttask | Task board operations |
| `groups-bridge.ts` | groups | Group config load/save |
| `session-bridge.ts` | session | Session/layout persistence |
| `settings-bridge.ts` | session/settings | Key-value settings |
| `files-bridge.ts` | commands/files | File browser operations |
| `search-bridge.ts` | search | FTS5 search |
| `secrets-bridge.ts` | secrets | System keyring |
| `anchors-bridge.ts` | session/anchors | Session anchor CRUD |
| `remote-bridge.ts` | remote | Remote machine management |
| `ssh-bridge.ts` | session/ssh | SSH session CRUD |
| `ctx-bridge.ts` | ctx | Context database queries |
| `memora-bridge.ts` | memora | Memora database queries |
| `fs-watcher-bridge.ts` | fs_watcher | Filesystem change events |
| `audit-bridge.ts` | btmsg (audit_log) | Audit log queries |
| `telemetry-bridge.ts` | telemetry | Frontend → Rust tracing |
| `notifications-bridge.ts` | notifications | Desktop notification trigger |
| `plugins-bridge.ts` | plugins | Plugin discovery |

### Agent Dispatcher

The agent dispatcher (`agent-dispatcher.ts`, ~260 lines) is the central router between sidecar events and the agent store. When the Rust backend emits a `sidecar-message` Tauri event, the dispatcher:

1. Looks up the provider for the session (via `sessionProviderMap`)
2. Routes the raw message through the appropriate adapter (claude-messages.ts, codex-messages.ts, or ollama-messages.ts) via `message-adapters.ts`
3. Feeds the resulting `AgentMessage[]` into the agent store
4. Handles side effects: subagent pane spawning, session persistence, auto-anchoring, worktree detection, health tracking, conflict recording

The dispatcher delegates to four extracted utility modules:
- `utils/session-persistence.ts` — session-project maps, persistSessionForProject
- `utils/subagent-router.ts` — spawn + route subagent panes
- `utils/auto-anchoring.ts` — triggerAutoAnchor on first compaction event
- `utils/worktree-detection.ts` — detectWorktreeFromCwd pure function

---

## Sidecar Layer (`sidecar/`)

See [sidecar.md](sidecar.md) for the full sidecar architecture. In brief:

- Each AI provider has its own runner file (e.g., `claude-runner.ts`) compiled to an ESM bundle (`claude-runner.mjs`) by esbuild
- Rust's SidecarManager spawns the appropriate runner based on the `provider` field in AgentQueryOptions
- Communication uses stdio NDJSON — one JSON object per line, newline-delimited
- Deno is preferred (faster startup), Node.js is the fallback
- The Claude runner uses `@anthropic-ai/claude-agent-sdk` query() internally

---

## Data Flow: Agent Query Lifecycle

Here is the complete path of a user prompt through the system:

```
1. User types prompt in AgentPane
2. AgentPane calls agentBridge.queryAgent(options)
3. agent-bridge.ts invokes Tauri command 'agent_query'
4. Rust agent_query handler calls SidecarManager.query()
5. SidecarManager resolves provider runner (e.g., claude-runner.mjs)
6. SidecarManager writes QueryMessage as NDJSON to sidecar stdin
7. Sidecar runner calls provider SDK (e.g., Claude Agent SDK query())
8. Provider SDK streams responses
9. Runner forwards each response as NDJSON to stdout
10. SidecarManager reads stdout line-by-line
11. SidecarManager emits Tauri event 'sidecar-message' with sessionId + data
12. Frontend agent-dispatcher.ts receives event
13. Dispatcher routes through message-adapters.ts → provider-specific parser
14. Parser converts to AgentMessage[]
15. Dispatcher feeds messages into agents.svelte.ts store
16. AgentPane reactively re-renders via $derived bindings
```

### Session Stop Flow

```
1. User clicks Stop button in AgentPane
2. AgentPane calls agentBridge.stopAgent(sessionId)
3. agent-bridge.ts invokes Tauri command 'agent_stop'
4. Rust handler calls SidecarManager.stop(sessionId)
5. SidecarManager writes StopMessage to sidecar stdin
6. Runner calls AbortController.abort() on the SDK query
7. SDK terminates the Claude subprocess
8. Runner emits final status message, then closes
```

---

## Configuration

### Project Groups (`~/.config/agor/groups.json`)

Human-editable JSON file defining project groups and their projects. Loaded at startup by `groups.rs`. Not hot-reloaded — changes require app restart or group switch.

### SQLite Settings (`sessions.db` → `settings` table)

Key-value store for user preferences: theme, fonts, shell, CWD, provider settings. Accessed via `settings-bridge.ts` → `settings_get`/`settings_set` Tauri commands.

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `AGOR_TEST` | Enables test mode (disables watchers, wake scheduler) |
| `AGOR_TEST_DATA_DIR` | Redirects SQLite database storage |
| `AGOR_TEST_CONFIG_DIR` | Redirects groups.json config |
| `AGOR_OTLP_ENDPOINT` | Enables OpenTelemetry OTLP export |

---

## Data Model

### Project Group Config (`~/.config/agor/groups.json`)

Human-editable JSON file defining workspaces. Each group contains up to 5 projects. Loaded at startup by `groups.rs`, not hot-reloaded.

```jsonc
{
  "version": 1,
  "groups": [
    {
      "id": "work-ai",
      "name": "AI Projects",
      "projects": [
        {
          "id": "agor",
          "name": "Agents Orchestrator",
          "identifier": "agor",
          "description": "Terminal emulator with Claude integration",
          "icon": "\uf120",
          "cwd": "/home/user/code/Agents Orchestrator",
          "profile": "default",
          "enabled": true
        }
      ]
    }
  ],
  "activeGroupId": "work-ai"
}
```

### TypeScript Types (`src/lib/types/groups.ts`)

```typescript
export interface ProjectConfig {
  id: string;
  name: string;
  identifier: string;
  description: string;
  icon: string;
  cwd: string;
  profile: string;
  enabled: boolean;
}

export interface GroupConfig {
  id: string;
  name: string;
  projects: ProjectConfig[];  // max 5
}

export interface GroupsFile {
  version: number;
  groups: GroupConfig[];
  activeGroupId: string;
}
```

### SQLite Schema (v3 Additions)

Beyond the core `sessions` and `settings` tables, v3 added project-scoped agent persistence:

```sql
ALTER TABLE sessions ADD COLUMN project_id TEXT DEFAULT '';

CREATE TABLE IF NOT EXISTS agent_messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    project_id TEXT NOT NULL,
    sdk_session_id TEXT,
    message_type TEXT NOT NULL,
    content TEXT NOT NULL,
    parent_id TEXT,
    created_at INTEGER NOT NULL,
    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS project_agent_state (
    project_id TEXT PRIMARY KEY,
    last_session_id TEXT NOT NULL,
    sdk_session_id TEXT,
    status TEXT NOT NULL,
    cost_usd REAL DEFAULT 0,
    input_tokens INTEGER DEFAULT 0,
    output_tokens INTEGER DEFAULT 0,
    last_prompt TEXT,
    updated_at INTEGER NOT NULL
);
```

---

## Layout System

### Project Grid (Flexbox + scroll-snap)

Projects are arranged horizontally in a flex container with CSS scroll-snap for clean project-to-project scrolling:

```css
.project-grid {
  display: flex;
  gap: 4px;
  height: 100%;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}

.project-box {
  flex: 0 0 calc((100% - (N-1) * 4px) / N);
  scroll-snap-align: start;
  min-width: 480px;
}
```

N is computed from viewport width: `Math.min(projects.length, Math.max(1, Math.floor(containerWidth / 520)))`

### Project Box Internal Layout

Each project box uses a CSS grid with 4 rows:

```
┌─ ProjectHeader (auto) ─────────────────┐
├─────────────────────┬──────────────────┤
│ AgentSession        │ TeamAgentsPanel  │
│ (flex: 1)           │ (240px/overlay)  │
├─────────────────────┴──────────────────┤
│ [Tab1] [Tab2] [+]          TabBar auto │
├────────────────────────────────────────┤
│ Terminal content (xterm or scrollback) │
└────────────────────────────────────────┘
```

Team panel: inline at >2560px viewport (240px wide), overlay at <2560px. Collapsed when no subagents running.

### Responsive Breakpoints

| Viewport Width | Visible Projects | Team Panel Mode |
|---------------|-----------------|-----------------|
| 5120px+ | 5 | inline 240px |
| 3840px | 4 | inline 200px |
| 2560px | 3 | overlay |
| 1920px | 3 | overlay |
| <1600px | 1 + project tabs | overlay |

### xterm.js Budget: 4 Active Instances

WebKit2GTK OOMs at ~5 simultaneous xterm.js instances. The budget system manages this:

| State | xterm.js Instance? | Memory |
|-------|--------------------|--------|
| Active-Focused | Yes | ~20MB |
| Active-Background | Yes (if budget allows) | ~20MB |
| Suspended | No (HTML pre scrollback) | ~200KB |
| Uninitialized | No (placeholder) | 0 |

On focus: serialize least-recent xterm scrollback, destroy it, create new for focused tab, reconnect PTY. Suspend/resume cycle < 50ms.

### Project Accent Colors

Each project slot gets a distinct Catppuccin accent color for visual distinction:

| Slot | Color | CSS Variable |
|------|-------|-------------|
| 1 | Blue | `var(--ctp-blue)` |
| 2 | Green | `var(--ctp-green)` |
| 3 | Mauve | `var(--ctp-mauve)` |
| 4 | Peach | `var(--ctp-peach)` |
| 5 | Pink | `var(--ctp-pink)` |

Applied to border tint and header accent via `var(--accent)` CSS custom property set per ProjectBox.

---

## Keyboard Shortcuts

Three-layer shortcut system prevents conflicts between terminal input, workspace navigation, and app-level commands:

| Shortcut | Action | Layer |
|----------|--------|-------|
| Ctrl+K | Command palette | App |
| Ctrl+G | Switch group (palette filtered) | App |
| Ctrl+1..5 | Focus project by index | App |
| Alt+1..4 | Switch sidebar tab + open drawer | App |
| Ctrl+B | Toggle sidebar open/closed | App |
| Ctrl+, | Toggle settings panel | App |
| Escape | Close sidebar drawer | App |
| Ctrl+Shift+F | FTS5 search overlay | App |
| Ctrl+N | New terminal in focused project | Workspace |
| Ctrl+Shift+N | New agent query | Workspace |
| Ctrl+Tab | Next terminal tab | Project |
| Ctrl+W | Close terminal tab | Project |
| Ctrl+Shift+C/V | Copy/paste in terminal | Terminal |

Terminal layer captures raw keys only when focused. App layer has highest priority.

---

## Key Constraints

1. **WebKit2GTK has no WebGL** — xterm.js must use the Canvas addon explicitly. Maximum 4 active xterm.js instances to avoid OOM.

2. **Svelte 5 runes require `.svelte.ts`** — Store files using `$state`/`$derived` must have the `.svelte.ts` extension. The compiler silently accepts `.ts` but runes fail at runtime.

3. **Single shared sidecar** — All agent sessions share one SidecarManager. Per-project isolation is via `cwd`, `claude_config_dir`, and `session_id` routing. Per-project sidecar pools deferred to v3.1.

4. **SQLite WAL mode** — Both databases use WAL with 5s busy_timeout for concurrent access from Rust backend + Python CLIs (btmsg/bttask).

5. **camelCase wire format** — Rust uses `#[serde(rename_all = "camelCase")]`. TypeScript interfaces must match. This was a source of bugs during development (see [findings.md](findings.md) for context).
