oleg.m/waggle-os

Fork 0

Files

Oleg Maslov 0c3e2ead3b

Installer Smoke / installer-smoke (push) Has been cancelled

Details

moving

2026-09-02 10:10:29 +02:00

9.1 KiB

Raw Permalink Blame History

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

Keyword search via FTS5 (stop-word filtered, OR-based)
Vector search via sqlite-vec (k-NN embedding lookup)
RRF Fusion combines both (K=60 reciprocal rank)
Relevance scoring with 4 profiles: balanced, recent, important, connected

Embedding Providers (probed in order)

InProcess (Xenova/all-MiniLM-L6-v2, 384→1024 dims, zero config)
Ollama (nomic-embed-text, needs local Ollama)
Voyage AI (voyage-3-lite, needs API key)
OpenAI (text-embedding-3-small, needs API key)
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.

9.1 KiB Raw Permalink Blame History