02 - Architecture Overview#

Helmor is a three-tier desktop application built on Tauri. Each tier owns a distinct responsibility and communicates through well-defined boundaries.

The three tiers#

┌─────────────┐ IPC (invoke) ┌──────────────┐ JSON Lines ┌──────────┐
│ Frontend │ ◄──────────────────► │ Backend │ ◄──────────────► │ Sidecar │
│ (React) │ Tauri channels │ (Rust) │ stdin/stdout │ (Bun) │
└─────────────┘ └──────────────┘ └──────────┘

Frontend — React in a Tauri webview#

• React 19 with Vite bundling.
• Zustand for module-level state (survives unmounts). React Query for server state with file-system persistence.
• Radix UI components, Tailwind CSS, Monaco editor, xterm terminal.
• Communicates with the backend via typed invoke() wrappers and Tauri channels for streaming.

Backend — Rust/Tauri#

• Owns persistence (SQLite with WAL mode, dual-pool: 8 readers, 1 writer).
• Manages workspace lifecycle (worktrees, branches, file operations).
• Orchestrates agent sessions, streaming pipeline, and message persistence.
• Handles Git operations, encryption, and GitHub OAuth.
• Spawns and supervises the sidecar process.

Sidecar — Bun process#

• Interfaces with agent providers (Claude Code, Codex, Cursor).
• Communicates with the backend via JSON Lines over stdin/stdout.
• Emits heartbeats every 15 seconds during active streams.
• Three-step shutdown: cooperative RPC → SIGTERM → SIGKILL.

Data flow: sending a message#

1. User types prompt → frontend calls invoke("send_agent_message_stream").
2. Backend persists user message, acquires stream lock, writes JSON request to sidecar stdin.
3. Sidecar forwards to agent provider, streams events back on stdout.
4. Backend parses events, persists assistant turns, emits deltas to frontend via Tauri channel.
5. Frontend updates Zustand store → React re-renders the session timeline.

Key design decisions#

• Module-level state — Zustand stores live outside React so Tauri channel callbacks work even if components unmount.
• Two-phase workspace creation — fast DB insert (~20ms) followed by async filesystem materialization (~200ms–2s).
• Per-workspace locks — serialize filesystem mutations with database updates to prevent corruption.

Related#

• Frontend Overview — React architecture details.
• Backend Overview — Rust modules and persistence.
• Sidecar Overview — agent communication protocol.