<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3.1-system-components -->

# System Components

- AGENTS.md
- CLAUDE.md
- src/bus/message.rs
- src/bus/mod.rs
- src/cli/common.rs
- src/lib.rs
- src/session/mod.rs
- src/session/types.rs
- src/tools/mod.rs

This page provides a technical overview of ZeptoClaw's major subsystems, their implementation details, and how they interact to form a cohesive agentic system. ZeptoClaw is structured as a modular Rust library with approximately 30 top-level modules [src/lib.rs1-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L44)

## Overview

ZeptoClaw follows a **trait-based abstraction** pattern to enable pluggable implementations for its core capabilities:

- Communication : Channel trait for various chat platforms src/lib.rs 50-53
- Intelligence : LLMProvider trait for model backends (Anthropic, OpenAI, etc.) src/lib.rs 58-61
- Action : Tool trait for capabilities like filesystem access and shell execution src/lib.rs 94-100
- Isolation : ContainerRuntime trait for secure execution environments src/lib.rs 62-65

### Code Entity Space Mapping

The following diagram bridges the high-level system concepts to their specific implementation structures in the codebase.

```

```

**Sources:** [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [src/bus/mod.rs63-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/mod.rs#L63-L72) [src/session/mod.rs62-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L62-L67) [src/tools/mod.rs10-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L10-L13) [src/audit.rs95-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L95-L96)

## Core Subsystems

### 1. MessageBus and Routing

The `MessageBus` is the central async communication hub. It uses `tokio::sync::mpsc` channels to decouple message sources (Channels) from processors (Agents) [src/bus/mod.rs63-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/mod.rs#L63-L72)

- Inbound Pipeline : Channels (Telegram, Slack, etc.) publish InboundMessage objects to the bus src/bus/mod.rs 134-139
- Outbound Pipeline : Agents publish OutboundMessage objects which are consumed by the appropriate channel for delivery src/bus/mod.rs 193-198
- Session Keys : Every message is routed using a session_key formatted as channel:chat_id src/bus/message.rs 97
- Media Support : The bus supports MediaAttachment for images, audio, video, and documents src/bus/message.rs 46-70

**Sources:** [src/bus/mod.rs1-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/mod.rs#L1-L110) [src/bus/message.rs11-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L11-L42) [src/bus/message.rs46-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/message.rs#L46-L70)

### 2. AgentLoop

The `AgentLoop` is the primary orchestrator for a single conversation. It manages the iterative "Think-Act-Observe" cycle [src/agent/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/mod.rs)

- Context Building : Uses ContextBuilder to assemble system prompts, conversation history, and memory injections src/agent/context.rs
- Compaction : Implements three-tier compaction (Normal/Emergency/Critical at 70%/90%/95%) to stay within model token limits AGENTS.md 50
- Tool Execution : Routes tool calls through the ToolRegistry and handles the results back into the conversation history.
- Convergence : Agent loop, MCP server, and embedded ZeptoAgent all route through kernel::execute_tool() for shared safety scanning, taint checks, and metrics AGENTS.md 40 CLAUDE.md 89

**Sources:** [src/agent/loop.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs) [AGENTS.md40-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L50) [CLAUDE.md89](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L89-L89)

### 3. ToolRegistry and Execution

The `ToolRegistry` manages the lifecycle and discovery of tools [src/tools/registry.rs128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L128-L128)

**Sources:** [src/tools/mod.rs1-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L13) [src/tools/types.rs122-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L122-L166) [src/tools/registry.rs128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L128-L128)

### 4. SessionManager

The `SessionManager` provides persistence for conversation state [src/session/mod.rs62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L62-L62)

- Storage : Supports file-based persistence in ~/.zeptoclaw/sessions/ using JSON serialization src/session/mod.rs 86
- Repair : Includes repair_messages logic to fix malformed histories (e.g., duplicate assistant messages or orphaned tool results) src/session/mod.rs 35
- Thread Safety : Uses Arc<RwLock<HashMap<String, Session>>> for concurrent access across async tasks src/session/mod.rs 64

**Sources:** [src/session/mod.rs1-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L1-L110) [src/session/types.rs14-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/types.rs#L14-L25)

### 5. LLM Providers

The provider system uses a registry-based approach to resolve model backends [src/providers/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs)

- Resolution : resolve_runtime_providers builds a chain based on configuration src/cli/common.rs 15-17
- Decorators : Providers can be wrapped in RetryProvider (for exponential backoff) or FallbackProvider (for high availability) AGENTS.md 21
- OpenAI Parity : The /v1/chat/completions serve path forwards tools and returns OpenAI-style payloads, including streaming tool-call deltas AGENTS.md 25

**Sources:** [src/providers/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs) [src/cli/common.rs113-116](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L113-L116) [AGENTS.md21-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L21-L25)

## Data Flow: Channel to Agent

This diagram illustrates the flow of a message from an external platform through the system components to an LLM provider and back.

```

```

**Sources:** [src/bus/mod.rs134-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bus/mod.rs#L134-L210) [src/agent/loop.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/loop.rs) [src/session/mod.rs160-189](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/session/mod.rs#L160-L189) [src/tools/registry.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs) [AGENTS.md40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L40)

## Infrastructure Services

### Gateway and Container Orchestration

The `gateway` command orchestrates the `ContainerAgentProxy`, which provides strong isolation by spawning agents in separate runtimes [src/gateway/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/mod.rs)

- Backends : Supports Docker , Apple (macOS), Landlock , Firejail , and Bubblewrap AGENTS.md 16
- Startup Guard : Monitors for crash loops and degrades after N failures AGENTS.md 45
- Hot Reload : Polls config.json every 30s to apply updates to providers, channels, and safety settings without restarting the gateway AGENTS.md 53

**Sources:** [src/gateway/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/gateway/mod.rs) [src/runtime/mod.rs62-65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L62-L65) [AGENTS.md16-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L16-L53)

### Background Services

- CronService : Handles persistent scheduling with exponential backoff on errors and one-shot delete-after-run on success src/cron/mod.rs AGENTS.md 35
- HeartbeatService : Monitors system health and generates HEARTBEAT.md logs src/heartbeat/mod.rs
- Routines Engine : Manages event-triggered automations via Triggers (Cron, Event, Webhook, Manual) src/routines/mod.rs
- r8r Bridge : WebSocket bridge for workflow approvals, health updates, and replay-safe duplicate-event acknowledgments src/r8r_bridge/mod.rs AGENTS.md 52

**Sources:** [src/lib.rs55-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L55-L78) [src/routines/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs) [AGENTS.md35-52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L35-L52)

## Security Architecture

Security is implemented as a multi-layered "SafetyLayer" [src/safety/mod.rs36](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L36-L36)

1. Injection Detection : 21+ patterns to prevent prompt injection AGENTS.md 43
2. Leak Scanner : 22+ patterns to prevent credential/secret leakage AGENTS.md 43
3. Audit Chain : In-memory SHA-256 hash chain of all tool executions recorded via record_audit_chain_event src/audit.rs 95 AGENTS.md 47
4. Taint Tracking : Tracks sensitive data flow through the system using TaintEngine src/lib.rs 35
5. Shell Security : Blocklists dangerous commands and validates paths in workspace src/security/mod.rs 82-86
6. Filesystem Hardening : Write/edit tools create parent directories one component at a time and use secure no-follow writes AGENTS.md 43

**Sources:** [src/safety/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs) [src/security/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs) [src/audit.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs) [AGENTS.md43-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L43-L47)
