Architecture Overview
The integration between the daemon and external platforms is managed by theChannelPlatform crates/palyra-daemon/src/channels.rs#148-152. It encapsulates a ConnectorSupervisor which manages the lifecycle of individual connector instances.
Key Components
| Component | Role | Location |
|---|---|---|
| ChannelPlatform | Top-level daemon sub-system for channel management. | palyra-daemon |
| ConnectorSupervisor | Manages connector state, outbox queuing, and retries. | palyra-connector-core |
| ConnectorStore | SQLite-backed persistence for connector configuration and message history. | palyra-connector-core |
| ConnectorAdapter | Trait-based interface implemented by specific platforms (e.g., Discord). | palyra-connector-core |
| ChannelRouter | Routes inbound messages from connectors into the agent gateway. | palyra-daemon |
Data Flow: External to Internal
The following diagram illustrates how a message from an external platform (like Discord) reaches the Palyra Agent Gateway. Message Ingress Flow Sources: crates/palyra-daemon/src/channels.rs#167-174, crates/palyra-connector-discord/src/adapter.rs#77-118, crates/palyra-connector-core/tests/simulator_harness.rs#41-71Connector Framework
Thepalyra-connector-core crate defines the standard interface for all integrations. It uses a trait-based approach to ensure that the daemon can interact with any platform without knowing its internal implementation details.
- ConnectorAdapter Trait: Defines methods for
send_outbound,capabilities, andruntime_snapshotcrates/palyra-connector-discord/src/adapter.rs#77-166. - Reliability Layer: The supervisor handles exponential backoff, rate limiting (via
RetryClass::RateLimit), and “dead letter” handling for messages that fail permanently crates/palyra-connector-core/tests/simulator_harness.rs#140-154. - Idempotency: Connectors use
envelope_idto ensure that retried requests do not result in duplicate messages on the target platform crates/palyra-connectors/src/connectors/echo.rs#145-163.
Discord Integration
The Discord connector is the primary reference implementation of theConnectorAdapter. It supports:
- Real-time Ingress: Uses the Discord Gateway (WebSocket) to receive messages instantly crates/palyra-connector-discord/src/adapter.rs#44-55.
- Message Mutation: Supports editing, deleting, and reacting to messages, governed by a risk-based approval system crates/palyra-daemon/src/channels/discord.rs#61-141.
- Attachment Handling: Manages file uploads and downloads between Discord and the daemon’s internal
MediaArtifactStorecrates/palyra-daemon/src/channels.rs#162-166.
Governance & Approvals
Because connectors can perform destructive actions (like deleting messages), theChannelPlatform implements a governance layer. Before a mutation is executed, it is classified by risk level:
- Low Risk: Editing a fresh message authored by the bot in a private channel crates/palyra-daemon/src/channels/discord.rs#78-84.
- High/Critical Risk: Deleting messages or modifying old content in public channels crates/palyra-daemon/src/channels/discord.rs#98-102.
ApprovalRecord in the JournalStore, requiring human intervention via the Web Console before the ConnectorSupervisor releases the message from the outbox crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#20-22.
Entity Mapping: Governance to Code
Sources: crates/palyra-daemon/src/channels/discord.rs#61-66, crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#1-18
Management API
The daemon exposes administrative endpoints for monitoring channel health and managing the connector inventory:GET /admin/v1/channels: Lists all configured connectors and their status crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#22-37.- Health Snapshots: Provides detailed metrics on queue depth, rate limits, and “dead letters” (messages that failed all retry attempts) crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#124-158.