This commit is contained in:
Oleg Maslov
226
docs/WAGGLE-SYSTEM-MAP.md
Normal file
226
docs/WAGGLE-SYSTEM-MAP.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Waggle OS — System Map
|
||||
|
||||
**Date:** 2026-04-12
|
||||
**Purpose:** Complete system map for a non-coder product owner and any engineer joining the project.
|
||||
**Extends:** WAGGLE-CORNERSTONE.md (product state + build plan). This doc covers *system internals*.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architecture Overview
|
||||
|
||||
```
|
||||
USER
|
||||
|
|
||||
v
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ TAURI SHELL (Rust, ~120 MB binary) │
|
||||
│ Spawns sidecar, tray icon, Ctrl+Shift+W toggle │
|
||||
│ Watchdog: restarts sidecar on crash (max 5/10m) │
|
||||
└──────────────────────────────────────────────────┘
|
||||
│ hosts webview at localhost:3333
|
||||
v
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ REACT DESKTOP OS (apps/web/) │
|
||||
│ Window manager, dock, 18+ apps, SSE streaming │
|
||||
│ Talks to sidecar via HTTP + SSE + WebSocket │
|
||||
└──────────────────────────────────────────────────┘
|
||||
│ HTTP POST/GET + SSE streams
|
||||
v
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ SIDECAR (Node.js + Fastify, port 3333) │
|
||||
│ 150+ routes, agent loop, tool execution │
|
||||
│ LLM: LiteLLM proxy (4000) or built-in Anthropic │
|
||||
└──────────────────────────────────────────────────┘
|
||||
│ direct function calls
|
||||
v
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ CORE (TypeScript library packages) │
|
||||
│ MindDB (SQLite), FrameStore, KnowledgeGraph │
|
||||
│ HybridSearch, Harvest, Compliance, Vault │
|
||||
│ Each workspace = its own .mind SQLite file │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Why this matters:** Every user action flows through exactly this stack. There are no hidden services or external dependencies for core functionality.
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Flows
|
||||
|
||||
### Chat Message Flow
|
||||
```
|
||||
User types message → adapter.ts POST /api/chat
|
||||
→ Sidecar resolves workspace session (WorkspaceSessionManager)
|
||||
→ Builds system prompt (orchestrator.ts: identity + awareness + memory recall)
|
||||
→ Agent loop: POST to LLM provider (streaming)
|
||||
→ SSE events back: token, step, tool_start, tool_end, done
|
||||
→ Frontend useChat.ts parses SSE → renders in ChatApp
|
||||
```
|
||||
|
||||
### Memory Save Flow
|
||||
```
|
||||
Agent calls save_memory tool
|
||||
→ FrameStore.createIFrame() or createPFrame()
|
||||
→ SHA-256 dedup check (500-frame window)
|
||||
→ INSERT into memory_frames + FTS5 index
|
||||
→ Embed via active provider → INSERT into vec table
|
||||
→ CognifyPipeline: extract entities → KnowledgeGraph upsert
|
||||
→ MemoryLinker: find related frames
|
||||
```
|
||||
|
||||
### Memory Recall Flow
|
||||
```
|
||||
User query arrives → orchestrator.recallMemory()
|
||||
→ Catch-up detection ("where were we?")
|
||||
→ HybridSearch: parallel FTS5 keyword + sqlite-vec k-NN
|
||||
→ RRF fusion (K=60) → relevance scoring (temporal/popularity/importance/contextual)
|
||||
→ Top results injected into system prompt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Surface Area
|
||||
|
||||
| Category | Count | Key Files |
|
||||
|----------|-------|-----------|
|
||||
| HTTP API routes | 150+ | packages/server/src/local/routes/ |
|
||||
| Agent tools | 60+ | packages/agent/src/*-tools.ts (22 files) |
|
||||
| MCP catalog entries | 149+ (auto-syncs to 2000+) | packages/shared/src/mcp-catalog.ts |
|
||||
| Keyboard shortcuts | 21 | apps/web/src/hooks/useKeyboardShortcuts.ts |
|
||||
| Audit event types | 13 | packages/server/src/local/routes/events.ts |
|
||||
| SSE streams | 3 | /api/chat, /api/events/stream, /api/notifications/stream |
|
||||
| Personas | 22 | packages/agent/src/personas.ts |
|
||||
| Frontend apps | 18+ | apps/web/src/components/os/apps/ |
|
||||
|
||||
---
|
||||
|
||||
## 4. Memory Architecture
|
||||
|
||||
### Frame Types (the fundamental unit)
|
||||
- **I-Frame (Identity):** Foundational memory — "User prefers bullet points"
|
||||
- **P-Frame (Procedural):** Incremental update — "Updated: also prefers dark mode"
|
||||
- **B-Frame (Bridging):** Cross-references between frames
|
||||
|
||||
### Search Pipeline
|
||||
1. **Keyword search** via FTS5 (stop-word filtered, OR-based)
|
||||
2. **Vector search** via sqlite-vec (k-NN embedding lookup)
|
||||
3. **RRF Fusion** combines both (K=60 reciprocal rank)
|
||||
4. **Relevance scoring** with 4 profiles: balanced, recent, important, connected
|
||||
|
||||
### Embedding Providers (probed in order)
|
||||
1. InProcess (Xenova/all-MiniLM-L6-v2, 384→1024 dims, zero config)
|
||||
2. Ollama (nomic-embed-text, needs local Ollama)
|
||||
3. Voyage AI (voyage-3-lite, needs API key)
|
||||
4. OpenAI (text-embedding-3-small, needs API key)
|
||||
5. Mock fallback (deterministic, always available)
|
||||
|
||||
### Memory Harvest (external import)
|
||||
4-pass pipeline: **Classify** (Haiku) → **Extract** (Sonnet) → **Synthesize** (Sonnet) → **Dedup** (local)
|
||||
Supports: ChatGPT, Claude, Claude Code, Gemini, Perplexity, Grok, Cursor, Copilot exports.
|
||||
|
||||
### Learning / EvolveSchema
|
||||
ImprovementSignals table tracks 3 categories:
|
||||
- `capability_gap` — missing tools (threshold: 2 occurrences)
|
||||
- `correction` — user behavior corrections (threshold: 3)
|
||||
- `workflow_pattern` — recurring task shapes (threshold: 3)
|
||||
Surfaced to user as actionable suggestions (max 3 at a time).
|
||||
|
||||
---
|
||||
|
||||
## 5. Production Subsystems
|
||||
|
||||
### Billing (Stripe)
|
||||
- **Status:** Implemented
|
||||
- Checkout sessions for BASIC ($15/mo) and TEAMS ($79/mo)
|
||||
- Webhook handler for subscription lifecycle
|
||||
- Poll-based tier sync for desktop apps behind NAT
|
||||
- Tier definitions in packages/shared/src/tiers.ts with capability matrices
|
||||
|
||||
### Auth (Clerk)
|
||||
- **Status:** Implemented (cloud only)
|
||||
- JWT validation via @clerk/fastify
|
||||
- Desktop app uses bearer token auth (wsToken from /health)
|
||||
- Auto-provisioning from JWT claims
|
||||
|
||||
### Vault (Secret Management)
|
||||
- **Status:** Implemented
|
||||
- AES-256-GCM encryption with per-entry IV
|
||||
- Machine-local key file (.vault-key, mode 0600)
|
||||
- API routes for reveal/list/set/delete
|
||||
- 3 test files including concurrency and edge cases
|
||||
|
||||
### Offline Queue
|
||||
- **Status:** Implemented
|
||||
- Periodic LLM health check (30s interval)
|
||||
- Message queue persisted to offline-queue.json
|
||||
- Auto-retry on reconnection
|
||||
|
||||
### Telemetry
|
||||
- **Status:** Implemented (privacy-first)
|
||||
- All data in local ~/.waggle/telemetry.db
|
||||
- Never tracks: message content, memory, file paths, API keys
|
||||
- Daily aggregation of tools, commands, errors
|
||||
|
||||
### EU AI Act Compliance
|
||||
- **Status:** Implemented
|
||||
- Art. 12: Interaction audit logging
|
||||
- Art. 14: Human oversight tracking (approved/denied/modified)
|
||||
- Art. 19: 6-month log retention
|
||||
- Art. 26: Deployer monitoring
|
||||
- Art. 50: Model transparency
|
||||
- Template-level risk classification (minimal/limited/high-risk)
|
||||
|
||||
### Rate Limiting
|
||||
- **Status:** Implemented
|
||||
- Per-endpoint: /api/chat (120/min), /api/vault/reveal (5/min), /api/backup (2/min)
|
||||
- Security headers: CSP, X-Frame-Options, X-XSS-Protection
|
||||
- API search tools: daily limits (Perplexity 100, Tavily 50, Brave 100)
|
||||
|
||||
### KVARK Enterprise
|
||||
- **Status:** Partially implemented
|
||||
- kvark_search + kvark_ask_document tools exist
|
||||
- KvarkClient with JWT lifecycle
|
||||
- UI settings panel stubbed ("MOCK: Remove this fallback once real KVARK is wired")
|
||||
|
||||
### Tauri Bundle
|
||||
- **Status:** Implemented
|
||||
- Windows NSIS + macOS DMG targets
|
||||
- Auto-updater with GitHub Releases endpoint
|
||||
- No code signing configured yet
|
||||
- Signature fields in latest.json empty
|
||||
|
||||
---
|
||||
|
||||
## 6. Testing
|
||||
|
||||
| Type | Count | Framework |
|
||||
|------|-------|-----------|
|
||||
| Unit/Integration tests | 305 files | Vitest |
|
||||
| E2E tests | 11 spec files | Playwright |
|
||||
| Visual regression | 14 baselines | Playwright screenshots |
|
||||
| Phase A/B verification | 13 tests, all passing | Playwright |
|
||||
|
||||
---
|
||||
|
||||
## 7. Production-Ready Checklist
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| Core chat loop | GREEN | Multi-session, multi-persona, streaming |
|
||||
| Memory persistence | GREEN | 199 frames in personal.mind, dedup works |
|
||||
| Workspace isolation | GREEN | Each workspace = separate SQLite |
|
||||
| Offline mode | GREEN | Queue + auto-retry |
|
||||
| Billing/tiers | AMBER | Stripe wired, needs production keys |
|
||||
| Auth | GREEN | Clerk (cloud) + bearer token (desktop) |
|
||||
| Vault encryption | GREEN | AES-256-GCM, tested |
|
||||
| Compliance | GREEN | AI Act articles covered |
|
||||
| Rate limiting | GREEN | Per-endpoint limits active |
|
||||
| Auto-updater | AMBER | Configured, signatures empty |
|
||||
| Code signing | RED | Not configured |
|
||||
| KVARK integration | AMBER | Backend exists, UI stubbed |
|
||||
| Error boundary | AMBER | Toast notifications only, no global boundary |
|
||||
| E2E coverage | GREEN | 13/13 Phase A/B tests passing |
|
||||
|
||||
---
|
||||
|
||||
*Generated 2026-04-12. Extends WAGGLE-CORNERSTONE.md.*
|
||||
Reference in New Issue
Block a user