Architecture Overview
ClawDesk is a multi-channel AI agent gateway built in Rust. It routes conversations from any messaging platform through a unified agent pipeline, executes tool calls, manages memory, and streams responses—all while enforcing security, observability, and fault tolerance guarantees.
Design Philosophy
ClawDesk follows five core architectural principles:
| Principle | Description | Enforcement |
|---|---|---|
| Hexagonal Architecture | Business logic is isolated from I/O via port traits and adapter implementations | clawdesk-storage defines ports; clawdesk-sochdb provides adapters |
| Type-Driven Correctness | Algebraic sum types make illegal states unrepresentable | InboundMessage enum, ValidatedConfig, ClawDeskError |
| Structured Concurrency | Every spawned task is owned, tracked, and cancellable | CancellationToken trees, JoinSet scoping |
| Zero-Trust Security | Four-layer cascade: ACL → allowlist → content scan → audit | clawdesk-security crate |
| Compilation-Unit Isolation | 27 fine-grained crates maximize parallel compilation and enforce boundaries | Workspace Cargo.toml |
System Context
High-Level Message Flow
Every inbound message follows a deterministic path through the system:
Subsystem Map
ClawDesk is composed of seven major subsystems, each implemented across one or more crates:
1. Channel Subsystem
Handles all inbound/outbound communication with messaging platforms.
| Crate | Role |
|---|---|
clawdesk-types | InboundMessage sum type, ChannelId, ChannelMeta |
clawdesk-channel | Layered trait hierarchy (Channel → Threaded → RichChannel) |
clawdesk-channels | Concrete adapter implementations (Slack, Discord, etc.) |
2. Agent Subsystem
Core AI inference pipeline with tool execution.
| Crate | Role |
|---|---|
clawdesk-agents | 6-stage pipeline, AgentRunner, ToolRegistry |
clawdesk-providers | Provider trait + implementations (Anthropic, OpenAI, etc.) |
clawdesk-skills | Composable skill system with knapsack selector |
clawdesk-runtime | Durable agent runtime with state persistence |
3. Storage Subsystem
Persistent state with ACID guarantees and vector search.
| Crate | Role |
|---|---|
clawdesk-storage | Port traits: SessionStore, ConversationStore, VectorStore |
clawdesk-sochdb | SochDB adapter: MVCC, WAL, HNSW, TOON queries |
clawdesk-memory | Hybrid search (BM25 + embedding), reranking, batch ingest |
4. Security Subsystem
Defense-in-depth with audit trail.
| Crate | Role |
|---|---|
clawdesk-security | ACL, allowlist, content scanner, hash-chained audit, tokens |
5. Gateway Subsystem
HTTP/WebSocket server and API surface.
| Crate | Role |
|---|---|
clawdesk-gateway | Axum server, 24+ routes, middleware, hot-reload |
clawdesk-acp | Agent Communication Protocol |
clawdesk-tunnel | Secure webhook tunneling |
6. Plugin Subsystem
Extensibility through sandboxed plugins.
| Crate | Role |
|---|---|
clawdesk-plugin | Plugin host, dependency resolver, sandbox, registry |
7. Observability Subsystem
Full-stack telemetry and monitoring.
| Crate | Role |
|---|---|
clawdesk-observability | OpenTelemetry tracing + metrics integration |
clawdesk-telemetry | OTLP export, structured events |
Client Applications
ClawDesk ships three client binaries:
| Binary | Crate | Technology | Purpose |
|---|---|---|---|
clawdesk | clawdesk-cli | Clap + Tokio | Command-line interface |
| ClawDesk Desktop | clawdesk-tauri | Tauri 2.0 + WebView | Native desktop application |
| ClawDesk TUI | clawdesk-tui | Ratatui | Terminal UI |
All three connect to the same gateway server and share the same storage layer.
Utility & Infrastructure Crates
| Crate | Role |
|---|---|
clawdesk-domain | Business rules: auth, routing, fallback FSM, prompt building |
clawdesk-infra | Infrastructure utilities, platform abstractions |
clawdesk-cron | Scheduled task execution with heartbeat monitoring |
clawdesk-media | Media processing and transcoding |
clawdesk-autoreply | Automated reply rules and templates |
clawdesk-browser | Headless browser integration |
clawdesk-discovery | Service discovery and registration |
Crate Dependency Overview
The workspace contains 27 crates organized in a directed acyclic graph with a critical path depth of 6:
The longest compilation chain is: clawdesk-types → clawdesk-storage → clawdesk-domain → clawdesk-channel → clawdesk-channels → clawdesk-gateway → clawdesk-cli (depth 6). All other crates compile in parallel branches.
Key Architectural Decisions
ADR-1: Hexagonal Architecture Over Layered
Context: ClawDesk must support multiple storage backends and channel adapters without coupling business logic to specific implementations.
Decision: Adopt hexagonal (ports-and-adapters) architecture. All I/O boundaries are defined as Rust traits in clawdesk-storage and clawdesk-channel.
Consequence: Any storage or channel implementation can be swapped without modifying business logic.
ADR-2: Fine-Grained Crate Decomposition
Context: A monolithic crate would lead to long compile times and unclear boundaries.
Decision: Decompose into 27 crates with explicit dependency edges.
Consequence: Maximum parallelism during cargo build. The critical path depth is only 6, enabling crates on independent branches to compile simultaneously.
ADR-3: Embedded Database Over External
Context: Requiring users to install and manage PostgreSQL or similar would increase operational complexity.
Decision: Embed SochDB as the primary storage engine, providing ACID transactions, vector search, and full-text search in a single binary.
Consequence: Zero external dependencies for storage. Single-binary deployment. Trade-off: no horizontal scaling of the database layer.
ADR-4: Algebraic Error Types
Context: Error handling must be exhaustive and composable across crate boundaries.
Decision: Use thiserror-derived enums with per-crate error types that compose via #[from] into ClawDeskError.
Consequence: The compiler enforces exhaustive error handling. No unwrap() in production code paths.
ADR-5: Tokio Single-Runtime
Context: Multiple runtimes would complicate task management and cancellation.
Decision: Single tokio::runtime::Runtime with structured concurrency via CancellationToken hierarchy.
Consequence: Clean shutdown propagation. All spawned tasks are trackable and cancellable.
Performance Characteristics
| Metric | Target | Mechanism |
|---|---|---|
| Message latency (p99) | < 50ms (excluding LLM) | Zero-copy normalization, pre-allocated buffers |
| Concurrent channels | 1,000+ | Tokio task-per-channel, bounded channel backpressure |
| Memory per session | < 8 KB baseline | Arena allocation, lazy context loading |
| Cold start | < 500ms | Lazy initialization, parallel crate loading |
| Hot reload | < 100ms | ArcSwap config, watcher-triggered |
| Vector search (10K docs) | < 10ms | HNSW index with SochDB |
What's Next
Explore each subsystem in detail:
- Hexagonal Architecture — How ports and adapters are structured
- Crate Dependency Graph — Full DAG analysis with build time implications
- Type System — Algebraic types and the message envelope
- Concurrency Model — Structured concurrency with Tokio
- Agent Pipeline — The 6-stage inference pipeline
- Gateway Server — Axum HTTP/WS server architecture
- Storage Layer — SochDB, MVCC, and vector search
- Security Model — Defense-in-depth security cascade
- Plugin System — Extensibility and sandboxing
- Channel Traits — Layered trait hierarchy
- Observability — Telemetry and monitoring