<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3-core-architecture -->

# Core Architecture

- AGENTS.md
- CLAUDE.md
- src/cli/common.rs
- src/lib.rs
- src/tools/mod.rs

## Purpose and Scope

This document describes the fundamental architectural patterns, design principles, and core subsystems that form the foundation of ZeptoClaw. It covers the high-level system organization, message flow, concurrency model, and extensibility mechanisms.

For detailed information about specific subsystems, see:

- System component interactions: System Components
- Agent processing internals: Agent Loop
- Message routing mechanisms: Message Bus and Routing
- Tool execution pipeline: Tool System Architecture
- Hook system and event lifecycle: Hooks System
- Security and isolation strategies: Runtime Isolation
- Middleware and cross-cutting concerns: Agent Middleware Pipeline

## Design Philosophy

ZeptoClaw is built on three core principles:

1. Async-first architecture - All I/O operations use the tokio async runtime. The system leverages async-trait for polymorphic interfaces and parallel tool execution via join_all patterns in the agent processing paths src/lib.rs 145
2. Trait-based abstraction - Core interfaces such as LLMProvider src/lib.rs 59 Channel src/lib.rs 51 Tool src/lib.rs 99 and ContainerRuntime src/lib.rs 63 enable runtime polymorphism and extensibility.
3. Defense-in-depth security - Multiple independent security layers including SafetyLayer src/lib.rs 36 ApprovalPolicyConfig src/tools/mod.rs 61 and containerized runtimes src/lib.rs 62-65 provide redundant protection.

The system follows a message-driven architecture where the `MessageBus` [src/lib.rs47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L47-L47) acts as the central nervous system, decoupling message sources (channels) from processing (agent loop) and delivery (channel dispatch).

**Sources:** [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [CLAUDE.md53-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L53-L83) [AGENTS.md1-54](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L1-L54)

## High-Level System Architecture

The following diagram maps the major subsystems to their primary code entities:

```

```

This diagram shows the primary code entities and their relationships. The `MessageBus` acts as the central hub, the `AgentLoop` orchestrates processing, and the `ToolRegistry` provides a unified interface to all tools.

**Sources:** [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101) [src/cli/common.rs191-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L191-L200) [CLAUDE.md53-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L53-L83) [AGENTS.md39-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L39-L41)

## Core Subsystems Overview

### Message Bus ( bus::MessageBus )

The `MessageBus` is an in-memory pub/sub hub using Tokio MPSC channels. It decouples message producers (channels) from consumers (agent loop).

**Key structures:**

- InboundMessage src/lib.rs 47 : Carries user text, sender info, and MediaAttachment .
- OutboundMessage src/lib.rs 47 : Carries agent responses back to specific channels.

The bus ensures that channel dispatchers do not hold the channels map `RwLock` across async `send()` awaits, improving throughput [AGENTS.md26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L26-L26)

**Sources:** [src/lib.rs47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L47-L47) [AGENTS.md26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L26-L26)

### Agent Loop ( agent::AgentLoop )

The `AgentLoop` [src/lib.rs46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L46-L46) is the core message processor. It consumes `InboundMessage` from the bus, builds context, calls the LLM provider, executes tools, and publishes `OutboundMessage` responses.

**Key components:**

- ContextBuilder src/lib.rs 46 : Assembles system prompt, conversation history, and tool definitions.
- ContextMonitor src/lib.rs 33 : Tracks token usage and triggers compaction tiers (Normal/70%, Emergency/90%, Critical/95%) AGENTS.md 50
- LoopGuard : Detects repeated tool calls via SHA256 signatures to prevent infinite loops AGENTS.md 46

**Sources:** [src/lib.rs33-46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L33-L46) [AGENTS.md46-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L46-L51)

### Channel Manager ( channels::ChannelManager )

The `ChannelManager` [src/lib.rs51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L51-L51) orchestrates channel lifecycle. It supports 10 communication protocols including Telegram, Slack, Discord, and WhatsApp [AGENTS.md15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L15-L15)

**Supervision:**

- A supervisor polling loop (15s) detects dead channels and restarts them with a 60s cooldown AGENTS.md 27
- Tasks for Slack, Discord, and other channels are wrapped with catch_unwind to isolate panics AGENTS.md 28

**Sources:** [src/lib.rs50-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L50-L53) [AGENTS.md15-32](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L15-L32)

### Tool Registry ( tools::ToolRegistry )

The `ToolRegistry` [src/lib.rs128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L128-L128) manages a collection of `Tool` implementations. Execution flows through `kernel::execute_tool()` to ensure shared safety scans, taint checks, and metric recording across the agent loop, MCP server, and embedded facades [AGENTS.md40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L40)

**Tool Categories:**

- Built-in : 33 built-in tools including ShellTool , GitTool , and WebSearchTool src/tools/mod.rs 15-33
- Plugins : BinaryPluginTool src/lib.rs 107 (JSON-RPC 2.0) and MCP servers src/lib.rs 24
- Composed : Natural language tool creation via CreateToolTool src/lib.rs 110

**Sources:** [src/lib.rs94-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L94-L100) [AGENTS.md40-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L42) [src/tools/mod.rs1-143](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L143)

### Provider Chain

LLM providers implement the `LLMProvider` trait [src/lib.rs59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L59-L59) Providers are resolved at runtime and can be wrapped in functional decorators:

- RetryProvider : Exponential backoff for transient errors AGENTS.md 21
- FallbackProvider : Failover between different models or providers src/cli/common.rs 16-17
- QuotaProvider : Enforces usage limits and cost tracking CLAUDE.md 70

**Sources:** [src/lib.rs58-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L58-L61) [src/cli/common.rs15-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L15-L17) [AGENTS.md21-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L21-L25)

### Safety and Security

ZeptoClaw implements a multi-layered security model:

1. SafetyLayer src/lib.rs 36 : Performs injection detection and leak scanning.
2. Audit Chain src/lib.rs 6 : An in-memory SHA-256 hash chain records per-call audit entries for shell, network, and spawn operations CLAUDE.md 95
3. Runtime Isolation : Executes dangerous tools in isolated environments using DockerRuntime , AppleContainerRuntime , or Linux-specific sandboxes like Landlock src/lib.rs 62-65

**Sources:** [src/lib.rs35-38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L35-L38) [src/lib.rs82-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L82-L86) [CLAUDE.md95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L95-L95) [AGENTS.md43-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L43-L47)

## Request Processing Pipeline

The following diagram shows the detailed steps from inbound message to outbound response:

```

```

**Sources:** [src/lib.rs46-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L46-L47) [src/lib.rs23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L23-L23) [AGENTS.md40-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L51)

## Summary

The ZeptoClaw architecture is designed for high reliability and security in a personal AI assistant context. By decoupling components via the `MessageBus` and enforcing strict tool execution boundaries through the `kernel` and `runtime` layers, the system maintains stability even when interacting with external environments or unreliable LLM providers.

For details on individual components, refer to the child pages:

- System Components
- Agent Loop
- Message Bus and Routing
- Tool System Architecture
- Hooks System
- Runtime Isolation
- Agent Middleware Pipeline
