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,51 @@
+<!-- Generated: 2026-07-12 | Files scanned: 124 | Token estimate: ~600 -->
+
+# Data / Persistence Layer
+
+## Storage Overview
+
+Base directory: `~/.config/zesdex/` (via `dirs::data_dir()`)
+
+```
+~/.config/zesdex/
+├── settings.json        # User preferences (provider, model, tokens)
+├── app_config.json      # Provider definitions (API base, auth, models)
+├── agents/              # Global agent definitions
+│   └── *.json
+├── memory/              # Persistent lesson/reference store
+│   └── *.md             # Markdown with YAML frontmatter
+├── sessions/            # Per-session data
+│   └── <session-uuid>/
+│       ├── editlog.json      # Edit history
+│       ├── msglog.db         # SQLite message log
+│       ├── transcript.json   # Chat transcript
+│       ├── session.json      # Session metadata
+│       ├── agents.json       # Session-local agent defs
+│       └── snapshot.dat      # State snapshot (daemon mode)
+├── run/                 # Unix domain sockets
+│   └── zesdex-*.sock
+└── store.json           # Legacy session index
+```
+
+## Key Files
+
+| File | Lines | Role |
+|------|-------|------|
+| `src/model/store.rs` | ~50 | File-system storage (ensure_dirs, base_dir resolution) |
+| `src/model/settings.rs` | ~60 | `Settings` — load/save JSON, API keys map |
+| `src/model/app_config.rs` | ~80 | `AppConfig` — provider definitions, model roles, auth |
+| `src/model/memory.rs` | 332 | Memory CRUD — markdown files with frontmatter |
+| `src/model/editlog.rs` | 121 | Edit log — append-only JSON array |
+| `src/model/msglog/` | 4 files | SQLite-backed message log (schema, query, blobs) |
+| `src/model/session.rs` | ~60 | Session CRUD, listing, archival |
+| `src/model/session_lock.rs` | ~50 | flock-based session lock |
+| `src/model/agent_def/` | 3 files | Agent definitions (builtin, global, session-local) |
+
+## Key Patterns
+
+- **No ORM** — raw JSON files + SQLite via rusqlite
+- **settings.json** — loaded at startup, saved on quit / mode switches
+- **Memory format** — Markdown files with YAML frontmatter (`---\nname: ...\ndescription: ...\n---\ncontent`)
+- **Edit log** — append-only, stores `(file, old, new, timestamp, tool)`
+- **Session locking** — flock-based, prevents concurrent access to same session dir
+- **Message log** — SQLite with attached blobs for tool arguments/outputs