Architecture Overview
The architecture is split between thepalyra-connectors crate, which contains the generic provider logic and storage, and the palyra-daemon, which implements the ChannelPlatform to orchestrate these connectors within the daemon’s lifecycle.
System Components and Routing Flow
The following diagram illustrates how a message travels from an external platform into the Palyra ecosystem and back. Message Routing and Dispatch Sources: crates/palyra-daemon/src/channels.rs#135-169, crates/palyra-connectors/src/core/supervisor.rs#1-50, crates/palyra-connectors/tests/simulator_harness.rs#41-71ChannelPlatform and Supervisor
TheChannelPlatform is the central management point within the daemon. It initializes the ConnectorSupervisor, which manages the lifecycle of individual ConnectorInstance records and their associated worker loops.
- Initialization: The platform opens a dedicated SQLite database for connectors and initializes the
ConnectorSupervisorwith a set ofConnectorAdapterimplementations crates/palyra-daemon/src/channels.rs#142-169. - Worker Loop: A background worker periodically drains outbound queues and processes pending events at a configurable interval (default 1000ms) crates/palyra-daemon/src/channels.rs#65-65.
- Persistence: All inbound and outbound events, as well as dead-letter records, are stored in the
ConnectorStorecrates/palyra-connectors/src/core/storage.rs#1-30.
Message Routing (ChannelRouter)
Routing is handled by theConnectorRouter trait. In the daemon, this is implemented by GrpcChannelRouter, which translates connector events into gRPC calls targeted at the Gateway’s run lifecycle crates/palyra-daemon/src/channels.rs#154-155.
| Entity | Role |
|---|---|
InboundMessageEvent | Normalized representation of a message from any platform crates/palyra-connectors/src/core/protocol.rs#1-20. |
RouteInboundResult | Decision from the router on whether to accept a message and how to respond immediately crates/palyra-connectors/tests/simulator_harness.rs#48-70. |
ConnectorConversationTarget | Mapping of platform-specific IDs (e.g., Guild/Channel) to a unified conversation ID crates/palyra-connectors/src/core/protocol.rs#50-60. |
Provider Integrations
Palyra supports multiple provider types, though their implementation status varies:- Discord: Fully supported integration using webhooks and bot tokens. Includes complex governance for message mutations (edits/deletions) crates/palyra-daemon/src/channels/discord.rs#155-190.
- Echo: An internal test provider that simply reflects messages back to the sender, used for CI and local development crates/palyra-connectors/src/providers/mod.rs#19-19.
- Slack/Telegram: Currently defined as
Deferredavailability in the provider registry crates/palyra-connectors/src/providers/mod.rs#126-135.
Administrative and Console Interfaces
The daemon exposes APIs for managing channels through both the Admin and Console surfaces. Channel Management API Mapping Sources: crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#16-31, crates/palyra-daemon/src/transport/http/handlers/console/channels/mod.rs#14-24, crates/palyra-cli/src/commands/channels/mod.rs#30-56- CLI: Commands under
palyra channelsallow for adding, removing, and testing connectors crates/palyra-cli/src/commands/channels/mod.rs#30-100. - Web Console: Provides a visual interface for monitoring channel health, viewing message logs, and managing dead-letter queues crates/palyra-daemon/src/transport/http/handlers/console/channels/mod.rs#51-77.
- Governance: High-risk operations like deleting messages from a channel often require explicit approval through the
DiscordMessageMutationGovernancesystem crates/palyra-daemon/src/channels/discord.rs#179-190.