From 29b5d08254a0f10050a18355f88bd928b35670e3 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 27 Apr 2026 02:03:19 +0900 Subject: [PATCH] docs: add docs/ARCHITECTURE.md with crate layout, request flow, subsystem map --- README.md | 2 +- docs/ARCHITECTURE.md | 110 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 docs/ARCHITECTURE.md diff --git a/README.md b/README.md index e998686..26c8491 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Claw Code is the public Rust implementation of the `claw` CLI agent harness. The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**. > [!IMPORTANT] -> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. +> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for a high-level crate/subsystem map, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. > > **ACP / Zed status:** `claw-code` does not ship an ACP/Zed daemon entrypoint yet. Run `claw acp` (or `claw --acp`) for the current status instead of guessing from source layout; `claw acp serve` is currently a discoverability alias only, and real ACP support remains tracked separately in `ROADMAP.md`. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..193e307 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,110 @@ +# claw-code Architecture + +A high-level overview of how claw-code is structured. For implementation details, see source code in `rust/crates/`. For provider details, see [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md). For pinpoint navigation, see [ROADMAP.md](../ROADMAP.md#pinpoint-cluster-index). + +## Overview + +claw-code is a Rust-based CLI for interacting with LLM providers (Anthropic, OpenAI-compatible, xAI, DashScope, etc.). It provides: + +- Streaming conversation with auto-compaction +- Tool execution (file read/write, bash, MCP) +- Multi-provider routing +- Session persistence +- Parallel agent execution + +## Workspace Layout + +The Rust workspace is organized in `rust/crates/`: + +### Core crates + +- **`rusty-claude-cli`** — CLI entry point. Parses args, routes commands, manages TUI/headless modes. +- **`runtime`** — Conversation engine. Manages session state, message history, auto-compaction, tool dispatch, hooks, MCP, and branch/lane events. +- **`api`** — Provider abstraction. Hosts `MODEL_REGISTRY` (provider/model routing), SSE streaming, request/response handling. Providers: `anthropic`, `openai_compat`. +- **`tools`** — Tool definitions. File I/O, bash execution, MCP integration, PDF extraction. + +### Support crates + +- **`commands`** — Parsed command dispatch layer between CLI and runtime. +- **`plugins`** — Plugin/hook lifecycle (`hooks.rs`). +- **`telemetry`** — Metrics and tracing instrumentation. +- **`compat-harness`** — Parity test harness for Rust-port validation. +- **`mock-anthropic-service`** — Local mock server for offline/test use. + +## Request Flow + +1. **CLI parse** (`rusty-claude-cli/src/main.rs`) — interprets args, env vars, settings.json +2. **Provider selection** (`api/src/providers/mod.rs`) — routes to provider via `MODEL_REGISTRY` based on model prefix +3. **Conversation execution** (`runtime/src/conversation.rs`) — sends to provider via SSE, receives streamed response +4. **Tool dispatch** (`tools/src/lib.rs`) — if response includes `tool_use`, execute and feed back `tool_result` +5. **Auto-compaction check** (`runtime/src/compact.rs`) — REACTIVE-AFTER-SUCCESS only (see #287 for preflight gap) +6. **Output** — JSON envelope (`--output-format json`) or text (default) + +## Key Subsystems + +### Auto-compaction + +Triggered post-turn when `usage.input_tokens > threshold`. See: +- Threshold via env-only (#283) +- Reactive-not-preflight (#287, CRITICAL) +- Manual `/compact` skip-reasons (#289) +- Failure envelope coverage (#288) + +### Provider routing + +Hard-coded `MODEL_REGISTRY` + env-var-based auth + model-prefix heuristics. See: +- [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md) for current providers +- #285 for declarative providers/models/websearch source-of-truth +- #245, #246 for declarative config & backend swap +- #290, #291, #292 for transport resilience (stream-init, circuit-breaker, escalation) + +### Parallel agents + +Lane-based execution via `runtime/src/lane_events.rs`. Manifest-driven lifecycle. See: +- #286 for detached-thread + no-heartbeat issue (CRITICAL) + +### Tool lifecycle / hooks + +Tools defined in `tools/src/`. Hook events emitted via `runtime/src/hooks.rs` and `plugins/src/hooks.rs`. See: +- #254 (MCP refresh) +- #268 (tool-rendering parity) +- #274 (hook-execution-event envelope) +- #280 (hook event tap) + +### Session persistence + +Sessions managed in `runtime/src/session.rs`. See: +- #278 (version-comparison) +- #279 (unknown-field policy) + +### CLI dispatch + +CLI parsing in `rusty-claude-cli/src/main.rs`. Issues: +- #262 `--max-turns` spec +- #267 `--cwd` runtime fix +- #272 position-independent parsing +- #282 env-vs-config consolidation + +## Build & Test + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for build commands. Quick reference: + +``` +cd rust && cargo build # Build all crates +cd rust && cargo test # Run all Rust tests +``` + +## Tracing & Debugging + +- **Session state:** `runtime/src/session.rs` + `~/.claw/sessions//` +- **Provider responses:** Set `RUST_LOG=trace` for verbose SSE logs +- **Parity checks:** Use `compat-harness` crate for Rust-port validation + +## Related Documents + +- [ROADMAP.md](../ROADMAP.md) — Pinpoints by cluster +- [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) — User-facing failure mitigation +- [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md) — Provider/model details +- [CONTRIBUTING.md](../CONTRIBUTING.md) — Pinpoint filing format +- [PINPOINT_FILING_GUIDE.md](./PINPOINT_FILING_GUIDE.md) — Filing workflow +- [CHANGELOG.md](../CHANGELOG.md) — Recent changes