03 - Frontend Overview#

The Helmor frontend is a React application running inside a Tauri webview. It provides the workspace UI, session timeline, code editor, file browser, and terminal — all communicating with the Rust backend via Tauri IPC.

Tech stack#

Project structure#

src/
├── features/ # Feature modules (workspace, session, commit, etc.)
├── components/ # Shared components
│ └── ui/ # Primitives (button, dialog, input, etc.)
├── hooks/ # Shared React hooks
├── stores/ # Zustand stores
├── lib/ # Utilities, query keys, constants
└── App.tsx # Root component

State management#

Zustand handles runtime state that must survive React component unmounts — streaming status, pending permissions, active sessions. These stores exist at module level so Tauri channel callbacks can update them even when the relevant component isn't mounted.

React Query manages server-derived state (workspaces, sessions, messages, settings). Key features:

• Hierarchical query keys for targeted invalidation.
• Opt-in file-system persistence (bypasses webview storage quotas).
• 30-minute GC time; persisted entries live 24 hours.
• Session messages tail-load the 100 most recent for fast workspace switching.

IPC with the backend#

Frontend calls typed wrappers around Tauri's invoke(). For streaming operations (agent messages), Tauri channels emit multiple events into a callback, which updates the Zustand store directly.

Streaming flow:

1. Composer submit → optimistic React Query cache update.
2. Mark session as "sending" in Zustand.
3. Call invoke("send_agent_message_stream", { request, onEvent }).
4. Event dispatcher routes backend deltas to the store.

Related#

• Architecture Overview — where frontend fits in the three tiers.
• Backend Overview — what the IPC calls invoke.