Architecture and Data Flow
The Desktop UI follows a reactive state-management pattern where the frontend periodically polls the Tauri backend for a unified system snapshot.Implementation Overview
- Frontend Framework: React with Vite and Tailwind CSS apps/desktop/ui/index.html#1-15.
- UI Components: Built using
@heroui/react(formerly NextUI) for consistent design apps/desktop/ui/src/App.tsx#2-20. - IPC Bridge:
desktopApi.tsprovides a typed interface for calling Rust commands via Tauri’sinvokeapps/desktop/ui/src/lib/desktopApi.ts#1-2. - State Management: The
useDesktopCompanionhook manages the lifecycle of fetchingDesktopCompanionSnapshotdata apps/desktop/ui/src/hooks/useDesktopCompanion.ts#27-105.
Data Flow Diagram
The following diagram illustrates how the UI synchronizes with the underlying Rust services. Sources: apps/desktop/ui/src/hooks/useDesktopCompanion.ts#18-101, apps/desktop/ui/src/lib/desktopApi.ts#50-51, apps/desktop/src-tauri/src/companion.rs#51-67Core Entities and Types
The frontend interacts with several key data structures defined in thedesktopApi.ts bridge, which mirror the Rust structs in companion.rs.
| Code Entity (TypeScript) | Source File | Description |
|---|---|---|
DesktopCompanionSnapshot | apps/desktop/ui/src/lib/desktopApi.ts#227-243 | The root state object containing metrics, sessions, and status. |
SessionCatalogRecord | apps/desktop/ui/src/lib/desktopApi.ts#62-81 | Represents an agent session with token counts and last intent. |
DesktopCompanionNotification | apps/desktop/ui/src/lib/desktopApi.ts#19-26 | System notifications (approvals, connections, runs). |
InventoryDeviceRecord | apps/desktop/ui/src/lib/desktopApi.ts#147-175 | Details about paired devices and their trust states. |
Key Frontend Components
1. useDesktopCompanion Hook
This hook is the engine of the UI. It implements a polling loop that adjusts its frequency based on the connection state:
- Active Interval: 5 seconds when connected apps/desktop/ui/src/hooks/useDesktopCompanion.ts#18.
- Idle Interval: 12 seconds when offline or reconnecting apps/desktop/ui/src/hooks/useDesktopCompanion.ts#19.
2. Main Shell (App.tsx)
The App component manages navigation between sections: home, chat, approvals, access, and onboarding apps/desktop/ui/src/App.tsx#44-50. It also handles:
- Window Handoff: Automatically reveals the main window when the host is available apps/desktop/ui/src/App.tsx#153-164.
- Preference Persistence: Syncs the active section and session ID back to the backend apps/desktop/ui/src/App.tsx#141-151.
- Notifications: Triggers native desktop notifications using the Web Notification API apps/desktop/ui/src/App.tsx#170-185.
3. IPC Bridge (desktopApi.ts)
This file abstracts Tauri’s invoke calls into asynchronous TypeScript functions. Key functions include:
sendDesktopCompanionChatMessage: Sends user input to a specific session apps/desktop/ui/src/lib/desktopApi.ts#31.decideDesktopCompanionApproval: Submits a human-in-the-loop decision for tool execution apps/desktop/ui/src/lib/desktopApi.ts#22.restartPalyra: Triggers a full service restart via the supervisor apps/desktop/ui/src/lib/desktopApi.ts#30.
Onboarding and Discord Setup
The onboarding wizard is a specialized flow within the Companion Shell that guides the user through initial configuration.Implementation Details
- State Tracking: The
OnboardingStatusSnapshottracksprogress_completedandprogress_totalapps/desktop/ui/src/lib/desktopApi.ts#197-208. - Discord Connector: Setup is handled as a phase within the onboarding snapshot, often requiring the user to provide bot tokens or authorize via OAuth apps/desktop/src-tauri/src/companion.rs#54.
- Dashboard Handoff: Once local setup is complete, the UI facilitates a handoff to the web-based dashboard apps/desktop/ui/src/lib/desktopApi.ts#203.
Control Center and Launcher
The “Home” section acts as a Control Center, providing a high-level view of system health and process status.System Monitoring
The UI displays the status of sidecar processes (likepalyrad and palyra-browserd) using the ServiceProcessSnapshot apps/desktop/ui/src/lib/desktopApi.ts#268-272.
- Metrics: Displays unread notifications, pending approvals, and active sessions apps/desktop/ui/src/lib/desktopApi.ts#217-225.
- Quick Facts: Shows gateway version, git hash, and browser service health apps/desktop/ui/src/lib/desktopApi.ts#253-260.