Learning Path
Welcome to the ClawDesk learning centre. Whether you just cloned the repo or you're preparing a contribution to the agent pipeline, this page maps out a structured path through the documentation.
Prerequisites
Before diving in, make sure you're comfortable with:
| Topic | Level | Resources |
|---|---|---|
| Rust ownership & lifetimes | Intermediate | The Rust Book ch. 4-10 |
async/await with Tokio | Beginner | Tokio tutorial |
| Trait-based polymorphism | Intermediate | Rust by Example — Traits |
| Finite State Machines | Conceptual | Wikipedia FSM article |
| Basic LLM API concepts | Conceptual | OpenAI API docs |
The Interactive section at the bottom has architecture explorers and quizzes that teach ClawDesk's design without requiring you to write code.
Learning Roadmap
Beginner Path — Tutorials
These tutorials walk you through ClawDesk hands-on, building real artefacts at each step.
1. Message Flow Tutorial
Time: ~30 min · Outcome: Understand every crate a message touches
Follow a single Telegram message from the raw webhook JSON all the way through the agent pipeline, out to an LLM provider, and back as a reply. Annotated sequence diagrams and code snippets from each crate along the path.
2. Build a Channel
Time: ~45 min · Outcome: A working WebHook channel with tests
Implement the Channel trait (Layer 0), add Streaming (Layer 1), register it in the channel registry, and exercise it with integration tests.
3. Build a Provider
Time: ~40 min · Outcome: A custom LLM provider with fallback support
Implement the Provider trait, map errors to FallbackError variants, register in the provider registry, and verify with mock LLM responses.
4. Build a Skill
Time: ~35 min · Outcome: A prompt-fragment skill with tool bindings
Define a skill in TOML, wire up tool implementations, declare dependencies, and test the knapsack selector under various token budgets.
Intermediate Path — Deep Dives
These articles explain why ClawDesk is designed the way it is, with mathematical analysis and comparisons to alternatives.
5. Type Algebra
Why InboundMessage is a 13-variant enum rather than a 60-field struct. Information theory, exhaustive matching, and the NormalizedMessage canonical form.
6. Fallback FSM
The 7-state finite state machine that governs model fallback. Full transition table, termination proof, and comparison to the imperative alternative.
7. Context Assembly
How ContextQueryBuilder in SochDB assembles context under a token budget using prioritized sections and TOON output format.
8. Structured Concurrency
Tokio's CancellationToken hierarchy, JoinSet for parallel tool execution, and spawn_blocking for CPU-bound work.
Interactive Content
9. Architecture Explorer
Clickable Mermaid diagrams with multiple views: system overview, crate dependency graph, message flow, and security layers.
10. Crate Quiz
20-question self-assessment covering crate responsibilities, trait definitions, pipeline stages, and FSM states. Uses expandable <details> blocks for answer reveals.
Recommended Reading Order
Quick Reference: Crate DAG
The entire ClawDesk system is built from 27 crates following a strict dependency order:
types → storage → domain → [channel | sochdb] → [channels | agents | skills] → providers → gateway → acp → [cli | tauri]
Each tutorial and deep dive tells you exactly which crates are involved so you can cross-reference the Crate Reference section.
How to Use This Section
| Icon | Meaning |
|---|---|
| 🟢 | Beginner — no prior ClawDesk knowledge required |
| 🔵 | Intermediate — assumes you've completed the tutorials |
| 🟣 | Interactive — self-paced, no code required |
Found an error or have a suggestion? Open an issue tagged docs:learn on the ClawDesk repository.