palyrad backend through two distinct REST API surfaces: the Console API (/console/v1/*), which handles session-based operator actions, and the Admin API (/admin/v1/*), which provides low-level status and diagnostic data often consumed by the CLI and automated health probes.
Console Architecture & Data Flow
The console is organized into functional sections, each mapped to specific capabilities published by the daemon. TheConsoleSectionContent component acts as the primary router, switching between sections based on the app.section state apps/web/src/console/ConsoleSectionContent.tsx#26-108.
API Interaction Model
TheConsoleApiClient is the centralized service for all backend communication. It manages:
- Authentication: Consuming desktop handoff tokens or performing standard login apps/web/src/consoleApi.ts#1-200.
- CSRF Protection: Automatically attaching
x-palyra-csrf-tokenheaders to mutating requests (POST, PUT, DELETE) after a successful session is established apps/web/src/consoleApi.test.ts#44-90. - Automatic Retries: The
loadBootstrapSessionfunction implements exponential backoff for 429 (Rate Limited) and 401/403 (Auth) errors during initial boot apps/web/src/console/useConsoleAppState.tsx#88-107.
System State Mapping
The following diagram bridges the high-level UI sections to their corresponding backend API endpoints and data structures. Console Section to Code Entity Mapping Sources: apps/web/src/consoleApi.ts#124-130, apps/web/src/console/sections/OperationsSection.tsx#49-122, apps/web/src/console/sections/UsageSection.tsx#34-93Console Sections Detail
1. Overview & Capability Catalog
The Overview section provides a high-level summary of the deployment posture and available capabilities. It consumes theCapabilityCatalog, which defines what features are enabled and whether they require CLI handoff apps/web/src/console/fixtures/m56ControlPlane.ts#5-105.
2. Operations & Diagnostics
TheOperationsSection serves as the technical troubleshooting hub. It displays:
- Model Provider State: Health and failover status of LLM backends apps/web/src/console/sections/OperationsSection.tsx#125-130.
- Self-Healing: Active incidents and remediation attempts tracked by the daemon’s background monitor apps/web/src/console/sections/OperationsSection.tsx#156-160.
- Audit Events: A filtered view of security-relevant actions apps/web/src/console/sections/OperationsSection.tsx#31-36.
3. Usage & Token Tracking
TheUsageSection tracks metrics across three dimensions: Sessions, Agents, and Models.
- Data Aggregation: Totals for tokens, runs, and latency are calculated on the backend to avoid processing large datasets in the browser apps/web/src/console/sections/UsageSection.tsx#58-60.
- Cost Estimation: If cost tracking is available, the UI renders USD estimates based on the model mix apps/web/src/consoleApi.ts#107-108.
4. Channels & Router
TheChannelsSection manages external platform integrations (Discord, Slack, etc.).
- Dead Letter Management: Operators can replay or discard failed webhook deliveries apps/web/src/App.runtime-operations.test.tsx#98-110.
- Onboarding: Multi-step wizards for connector setup, including preflight checks apps/web/src/App.runtime-operations.test.tsx#129-140.
5. Config & Secrets
TheConfigSection and SecretsSection provide a safe interface for modifying palyrad.toml and the vault.
- Redaction: Sensitive values are masked by default in the UI unless explicitly revealed by the operator apps/web/src/App.config-access-support.test.tsx#137-143.
- Mutations: Changes are applied via the
/console/v1/config/mutateendpoint, which validates the TOML structure before persistence apps/web/src/App.config-access-support.test.tsx#54-59.
Admin API Surface
The Admin API (/admin/v1/*) is distinct from the Console API as it often bypasses standard session cookies in favor of Bearer tokens, making it suitable for CLI and inter-process communication.
| Endpoint | Method | Purpose | Source |
|---|---|---|---|
/admin/v1/status | GET | Returns daemon health, gRPC ports, and auth requirements. | crates/palyra-daemon/tests/admin_surface.rs#30-72 |
/admin/v1/journal/recent | GET | Fetches recent events from the SQLite JournalStore. | crates/palyra-daemon/tests/admin_surface.rs#75-107 |
/admin/v1/policy/explain | GET | Evaluates a Cedar policy against a specific principal/action/resource. | crates/palyra-daemon/tests/admin_surface.rs#110-149 |
Security Headers
All Admin API responses are required to include strict security headers to prevent framing and content sniffing:X-Content-Type-Options: nosniffX-Frame-Options: DENYContent-Security-Policy: frame-ancestors 'none'crates/palyra-daemon/tests/admin_surface.rs#44-65
Authentication & Handoff Flow
The console supports a “Desktop Handoff” mechanism where the Tauri-based desktop app generates a short-lived token, allowing the user to open the web dashboard in a standard browser without re-authenticating. Authentication Sequence Sources: apps/web/src/App.test.tsx#69-107, apps/web/src/console/useConsoleAppState.tsx#109-123, apps/web/src/consoleApi.test.ts#44-53Auto-Refresh Logic
To maintain up-to-date diagnostics without overloading the backend, the console implements a section-aware TTL (Time-To-Live) for data. Sections likechannels and operations refresh every 8-10 seconds, while config and secrets have a longer 15-second TTL apps/web/src/console/useConsoleAppState.tsx#42-54.
Sources: