Skip to main content
The Desktop UI serves as the primary operator interface for the Palyra Desktop Companion. It is a Vite-powered React application hosted within a Tauri container, providing a bridge between the user and the palyrad (Gateway) and palyra-browserd (Browser) sidecar services. The onboarding flow is a critical multi-step wizard that ensures the local environment is correctly configured before the daemon is fully operational.

​
Desktop UI Architecture

The UI is built using React and Tailwind CSS, communicating with the Rust backend via Tauri’s IPC mechanism (invoke). The application state is primarily driven by a “Snapshot” model, where the UI periodically polls the backend for the complete state of the supervisor and managed services.

​
Key Components

ComponentRole
App.tsxMain entry point; manages routing between Home, Chat, Approvals, and Onboarding sections apps/desktop/ui/src/App.tsx#52-56.
useDesktopCompanion.tsCustom hook that handles polling get_desktop_companion_snapshot and managing refresh intervals apps/desktop/ui/src/App.tsx#20.
desktopApi.tsTypeScript bridge defining the types and wrappers for Tauri commands apps/desktop/ui/src/lib/desktopApi.ts#1-3.

​
Communication Flow: UI to Backend

The UI interacts with the ControlCenter supervisor through a set of commands defined in commands.rs. Sources: apps/desktop/ui/src/lib/desktopApi.ts#1-2, apps/desktop/src-tauri/src/commands.rs#53-62, apps/desktop/src-tauri/src/supervisor.rs#201-218

​
Onboarding Wizard Flow

The onboarding process is managed by the DesktopOnboardingStep state machine. It guides the user through environment validation, state root selection, and external service connection (OpenAI/Discord).

​
Onboarding Steps (DesktopOnboardingStep)

The sequence is defined as follows:
  1. Welcome: Initial landing and terms acknowledgement apps/desktop/src-tauri/src/desktop_state.rs#210.
  2. Environment: Validation of system dependencies and ports apps/desktop/src-tauri/src/desktop_state.rs#211.
  3. State Root: Selecting the directory for persistence (e.g., ~/palyra-data) apps/desktop/src-tauri/src/desktop_state.rs#212.
  4. Gateway Init: Bootstrapping the palyrad daemon and generating local identity apps/desktop/src-tauri/src/desktop_state.rs#213.
  5. Operator Auth: Establishing the initial admin token apps/desktop/src-tauri/src/desktop_state.rs#214.
  6. OpenAI Connect: Configuring LLM provider credentials apps/desktop/src-tauri/src/desktop_state.rs#215.
  7. Discord Connect: Optional setup for the Discord connector apps/desktop/src-tauri/src/desktop_state.rs#216.
  8. Dashboard Handoff: Transitioning the user to the full Web Console apps/desktop/src-tauri/src/desktop_state.rs#217.

​
Preflight Checks

Before proceeding, the build_onboarding_status function runs preflight checks to ensure ports (7142, 7443, etc.) are available and binaries are executable apps/desktop/src-tauri/src/onboarding.rs#156-200. Sources: apps/desktop/src-tauri/src/desktop_state.rs#209-219, apps/desktop/src-tauri/src/onboarding.rs#78-110

​
Discord Connector Onboarding

Discord onboarding is a specialized sub-flow that requires verifying permissions and connectivity for the Discord bot connector. Sources: apps/desktop/src-tauri/src/commands.rs#16-20, apps/desktop/src-tauri/src/lib.rs#40

​
Browser Handoff and Dashboard

The Desktop Companion often acts as a launcher for the more feature-rich Web Console. This is handled via the “Handoff” mechanism.
  1. Token Generation: The supervisor generates a short-lived admin token.
  2. URL Construction: build_dashboard_open_url creates a loopback URL (typically http://127.0.0.1:7142) with the auth token embedded apps/desktop/src-tauri/src/snapshot.rs#31.
  3. Handoff: The open_external_browser command (or Tauri’s shell API) opens the system browser to the console apps/desktop/src-tauri/src/commands.rs#24.
Sources: apps/desktop/src-tauri/src/snapshot.rs#30-34, apps/desktop/src-tauri/src/commands.rs#22-29

​
Technical Implementation: desktopApi.ts

The bridge defines TypeScript interfaces that mirror the Rust structs to ensure type safety across the IPC boundary.

​
Core Types

TypeDescription
DesktopCompanionSnapshotThe root state object containing control_center, onboarding, and metrics apps/desktop/ui/src/lib/desktopApi.ts#227-243.
OnboardingStatusSnapshotCurrent phase and progress of the onboarding wizard apps/desktop/ui/src/lib/desktopApi.ts#197-208.
ServiceProcessSnapshotReal-time status of palyrad or palyra-browserd (PID, uptime, ports) apps/desktop/ui/src/lib/desktopApi.ts#268-279.

​
Data Flow Diagram

Sources: apps/desktop/ui/src/lib/desktopApi.ts#197-208, apps/desktop/src-tauri/src/commands.rs#83-92, apps/desktop/src-tauri/src/onboarding.rs#120-134, apps/desktop/src-tauri/src/supervisor.rs#201-218