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,61 @@
+<!-- Generated: 2026-07-12 | Files scanned: 124 | Token estimate: ~750 -->
+
+# Architecture
+
+Zesdex is a single-process terminal AI coding agent with optional daemon/client split.
+
+## System Layout
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    main.rs                            │
+│  single-process ─┬── daemon ── Unix socket ── client  │
+│                  └── attach <id> (TUI-only client)    │
+└──────────────────────┬───────────────────────────────┘
+                       │
+┌──────────────────────▼───────────────────────────────┐
+│                   Event Loop                          │
+│  ┌────────┐   ┌───────────┐   ┌──────┐   ┌────────┐  │
+│  │Input   │──▶│  Actions  │──▶│State │──▶│  TUI   │  │
+│  │Handler │   │ (dispatch)│   │      │   │ Render │  │
+│  └────────┘   └─────┬─────┘   └──────┘   └────────┘  │
+│                     │                                 │
+│              ┌──────▼──────┐                          │
+│              │ LLM Stream  │                          │
+│              │ + Tool Exec │                          │
+│              └──────┬──────┘                          │
+│                ┌────┴────┐                            │
+│                │         │                            │
+│          ┌─────▼──┐ ┌───▼────┐                        │
+│          │ Tools  │ │Sub-    │                        │
+│          │ (28)   │ │agents  │                        │
+│          └────────┘ └────────┘                        │
+└───────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+```
+User keystroke → Controller (KeyEvent → Action)
+  → apply_action() mutates AppStateRest
+  → TUI redraws (ratatui Frame)
+  → On submit: LLM request → SSE stream → tool calls → tool results → more LLM
+  → Session persisted to disk (editlog, msglog, memory)
+```
+
+## Process Modes
+
+| Mode | Impl | Process | IPC |
+|------|------|---------|-----|
+| Single | `run_single_process()` | One | No |
+| Daemon | `run_daemon()` | Server | `ipc/server.rs` |
+| Attach | `run_attach()` | Client | `ipc/client.rs` |
+
+## Key Files
+
+| File | Lines | Role |
+|------|-------|------|
+| `src/main.rs` | 530 | Entry, TUI setup, daemon loop, attach loop |
+| `src/app/runtime/actions/mod.rs` | 1022 | Action dispatch + LLM stream loop + tool execution |
+| `src/controller/input.rs` | 281 | Key event → Action mapping |
+| `src/view/mod.rs` | 623 | TUI rendering (ratatui) |