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,64 @@
+<!-- Generated: 2026-07-12 | Files scanned: 124 | Token estimate: ~700 -->
+
+# Frontend / TUI
+
+## Render Pipeline
+
+```
+ratatui::Terminal::draw(|frame|)
+  → view::draw(frame, AppStateRest)
+    → render_main_panel / render_overlay (based on overlay state)
+    → render_input_bar
+    → draw_status_bar
+    → render_toasts (top-right floating notifications)
+```
+
+## Layout
+
+```
+┌──────────────────────────────────────────────┐
+│ Chat Panel (main_area: Min 3)                │
+│  ┌────────────────────────────────────────┐  │
+│  │ User: Hello                           │  │
+│  │ Agent: Hi there, how can I help?      │  │
+│  │                                       │  │
+│  │ Toast notifications (top-right)       │  │
+│  └────────────────────────────────────────┘  │
+├──────────────────────────────────────────────┤
+│ Input Bar (3 lines)                          │
+│ > Some text...                               │
+├──────────────────────────────────────────────┤
+│ Status Bar (1 line)                          │
+│  ┌ Provider │ Model │ Tokens │ Mode │ Quit ─┤
+└──────────────────────────────────────────────┘
+```
+
+## Key Files
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/view/mod.rs` | 623 | Frame draw, overlays (16 types), input bar, toasts |
+| `src/view/chat.rs` | 155 | Chat transcript rendering with markdown |
+| `src/view/markdown.rs` | 144 | Markdown → ratatui `Span` rendering (pulldown-cmark + syntect) |
+| `src/view/status.rs` | ~50 | Status bar with provider/model/tokens |
+| `src/view/workflow.rs` | 88 | Workflow progress visualization |
+| `src/view/theme.rs` | 23 | Color palette (23 named colors) |
+| `src/controller/input.rs` | 281 | Key event → Action mapping |
+
+## Overlays (16 types)
+
+`Overlay::Help | Settings | Bash | QuitConfirm | Workflow | KeyInput | Editor | Effort | Mcp | Todo | Rewind | Learning | Usage | Loading | ModelSelector | ClearConfirm`
+
+Each overlay renders a centered popup via `render_overlay()`.
+
+## State Mutations
+
+State is mutated in-place from two locations:
+- `src/controller/input.rs` — keyboard shortcuts and overlay interactions
+- `src/app/runtime/actions/mod.rs` — `apply_action()` reducer for all programmatic actions
+
+## Toast Notifications
+
+`render_toasts()` — floating stack at top-right, color-coded by severity:
+- Info: blue, Success: green, Warning: yellow, Error: red, Lesson: cyan
+- Max 4 visible, auto-expire after 5s lifetime