palyrad) and the browser automation service (palyra-browserd), provides a step-by-step onboarding experience for new users, and offers a “Companion UI” for quick interactions (chat, approvals, and health monitoring) without requiring the full web console.
Onboarding Sequence
The onboarding process is modeled as a linear state machine defined by theDesktopOnboardingStep enum apps/desktop/src-tauri/src/desktop_state.rs#209-219. The sequence ensures that the local environment is valid, services are initialized, and external integrations (OpenAI, Discord) are configured before the user reaches the dashboard.
Onboarding Steps
- Welcome: Initial landing and introduction apps/desktop/src-tauri/src/desktop_state.rs#210-210.
- Environment: Preflight checks for binary availability and port conflicts apps/desktop/src-tauri/src/onboarding.rs#199-206.
- StateRoot: Configuration of the
PALYRA_STATE_ROOTdirectory apps/desktop/src-tauri/src/desktop_state.rs#212-212. - GatewayInit: Initializing the
palyraddaemon and generating the admin token apps/desktop/src-tauri/src/desktop_state.rs#213-213. - OperatorAuthBootstrap: Establishing the initial admin session for the local UI apps/desktop/src-tauri/src/desktop_state.rs#214-214.
- OpenAiConnect / DiscordConnect: Optional steps for configuring LLM providers and messaging channels apps/desktop/src-tauri/src/desktop_state.rs#215-216.
- DashboardHandoff: Launching the full web console with a secure handoff token apps/desktop/src-tauri/src/desktop_state.rs#217-217.
- Completion: Onboarding finalized apps/desktop/src-tauri/src/desktop_state.rs#218-218.
Onboarding Logic Flow
Thebuild_onboarding_status function aggregates data from the ControlCenter and the palyrad admin API to determine the current progress apps/desktop/src-tauri/src/onboarding.rs#156-160.
Title: Desktop Onboarding State Transition
Sources: apps/desktop/src-tauri/src/commands.rs#83-92, apps/desktop/src-tauri/src/onboarding.rs#156-206, apps/desktop/src-tauri/src/desktop_state.rs#9-17
Tauri Command Layer
The desktop application uses Tauri’s IPC bridge to expose Rust-based management functions to the React frontend.Key Commands
| Command | Description | Source |
|---|---|---|
get_snapshot | Returns a full ControlCenterSnapshot including service status and redacted logs. | apps/desktop/src-tauri/src/commands.rs#54-62 |
get_desktop_companion_snapshot | Aggregates data for the Companion UI (sessions, approvals, inventory). | apps/desktop/src-tauri/src/commands.rs#108-123 |
send_desktop_companion_chat_message | Sends a message to a session; handles offline queuing if the daemon is down. | apps/desktop/src-tauri/src/companion.rs#327-370 |
open_dashboard | Generates a handoff URL and opens the system browser to the web console. | apps/desktop/src-tauri/src/snapshot.rs#320-337 |
Companion UI Data Flow
Theget_desktop_companion_snapshot command is the primary data source for the Companion UI. It calls build_companion_snapshot which utilizes a ControlPlaneClient to fetch data from the palyrad gRPC/HTTP surface apps/desktop/src-tauri/src/companion.rs#218-255.
Title: Companion UI Data Fetching
Sources: apps/desktop/ui/src/lib/desktopApi.ts#227-243, apps/desktop/src-tauri/src/commands.rs#108-123, apps/desktop/src-tauri/src/companion.rs#218-255
Offline Draft Queuing
To provide a resilient user experience, the Desktop Companion supports Offline Drafts. If thepalyrad daemon is unreachable or a message fails to send, the UI can queue the message locally.
- Storage: Drafts are stored in the
offline_draftsvector withinDesktopCompanionStateapps/desktop/src-tauri/src/desktop_state.rs#99-99. - Limit: The system enforces a limit of 20 offline drafts apps/desktop/src-tauri/src/desktop_state.rs#21-21.
- Behavior: When
send_desktop_companion_chat_messageis called withqueue_on_failure: true, a failure in the transport layer triggersqueue_offline_draftapps/desktop/src-tauri/src/companion.rs#356-363.
Desktop UI and Bridge
The UI is a Vite-powered React application apps/desktop/ui/index.html#12-12 using the HeroUI component library apps/desktop/ui/src/App.tsx#2-2.desktopApi.ts Bridge
ThedesktopApi.ts file acts as the typed interface between the TypeScript frontend and the Rust backend. It uses @tauri-apps/api/core to invoke commands apps/desktop/ui/src/lib/desktopApi.ts#1-1.
Key TypeScript Types:
DesktopCompanionSnapshot: The root data structure for the Companion UI apps/desktop/ui/src/lib/desktopApi.ts#227-243.ServiceProcessSnapshot: Describes the state ofpalyradorpalyra-browserdapps/desktop/ui/src/lib/desktopApi.ts#268-278.
UI Component Architecture
- App.tsx: The main entry point managing the
activeSectionstate (“home”, “chat”, “approvals”, “access”, “onboarding”) apps/desktop/ui/src/App.tsx#56-56. - useDesktopCompanion: A custom hook that handles periodic polling and data refreshing for the UI apps/desktop/ui/src/hooks/useDesktopCompanion.ts.
- HealthStrip: Displays the overall system status (
healthy,degraded,down) at the top of the window apps/desktop/ui/src/App.tsx#6-6.