src-tauri) serves as the orchestration layer for the Palyra Desktop application. It is responsible for the lifecycle management of sidecar processes (palyrad and palyra-browserd), managing persisted application state, and providing a secure IPC bridge between the desktop UI and the underlying system services.
Architecture Overview
The backend is built around theControlCenter struct, which acts as the central supervisor for all desktop operations. It coordinates process execution, health monitoring, and state persistence.
Key Components
- Supervisor: Manages the lifecycle of
palyrad(Gateway) andpalyra-browserd(Browser) sidecars apps/desktop/src-tauri/src/supervisor.rs#201-218. - State Management: Handles encrypted storage of admin tokens and application preferences using a SQLite-backed vault apps/desktop/src-tauri/src/desktop_state.rs#231-232.
- IPC Commands: Defines the
tauri::commandendpoints that the React frontend consumes to interact with the system apps/desktop/src-tauri/src/commands.rs#53-180. - Companion Bridge: Provides a high-level abstraction for chat sessions, notifications, and approvals, bridging the desktop UI to the Daemon’s gRPC/HTTP interfaces apps/desktop/src-tauri/src/companion.rs#51-67.
Data Flow: Frontend to Sidecar
The following diagram illustrates how a command from the UI (e.g., sending a message) traverses the Tauri backend to reach the managed sidecar. Sources: apps/desktop/ui/src/lib/desktopApi.ts#31, apps/desktop/src-tauri/src/commands.rs#215-220, apps/desktop/src-tauri/src/companion.rs#119-130Sidecar Supervision (supervisor.rs)
The supervisor.rs module implements the ManagedService logic. It ensures that required binaries are present, starts them with correct environment variables (e.g., PALYRA_ADMIN_TOKEN), and captures their stdout/stderr for diagnostic logging apps/desktop/src-tauri/src/supervisor.rs#97-107.
Process Lifecycle
The supervisor runs a tick every 500ms to check process health and perform backoff-based restarts if a service crashes apps/desktop/src-tauri/src/lib.rs#1.| Service | Binary Name | Default Ports |
|---|---|---|
| Gateway | palyrad | Admin: 7142, gRPC: 7443, QUIC: 7444 |
| Browserd | palyra-browserd | Health: 7143, gRPC: 7543 |
Code Entity Relationship: Supervision
Sources: apps/desktop/src-tauri/src/supervisor.rs#201-218, apps/desktop/src-tauri/src/supervisor.rs#97-107, apps/desktop/src-tauri/src/supervisor.rs#30-33Desktop State and Persistence (desktop_state.rs)
The application state is split between a standard JSON file for preferences and a secure vault for sensitive tokens.
- State File:
state.jsonstores non-sensitive data likeDesktopCompanionSection(Home, Chat, Approvals), onboarding progress, and notification history apps/desktop/src-tauri/src/desktop_state.rs#25-31. - Secret Store:
DesktopSecretStoremanages thedesktop_admin_tokenanddesktop_browser_auth_tokenusingpalyra-vaultapps/desktop/src-tauri/src/lib.rs#11-12. - Onboarding Steps: Tracks the state machine for setup, including
Welcome,StateRootselection, andOpenAiConnectapps/desktop/src-tauri/src/desktop_state.rs#209-219.
IPC Commands (commands.rs)
Commands are the primary interface for the frontend. Key categories include:
- System Snapshots:
get_snapshotandget_desktop_companion_snapshotprovide a unified view of process health, logs, and agent sessions apps/desktop/src-tauri/src/commands.rs#54-62, apps/desktop/src-tauri/src/commands.rs#108-123. - Process Control: Commands to start/stop sidecars and update preferences apps/desktop/src-tauri/src/commands.rs#154-162.
- Onboarding:
set_onboarding_state_root_commandallows users to select where Palyra stores its runtime data apps/desktop/src-tauri/src/commands.rs#135-151. - Companion Interaction:
send_companion_chat_message_commandanddecide_companion_approval_commandbridge to thepalyradgRPC API apps/desktop/src-tauri/src/commands.rs#215-231.
Diagnostics and Snapshots (snapshot.rs)
The snapshot.rs module aggregates data from multiple sources to provide the UI with a comprehensive status update.
ControlCenterSnapshot: IncludesOverallStatus(Healthy, Degraded, Down),QuickFacts(versions, uptimes), and redacted logs apps/desktop/src-tauri/src/snapshot.rs#173-182.- Redaction: Logs and URLs are passed through
sanitize_log_lineto ensure no sensitive tokens are leaked to the UI or support bundles apps/desktop/src-tauri/src/snapshot.rs#33, apps/desktop/src-tauri/src/snapshot.rs#15-16. - Observability: Tracks failure rates for provider auth, connector queues, and browser relays apps/desktop/src-tauri/src/snapshot.rs#107-115.
Onboarding Logic (onboarding.rs)
The onboarding flow is a guided process that ensures the environment is ready for operation.
- Preflight Checks: Verifies binary existence, port availability, and directory permissions before starting services apps/desktop/src-tauri/src/onboarding.rs#27-32.
- Recovery: If a step fails, the
OnboardingRecoverySnapshotprovides error details and suggested actions apps/desktop/src-tauri/src/onboarding.rs#56-61. - Handoff: Once local services are running, the backend generates a
dashboard_urlwith a one-time admin token to “hand off” the user to the full Web Console apps/desktop/src-tauri/src/onboarding.rs#90-93.