Skip to main content
The Desktop UI is a React-based Single Page Application (SPA) bundled within a Tauri container. It serves as the primary “Control Center” for the Palyra desktop experience, providing a unified interface for daemon management, real-time chat, tool approval workflows, and device inventory. It communicates with the Tauri Rust backend via asynchronous IPC commands and maintains a local state synchronized with the daemon’s status.

​
Core Architecture and Data Flow

The Desktop UI follows a unidirectional data flow pattern where the frontend consumes a comprehensive DesktopCompanionSnapshot apps/desktop/ui/src/lib/desktopApi.ts#227-243 provided by the backend.

​
The Synchronization Loop

The useDesktopCompanion hook manages the lifecycle of data fetching. It implements an adaptive polling mechanism that adjusts based on the connection state: The hook uses getDesktopCompanionSnapshot apps/desktop/ui/src/lib/desktopApi.ts#50 to invoke the Tauri command and updates the React state via startTransition to maintain UI responsiveness apps/desktop/ui/src/hooks/useDesktopCompanion.ts#52-56.

​
Desktop API Bridge

The desktopApi.ts file acts as the translation layer between the TypeScript frontend and the Rust backend. It uses Tauri’s invoke apps/desktop/ui/src/lib/desktopApi.ts#1 to call commands defined in the src-tauri crate.
FunctionPurposeBackend Entity
getDesktopCompanionSnapshotFetches the full UI state.get_desktop_companion_snapshot
sendDesktopCompanionChatMessageDispatches user input to the agent.send_desktop_companion_chat_message
decideDesktopCompanionApprovalSubmits a Human-in-the-loop decision.decide_desktop_companion_approval
updateDesktopCompanionPreferencesPersists UI state (active tab, etc).update_desktop_companion_preferences
Sources: apps/desktop/ui/src/hooks/useDesktopCompanion.ts#27-104, apps/desktop/ui/src/lib/desktopApi.ts#1-243

​
Component Hierarchy and Navigation

The App.tsx file serves as the root layout and state coordinator. It manages several UI-specific states that are not persisted in the daemon, such as active session selections and draft message content.

​
System Navigation

The UI is divided into five primary sections defined by DesktopCompanionSection apps/desktop/ui/src/lib/desktopApi.ts#17:
  1. Home: System health, process monitors, and quick facts.
  2. Chat: Real-time interaction with the agent and session management.
  3. Approvals: Queue for pending tool execution requests.
  4. Access: Inventory of paired devices and their trust states.
  5. Onboarding: Guided setup for external connectors (e.g., Discord).

​
State Synchronization Diagram

This diagram bridges the React App state with the underlying Rust DesktopCompanionSnapshot. Title: Desktop UI State Mapping Sources: apps/desktop/ui/src/App.tsx#52-135, apps/desktop/src-tauri/src/companion.rs#51-67

​
Companion Shell and Styling

The UI is designed to feel like a native desktop utility rather than a standard web page. This is achieved through specific CSS variables and layout constraints defined in styles.css.

​
Visual Constraints

​
Native Integration Features

The UI interacts with native OS features through the Tauri bridge:
  • Notifications: The App component monitors the unreadNotifications array in the snapshot and triggers the Web Notification API when new items appear apps/desktop/ui/src/App.tsx#170-185.
  • Window Visibility: Upon initialization, the UI calls showMainWindow() to ensure the Tauri window is visible to the user only after the initial state is loaded apps/desktop/ui/src/App.tsx#153-168.
Sources: apps/desktop/ui/src/styles.css#7-72, apps/desktop/ui/index.html#1-15, apps/desktop/ui/src/App.tsx#170-185

​
Onboarding and Connector Flows

The Onboarding section apps/desktop/ui/src/lib/desktopApi.ts#197-208 is a specialized state machine that guides the user through complex setup tasks, such as Discord bot integration.

​
Data Flow for Discord Onboarding

This diagram illustrates how the UI coordinates between the user, the Tauri backend, and the Palyra daemon during onboarding. Title: Discord Connector Onboarding Flow

​
Onboarding Progress Tracking

The UI calculates progress using progress_completed and progress_total from the snapshot apps/desktop/ui/src/App.tsx#96. If a failure occurs during setup, the recovery object apps/desktop/ui/src/lib/desktopApi.ts#205-207 provides a user-facing error message to help resolve configuration issues. Sources: apps/desktop/ui/src/lib/desktopApi.ts#197-208, apps/desktop/ui/src/App.tsx#96, apps/desktop/src-tauri/src/companion.rs#54