feat: add initial codemap documentation and architecture overview; include backend, data, dependencies, and frontend details

2026-07-12 11:10:16 +07:00
parent 89b63b1bc2
commit 7158d362fd
7 changed files with 419 additions and 0 deletions
@@ -0,0 +1,68 @@
+<!-- Generated: 2026-07-12 | Files scanned: 124 | Token estimate: ~850 -->
+
+# Backend / Service Layer
+
+## AI Provider
+
+`src/service/provider.rs` (258 lines)
+- `LlmClient::new(api_key, model, base_url)` — constructs blocking reqwest client
+- `chat_with_tools()` — non-streaming with tool definitions
+- `chat_stream()` — SSE streaming, returns `SseParser` yielding `StreamEvent`
+- Retry logic: up to 3 attempts on transient errors, exponential backoff
+
+## OAuth
+
+`src/service/oauth/manager.rs` (113 lines) + `loopback.rs` + `pkce.rs`
+- PKCE flow: `CodeVerifier` → challenge → browser auth → loopback server → token exchange
+- Configurable via `app_config.json` provider definitions (auth URL, token URL, scopes)
+
+## IPC / Daemon
+
+`src/ipc/` (7 files, ~300 lines total)
+- Unix domain socket, length-prefixed JSON frames
+- Daemon sends `DaemonFrame { state: StatePayload, diff, tasks }` to clients
+- Clients send `ClientRequest { action: Action }` back
+- State sync uses snapshots + binary diffs (rsync-style, not git)
+
+## Workflow Engine
+
+`src/app/workflow/engine.rs` (251 lines) + `script.rs`
+- Inline JS-style DSL executed by a lightweight runtime
+- `agent()`, `parallel()`, `pipeline()`, `phase()`, `log()` — spawns sub-agents
+- Max concurrency configurable via `workflow_max_concurrency` setting
+
+## Sub-Agent System
+
+`src/app/subagent/` (4 files, ~250 lines)
+- `run_subagent()` — spawns independent agent with its own tool set & context
+- Communicates via `mpsc<SubagentEvent>` channel (tool calls, results, completion)
+- Uses `LlmClient` (same as main agent) with tool-use API
+
+## MCP Client
+
+`src/app/mcp/manager.rs` (371 lines)
+- Stdio transport: spawns child process, JSON-RPC via stdin/stdout
+- HTTP transport: streaming HTTP with JSON-RPC
+- Tool registration: `tools/list` → `McpToolAdapter` implements `crate::tool::Tool`
+- Persistent child handle for stdio (reuses connection across calls)
+
+## Self-Review
+
+`src/app/review/mod.rs` (437 lines)
+- Post-tool execution quality check against learned lessons
+- Invokes `run_subagent()` with reviewer prompt
+- Staleness detection: skips review after N consecutive empty results
+
+## Background Bash
+
+`src/app/bgbash/` (2 files)
+- `spawn_bash_job()` — runs `sh -c` in a thread, collects stdout line-by-line
+- Channels: output via `mpsc<String>`, PID via `mpsc<u32>`
+- Killable via PID
+
+## Gate Guard / Harness
+
+`src/app/harness.rs` (127 lines)
+- `Harness::gate_tool_call()` — verdict-based tool gating (allow/block)
+- Parses LLM verdicts (JSON or plain-text)
+- `test_parse_verdict_*` tests for 6 verdict formats