Dosu Logo
Ask
Documents
02 - Architecture Overview
02 - Architecture Overview
Type
Document
Status
Published
Created
May 26, 2026
Updated
May 26, 2026
Updated by
Dosu Bot

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.