State Management & Authority
Relevant source files
The following files were used as context for generating this wiki page:
State management in the J.A.R.V.I.S. desktop application is governed by a strict hierarchy of authority divided between three primary architectural boundaries: the Electron main process, the Renderer (UI), and the Backend Service. The system prioritizes "maximum intelligence with minimum interruption," ensuring that the authority for specific data types resides where the truth can be most accurately validated.
The architecture follows a "local-first" philosophy where the desktop shell acts as the private Control Room, managing the lifecycle of a loopback-only TypeScript service. State synchronization between these boundaries is achieved through a mix of IPC (Inter-Process Communication), typed contracts, and an authenticated Server-Sent Events (SSE) stream for real-time updates.
Sources: instructions/design-backend-prompt.txt:13-25, instructions/AGENTS.md:12-20
Architectural Authority Domains
The project enforces a "Decide state by authority" rule, where state is stored with the component allowed to be "right" about it. This prevents synchronization conflicts and ensures that the UI remains a visual reflection of verified system status.
| Domain | Authority Scope | Implementation Mechanism |
|---|---|---|
| Electron (Main) | Machine facts, process lifecycle, filesystem/native APIs, runtime environment. | IPC Handlers, main.ts |
| Backend Service | Sessions, tool execution, model inference, memory persistence, shared service truth. | REST API, handler.ts |
| Renderer (UI) | Presentation details, ephemeral interaction state, navigation, visual cache. | React State, Nanostores, Preload Bridge |
Sources: instructions/AGENTS.md:22-35, instructions/GEMINI.md:4-9
Synchronization Flow
The following diagram illustrates how state is propagated from the authoritative Backend to the Renderer through the Electron bridge.
The Renderer paints from a cache of backend truth and must reconcile through optimistic updates and rollbacks rather than assuming success.
Sources: instructions/AGENTS.md:42-53, src/main.ts:384-406
Orb State Contract
The "Orb" serves as the primary semantic indicator for the system's live state. Unlike decorative elements, the Orb state is a composite indicator driven by verified status from underlying subsystems.
Orb States and Visual Language
States are mapped to specific visual behaviors and are only considered "live" when verified by a subsystem probe.
| State | Semantic Meaning | Implementation Source |
|---|---|---|
ready | Local service is healthy. | Real health probe (/health) |
listening | Voice intake is active. | JarvisVoiceStatus |
thinking | Model inference/tool loop in progress. | xAI/Ollama stream start |
executing-approved | Action is running post-approval. | JarvisActionEngine |
disconnected | Service unreachable. | Health probe failure |
Sources: instructions/design-backend-prompt.txt:59-70, packages/shared/tests/contracts.test.ts:31-40
Orb State Transitions
The Orb state transition is triggered by the Backend and relayed to the Renderer to update the data-orb-state attribute on the HTML element.
Persistent Memory & LifeOS Authority
Authority over long-term persistence is delegated to the JarvisMemoryAdapter. This system distinguishes between structured facts and semantic document retrieval.
LifeOS Governance
A specialized subset of state, known as LifeOS, manages high-authority user data (Mission, Values, Current State). These are stored as Markdown files in the user's home directory (Documents/Jarvis-Glas/lifeos) to ensure they survive application re-installations.
- Authoritative Source: Local Filesystem (
MISSION.md,VALUES.md,CURRENT_STATE.md). - Injection Logic: The Backend reads these files on every chat turn to provide context to the LLM.
- Location Extraction: The system uses regex to extract the user's location from
LifeOSfiles to provide context-aware responses (e.g., weather) without repeated prompting.
Sources: backend/src/handler.ts:60-95, src/main.ts:880-888
Action Engine & Human-in-the-Loop
For operations involving system changes, the "Action Engine" implements a proposed-decided lifecycle. Authority for execution is gated by explicit user approval, adhering to the "No ambient execution" security principle.
Action Status Lifecycle
Actions transition through strictly typed states validated by isJarvisActionIntent.
- Proposed: Action is staged in the UI for review.
- Executing: Action is currently interacting with the OS/Browser.
- Completed/Failed: Terminal states reflecting the outcome.
- Rejected: Explicit user denial of the action.
Sources: packages/shared/tests/contracts.test.ts:151-164, backend/src/handler.ts:820-845
Configuration & Runtime State
Application configuration is split between environment variables (.env) and a local JSON config file.
- Config Authority: The Electron main process loads
jarvis-desktop-config.jsonfromuserDataand synchronizes it with the Backend viaPOST /v1/config. - Environment Injection: The Main process injects keys (e.g.,
XAI_API_KEY) into the child service process environment without writing them to the service's disk.
Sources: src/main.ts:48-95, instructions/design-backend-prompt.txt:43-45
Conclusion
State management in J.A.R.V.I.S. is a federated system where Electron, the Renderer, and the Backend Service maintain distinct areas of authority. By centralizing machine facts in Electron, task logic in the Backend, and visual cache in the Renderer, the system maintains high performance and reliability even during asynchronous operations or service reconnections. The Orb state serves as the visual anchor for this complex orchestration, providing the user with immediate, authoritative feedback on system activity.