<!-- source: https://deepwiki.com/qhkm/zeptoclaw/7.1-channel-architecture -->

# Channel Architecture

- Cargo.lock
- Cargo.toml
- src/channels/factory.rs
- src/channels/manager.rs
- src/channels/mod.rs
- src/channels/types.rs
- src/cli/channel.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/watcher.rs

## Purpose and Scope

The ZeptoClaw Channel Architecture provides a unified abstraction for communication platforms, enabling the agent to interact with users across Telegram, Slack, Discord, WhatsApp, Lark, and Webhooks through a consistent interface. At its core, the `Channel` trait decouples platform-specific protocol handling (HTTP, WebSockets, long-polling, etc.) from the internal `MessageBus` and `AgentLoop`. [src/channels/mod.rs1-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L1-L27) [src/channels/types.rs1-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L1-L18)

This architecture handles:

- Message Ingestion : Receiving and normalizing platform-specific events into InboundMessage structures. src/channels/types.rs 11-18
- Message Delivery : Routing OutboundMessage responses from agents back to the correct platform and chat. src/channels/manager.rs 1-8
- Access Control : Enforcing per-channel allowlists and "deny-by-default" security policies. src/channels/types.rs 112-118
- Lifecycle Management : Standardized startup, shutdown, and supervised reconnection logic via the ChannelManager . src/channels/manager.rs 106-164
- Background Tasks : Integration with CronService and HeartbeatService to inject synthetic messages into the bus. src/cron/mod.rs 14-15 src/heartbeat/service.rs 12-14

**Sources:** [src/channels/mod.rs1-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L1-L27) [src/channels/types.rs1-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L1-L18) [src/channels/manager.rs1-8](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L1-L8) [src/channels/types.rs112-118](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L112-L118) [src/channels/manager.rs106-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L106-L164) [src/cron/mod.rs14-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L14-L15) [src/heartbeat/service.rs12-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L12-L14)

## Channel Trait Interface

The `Channel` trait defines the behavioral contract for all communication adapters. Every supported platform must implement this trait to integrate with the system. [src/channels/types.rs63-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L63-L110)

**Channel Entity Space**

```

```

**Sources:** [src/channels/types.rs63-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L63-L110) [src/channels/mod.rs134-152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L134-L152)

## ChannelManager and Registration Flow

The `ChannelManager` acts as the central supervisor for all active channels. It maintains a registry of `SharedChannel` (an `Arc<Mutex<Box<dyn Channel>>>`) and coordinates their lifecycle. [src/channels/manager.rs23-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L23-L24) [src/channels/manager.rs86-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L86-L104)

### Registration Process

Channels are typically registered during system initialization via `register_configured_channels`. This function inspects the global `Config` and instantiates enabled channels. [src/channels/factory.rs23-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L23-L27)

```

```

**Sources:** [src/channels/factory.rs23-46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L23-L46) [src/channels/manager.rs106-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L106-L164) [src/cli/gateway.rs10-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L10-L11)

## Supervision and Health Monitoring

The `ChannelManager` includes a background supervisor task that periodically checks the health of registered channels. [src/channels/manager.rs102-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L102-L103)

### Supervisor Logic

- Polling : The supervisor runs every 15 seconds ( SUPERVISOR_POLL_SECS ). src/channels/manager.rs 26
- Detection : It calls is_running() on every registered channel. src/channels/manager.rs 335
- Recovery : If a channel is down but was supposed to be started, the supervisor attempts to restart it, up to 5 times ( SUPERVISOR_MAX_RESTARTS ), with a 60-second cooldown ( SUPERVISOR_COOLDOWN_SECS ) between attempts. src/channels/manager.rs 28-30 src/channels/manager.rs 340-360
- Health Registry : Status changes are reported to the HealthRegistry if configured. src/channels/manager.rs 101 src/channels/manager.rs 141-143

**Sources:** [src/channels/manager.rs25-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L25-L37) [src/channels/manager.rs316-368](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L316-L368)

## Access Control and Allowlists

Access control is standardized through the `BaseChannelConfig` struct. This allows administrators to restrict agent access on a per-channel basis using user identifiers (e.g., Telegram User IDs, Slack Member IDs). [src/channels/types.rs139-147](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L139-L147)

**Access Control Modes**

**Sources:** [src/channels/types.rs139-147](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L139-L147) [src/channels/types.rs198-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L198-L206)

### Implementation in Code

Each channel implementation calls `self.base_config.is_allowed(user_id)` within its `is_allowed` trait method to determine if an incoming message should be processed or dropped. [src/channels/types.rs198-230](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L198-L230)

**Sources:** [src/channels/types.rs198-230](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L198-L230)

## Message Flow Architecture

Channels act as the bridge between the external world and the internal `MessageBus`. They translate raw platform payloads into `InboundMessage` and vice versa. [src/channels/mod.rs9-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L9-L27)

```

```

**Sources:** [src/channels/mod.rs9-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L9-L27) [src/channels/types.rs11-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L11-L18) [src/cron/mod.rs14-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L14-L15) [src/heartbeat/service.rs12-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L12-L14)

## CLI Management

The system provides CLI utilities to manage and debug channels via the `zeptoclaw channel` command group. [src/cli/channel.rs25-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/channel.rs#L25-L31)

**Sources:** [src/cli/channel.rs1-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/channel.rs#L1-L31)

## Implementation Patterns

### Reconnection and Resilience

Stateful channels like `SlackChannel` (Socket Mode) or `LarkChannel` (WS long-connection) implement supervised loops. If the WebSocket connection drops, the internal task attempts to reconnect while respecting the `is_running` state managed by the `ChannelManager`. [src/channels/manager.rs6-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L6-L7) [src/channels/lark.rs164-177](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/lark.rs#L164-L177)

### Feature Gating

The channel factory ensures that only features compiled into the binary are activated. For example, the `whatsapp-web` channel requires the `whatsapp-web` feature flag; if enabled in config but missing in the binary, a warning is emitted. [src/channels/factory.rs119-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L119-L139)

**Sources:** [src/channels/factory.rs119-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/factory.rs#L119-L139) [src/channels/mod.rs120-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/mod.rs#L120-L132)

### Async Trait Usage

Because channel operations involve network I/O, the `Channel` trait uses `#[async_trait]`. This allows the `ChannelManager` to await `start()`, `stop()`, and `send()` calls across different implementations. [src/channels/types.rs62-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L62-L110)

**Sources:** [src/channels/types.rs62-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/types.rs#L62-L110)
