227 lines
9.1 KiB
Markdown
227 lines
9.1 KiB
Markdown
# 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.*
|