Desktop Engineering Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• instructions/AGENTS.md
• instructions/GEMINI.md
• instructions/DESIGN.md
• instructions/design-backend-prompt.txt
• src/renderer.css
• CONTRIBUTING.md

Introduction

The Desktop Engineering Guidelines define the architectural invariants, state management principles, and visual contracts for the Jarvis-Glas desktop environment. The project is built as a native chat surface using Electron, React, and a dedicated TypeScript backend service. These guidelines ensure that as the application evolves, new features maintain technical integrity, performance, and a consistent user experience.

The core philosophy of the engineering guide is "Maximum Intelligence, Minimum Interruption," emphasizing a system that absorbs complexity in the background while presenting only essential information to the operator. The architecture is strictly separated into three authoritative parties: Electron for machine control, the Renderer for presentation, and the Agent Backend for core work and model orchestration.

Sources: instructions/AGENTS.md:10-18, instructions/GEMINI.md:3-8, SOUL.md:12-14

Core Architecture & Module Boundaries

The application follows a strict separation of concerns to maintain clean seams and prevent native capability leaks into the sandboxed renderer.

Authority and Responsibility

The system is divided into three primary layers, each authoritative over a specific domain:

• Electron (Main): Responsible for the machine lifecycle, including process management, native filesystem access, window management, and the IPC bridge.
• Renderer (Frontend): Manages the user experience, navigation, and ephemeral UI state. It is isolated behind a narrow, typed bridge and cannot access Node or Electron directly.
• Backend Service: Owns the agent workflows, sessions, model orchestration (Ollama/xAI), and persistent memory.

Sources: instructions/AGENTS.md:12-18, instructions/GEMINI.md:4-10

Structural Flow

The following diagram illustrates the high-level data flow and authority boundaries between the system components:

The diagram shows the isolation of the Renderer, which interacts with the machine layer only through a deliberate capability bridge.
Sources: instructions/AGENTS.md:15-22, instructions/GEMINI.md:5-9

State Management Principles

State in Jarvis-Glas is partitioned by authority rather than convenience. Every piece of state must live where it is "allowed to be right."

Authority Mapping

Entity	Authoritative State Domain
Backend	Anything shared across Jarvis surfaces (e.g., chat history, memory items).
Electron	Machine and runtime facts (e.g., connectivity, versioning).
Renderer	Purely presentation-related facts (e.g., local window scroll position, hover states).

Sources: instructions/AGENTS.md:23-32

Synchronization and Honesty

• Merge, don't clobber: New data from the backend should be layered over existing knowledge to prevent dropping live or pinned UI elements.
• Optimistic UI: Direct manipulations should paint immediately. If a network write fails, the UI must roll back visibly.
• Reference Identity: To optimize React performance, reference identity must be preserved on no-ops to prevent unnecessary tree re-renders.

Sources: instructions/AGENTS.md:45-56

Orb State & Visual Contract

The central Orb is a composite semantic system indicator, not merely decoration. It communicates the real-time status of the underlying agent subsystems.

Orb State Definitions

State	Meaning	Visual Language
idle	Core initialized; no work.	Muted cyan, slow orbit.
ready	Local service is healthy.	Luminous cyan/blue, steady pulse.
listening	Voice intake is active.	Green/cyan receptive pulse.
thinking	Model inference in progress.	Violet/blue fast orbit.
responding	TTS or text output active.	Bright cyan/green expansion.
error	Runtime fault detected.	Red high-contrast warning.

Sources: instructions/design-backend-prompt.txt:87-95, src/renderer.css:262-271

Orb Interaction Sequence

This sequence diagram shows how the Orb state transitions during a standard user interaction:

Diagram showing the visual state flow synchronized with backend activity.
Sources: instructions/design-backend-prompt.txt:87-95, instructions/AGENTS.md:58-62

Design System & HUD Primitives

The design follows a "Flat, not boxed" principle, utilizing Glassmorphism and high-tech HUD elements.

Token-Based Styling

All styling must use defined CSS variables (tokens) rather than literal values to ensure theme consistency and ease of maintenance.

Category	CSS Token Example	Usage
Stroke	--ui-stroke-tertiary	Default in-panel dividers and list hairlines.
Text	--ui-text-secondary	Secondary hierarchy text in the HUD.
Surface	--ui-bg-quaternary	Soft control fill for secondary buttons.
Shadow	--shadow-nous	Borderless elevation for floating panels.

Sources: instructions/DESIGN.md:38-44, src/renderer.css:22-35

Component Invariants

• Buttons: Must use the single source at src/components/ui/button.tsx with standard variants like default, secondary, and ghost.
• SearchField: Should be borderless with an underline-on-focus, avoiding boxed search bar styles.
• Elevation: Floating panels use shadow-nous and a --stroke-nous hairline for elevation without thick frames.

Sources: instructions/DESIGN.md:52-60, instructions/DESIGN.md:92-95

Development Workflow

Technical Stack

• Bundler: Bun (used for builds and script execution).
• Desktop Container: Electron.
• Language: TypeScript (strict mode preferred).
• Styling: CSS3 with Glassmorphic effects.

Sources: CONTRIBUTING.md:14-22, instructions/CONTEXT.md:10-18

Verification & Checklists

Before pushing changes, developers must:

1. Run bun run check or bun run build to verify types and build integrity.
2. Ensure no secrets are committed (API keys in .env are gitignored).
3. Update the conversation memory in .agent/CONVERSATION_MEMORY.md for relevant changes.
4. Verify that keyboard ownership and Esc key behavior remain correct for all overlays.

Sources: instructions/GEMINI.md:11-15, CONTRIBUTING.md:43-48, instructions/DESIGN.md:148-154

Conclusion

These engineering guidelines serve as the foundation for maintaining the "Living Architecture" of Jarvis-Glas. By adhering to the strict authority boundaries, token-based design primitives, and the "Silence Priority" communication model, developers can contribute to a robust and highly performant personal AI assistant.

Sources: instructions/design-backend-prompt.txt:1-5, SOUL.md:158-164