feat: remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide

2026-07-20 14:47:55 +07:00
parent 44c3dd1239
commit 66ac4dbf02
23 changed files with 775 additions and 13170 deletions
@@ -1,65 +1,118 @@
-# Architecture Overview
+# Arsitektur Sistem Zesdex

-## System Layout
+## Gambaran Umum

-Zesdex is an autonomous AI coding agent with a TUI — an LLM client wrapped in a tool-use harness with 37 built-in tools.
+Zesdex adalah autonomous AI coding agent berbasis TUI, dibangun dengan **Rust** menggunakan clean architecture berlapis. LLM client dibungkus dalam tool-use harness dengan 37+ built-in tools — file ops, git, shell, LSP, MCP, subagent orchestration, dan lainnya.
+
+## Struktur Workspace

 ```
-┌─────────────────────────────────────────────────────────────┐
-│                       Process Mode                           │
-│  Single-Process ─── Daemon (background) ─── Attach (client) │
-└──────────────────────────┬──────────────────────────────────┘
-                           │ IPC (Unix domain socket)
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│  src/main.rs                                                │
-│  ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
-│  │  Controller   │──▶│   Runtime    │──▶│     View       │  │
-│  │  (input.rs)   │   │ (actions.rs) │   │ (chat,status,…)│  │
-│  └──────────────┘   └──────┬───────┘   └────────────────┘  │
-│                            │                                 │
-│                    ┌───────▼────────┐                       │
-│                    │    Harness     │                        │
-│                    │  (tool dispatch)│                       │
-│                    └───────┬────────┘                       │
-│                            │                                 │
-│          ┌─────────────────┼─────────────────┐              │
-│          ▼                 ▼                  ▼              │
-│     ┌─────────┐    ┌────────────┐    ┌───────────────┐      │
-│     │  Tools  │    │ Subagents  │    │  Workflow     │      │
-│     │ (37x)   │    │ (auto/gen) │    │  Engine       │      │
-│     └─────────┘    └────────────┘    │  (hive_mind)  │      │
-│                                      └───────────────┘      │
-└─────────────────────────────────────────────────────────────┘
+zesdex/
+├── apps/
+│   ├── domain/           # Layer 1: Pure entities, traits, value objects
+│   ├── application/      # Layer 2: Use-case services
+│   ├── infrastructure/   # Layer 3: Semua I/O (LLM, DB, tools, MCP, LSP)
+│   ├── interfaces/
+│   │   ├── tui/          # Ratatui terminal UI
+│   │   ├── api/          # Axum REST API
+│   │   ├── daemon/       # Unix socket daemon
+│   │   ├── ws/           # WebSocket server
+│   │   ├── grpc/         # gRPC server
+│   │   └── web/          # Web frontend
+│   ├── gateway/          # CLI entry point & dispatcher
+│   └── bootstrap/        # Initial data seeder
 ```

+## Dependency Graph Antar Layer
+
+```
+gateway/bootstrap
+       │
+       ▼
+   interfaces/*  (tui, api, daemon, ws, grpc, web)
+       │
+       ▼
+ infrastructure  ─── implements ──▶  domain ports
+       │
+       ▼
+  application    ─── depends on ──▶  domain traits
+       │
+       ▼
+    domain        (zero framework deps: serde, chrono, uuid only)
+```
+
+> **Aturan**: layer bawah tidak boleh tahu tentang layer atas. `domain` tidak import apapun dari `infrastructure` atau `interfaces`.
+
 ## Process Modes

-| Mode | Description |
-|------|-------------|
-| **Single-process** | TUI + agent run in the same process. Simplest mode. |
-| **Daemon** | `--daemon` flag. Agent processes state in background; clients attach to render. |
-| **Attach** | `--attach <id>` flag. Connect to existing daemon with IPC. |
+| Mode | Flag | Keterangan |
+|------|------|------------|
+| **TUI** | *(default)* | TUI + agent loop dalam satu proses |
+| **Daemon** | `--daemon` | Agent berjalan di background via IPC socket |
+| **Attach** | `--attach <id>` | TUI terhubung ke daemon yang sedang berjalan |
+| **REST API** | `--api` | HTTP server (default port 8080) |
+| **WebSocket** | `--ws` | WS server (default port 8081) |
+| **gRPC** | `--grpc` | gRPC server (default port 50051) |
+| **Web** | `--web` | Static web frontend (default port 3000) |

-In daemon mode, the daemon runs the full agent loop; clients are stateless renderers that sync via Unix domain sockets with diff-based state synchronization.
+## Alur Data (Single-Process Mode)

-## Data Flow
+```
+Keyboard/Event
+      │
+      ▼
+controller/input.rs: handle_key()
+      │  returns Vec<Action>
+      ▼
+action.rs: apply_action(&mut AppStateRest)
+      │  state dimutasi in-place
+      ├──▶ turn.rs: spawn_agent_turn()  ──▶  background thread
+      │         │
+      │         ├─ LLM call (blocking reqwest)
+      │         ├─ tool execution (Tool trait)
+      │         └─ push TurnEvent ke queue
+      │
+      ▼
+run.rs: run_loop_inner()
+      │  drain TurnEvent setiap tick
+      │  skip render jika dirty=false
+      ▼
+view/: draw frame ke terminal (ratatui)
+```

-1. **Input** → `controller/input.rs` handles key events and autocomplete
-2. **Dispatch** → `app/runtime/actions/mod.rs` applies actions to state (`AppStateRest`)
-3. **LLM Stream** → `app/runtime/stream/mod.rs` parses SSE chunks into typed events
-4. **Tool Execution** → `app/harness.rs` gates and runs tool calls via the `Tool` trait
-5. **Rendering** → `view/` modules read `AppStateRest` and render via ratatui
+## File Kunci

-## Key Files
+| File | Peran |
+|------|-------|
+| `apps/gateway/src/main.rs` | CLI entry point, parse args, dispatch ke mode |
+| `apps/interfaces/tui/src/state.rs` | `AppStateRest` — single source of truth state TUI |
+| `apps/interfaces/tui/src/action.rs` | `apply_action()` — satu-satunya tempat state dimutasi |
+| `apps/interfaces/tui/src/run.rs` | Event loop: render → poll → handle → tick |
+| `apps/interfaces/tui/src/turn.rs` | Spawn agent turn di background thread |
+| `apps/interfaces/tui/src/view/mod.rs` | Top-level render pipeline + `pre_render` hook |
+| `apps/infrastructure/src/llm/` | LLM client (streaming + non-streaming) |
+| `apps/infrastructure/src/tools/` | 37 tool implementations |
+| `apps/domain/src/core/` | Entity inti: `ChatMessage`, `Role`, `Store`, `Tool` trait |

-| File | Purpose |
-|------|---------|
-| `src/main.rs` | Entry point, process mode dispatch, TUI init |
-| `src/app/state/rest.rs` | Single source-of-truth state struct |
-| `src/app/runtime/actions/mod.rs` | State reducer (`apply_action`) |
-| `src/app/runtime/stream/mod.rs` | SSE stream parser |
-| `src/app/harness.rs` | Tool harness with safety gating |
-| `src/app/workflow/hive_mind.rs` | Multi-agent orchestration |
-| `src/tool/mod.rs` | Tool trait + registry (37 tools) |
-| `src/view/mod.rs` | TUI render pipeline |
+## IPC Protocol (Daemon Mode)
+
+```
+┌──────────┐  Unix domain socket  ┌──────────┐
+│  Client   │ ◄──────────────────► │  Daemon  │
+│  (TUI)    │  [4-byte len][JSON]  │  (agent) │
+└──────────┘                       └──────────┘
+
+Client  ──Action──▶  Daemon (apply_action → state mutasi)
+Daemon  ──StatePayload──▶  Client (render snapshot)
+```
+
+## Lints & Kualitas Kode
+
+Semua workspace crate menerapkan lint ketat di `Cargo.toml`:
+- `unused`, `dead_code`, `unreachable_code` → **deny**
+- `unused_imports`, `unused_variables`, `unused_mut` → **deny**
+- `clippy::all` + `clippy::pedantic` → **warn**
+
+## Release Profile
+
+`opt-level=3`, `lto="fat"`, `codegen-units=1`, `panic="abort"`, `strip="symbols"`