Files
waggle-os/docs/ARCHITECTURE.md
shumeiko.it 06a0df73b5 docs: rewrite the architecture overview for the community edition (P2.4)
Describe the web UI, the sidecar, the Tauri shell, waggle.db, the
memory contract and mem0, models, the server installer and archive,
and the staging chain that builds the desktop packages and the server
archive. Drop the removed packages, KVARK, team mode, the .mind files
and the knowledge graph.
2026-11-01 01:53:53 +01:00

12 KiB

Architecture

How the community edition of Waggle is put together: the parts, how a chat turn flows through them, where data lives and how a release is built. The decisions behind it are in docs/oss/adr/; AGENTS.md lists the status of every package.

Overview

 Browser tab or Tauri window
 ┌──────────────────────────┐
 │ Web UI (apps/web, React) │
 └────────────┬─────────────┘
              │ HTTP + Server-Sent Events, bearer session token
              ▼
 ┌─────────────────────────────────────────────────────────────┐
 │ Sidecar: Fastify on Node.js, 127.0.0.1:3333                 │
 │ (packages/server/src/local)                                 │
 │                                                             │
 │  agent runtime ─────── built-in provider proxy ──► provider │
 │  (packages/agent)      (/v1/chat/completions)      APIs or  │
 │                                                    Ollama   │
 │  MemoryStore ──► @waggle/memory-mem0 ──► <data>/memory/     │
 │  WaggleDB ─────► <data>/waggle.db                           │
 │  vault ────────► <data>/vault.json                          │
 │  connectors, channels, scheduler, marketplace, skills       │
 └─────────────────────────────────────────────────────────────┘

Everything runs on the user's computer. The only outside calls are the ones the user sets up: model providers, connectors, messaging channels, marketplace sources, downloads of local models and the embedding model, and analytics if the user allows them.

Parts

Web UI (apps/web)

React 19, TypeScript, Vite 6, Tailwind CSS 3.4 and Radix UI primitives. It is an application, not a package. npm run build builds it into the root dist/, which the sidecar serves; the desktop build uses apps/web/dist.

The UI talks to the sidecar over HTTP, with Server-Sent Events for chat streaming and notifications. Every /api/* request carries a bearer session token. A page served by the sidecar gets the token from GET /api/auth/session-token, which answers same-origin requests only; the desktop window gets it through a per-launch credential from the Tauri shell.

Product analytics (PostHog) start only after the user allows them, and only in builds that carry a key in VITE_POSTHOG_KEY (ADR-0006).

Sidecar (packages/server/src/local)

A Fastify server on Node.js. In development it runs from TypeScript source with tsx; for release it is bundled into one service.js with esbuild. It listens on 127.0.0.1 port 3333 by default (WAGGLE_PORT, WAGGLE_HOST), rejects requests whose Host header is not local, and serves the web UI from WAGGLE_FRONTEND_DIR or the root dist/.

It holds:

  • the HTTP routes (routes/) for chat, workspaces, sessions, memory, settings, vault, skills, plugins, connectors, marketplace, automations and the rest;
  • the built-in provider proxy (routes/anthropic-proxy.ts): an OpenAI-compatible /v1/chat/completions endpoint that translates Claude requests to Anthropic's Messages API and forwards requests for other providers to their OpenAI-compatible APIs. The agent loop and memory extraction call cloud models through it (or through LiteLLM when the user runs it);
  • the managed Ollama runtime (managed-ollama-runtime.ts): downloads the official Ollama build, checks its SHA-256 and size, and runs it on 127.0.0.1:11434 with models in <data>/models/ollama;
  • the scheduler for automations (cron.ts), notifications, held actions and approvals;
  • messaging channels (channels/): Telegram, Discord, Slack, and WhatsApp through whatsapp-web.js (ADR-0005);
  • the memory store and background fact extraction (memory-runtime.ts, memory-extraction.ts).

An optional LiteLLM proxy runs only when config.json contains "litellm": { "enabled": true }, on the user's own Python. Nothing else needs Python.

Agent runtime (packages/agent)

The agent loop (agent-loop.ts), the orchestrator that builds the system prompt and recalls memory (orchestrator.ts), personas (persona-data.ts, personas.ts), tools, slash commands (commands/), sub-agents and workflow templates, connectors (connectors/), MCP client support (mcp/), the injection scanner and cost tracking (cost-tracker.ts).

Other packages

Package Role
@waggle/core Config (config.json), the vault, WaggleDB (waggle.db), workspaces, file storage, embeddings, local telemetry, logger
@waggle/shared Shared types, Zod schemas, the MCP server catalog
@waggle/memory-contract The MemoryStore interface, record model, capability map, an in-memory store and the compatibility suite
@waggle/memory-mem0 MemoryStore on the open-source mem0 library
@waggle/marketplace Marketplace catalog (SQLite with full-text search), installer, security scan, sync
@waggle/sdk Skill and plugin SDK, starter skills, capability packs
@waggle/cli A terminal REPL on the same memory store and waggle.db
@waggle-ai/waggle (packages/launcher) The server installer (install, run, doctor, update, uninstall)

packages/team-server, packages/waggle-dance and packages/worker hold team mode. They stay in the repository but are not built, tested in the root run, or shipped (ADR-0003). apps/browser-ext is not part of the release.

Desktop shell (app/)

A Tauri 2 shell in Rust (app/src-tauri). There is no separate frontend in app/: the window loads the apps/web build. The shell:

  • starts the bundled sidecar with the bundled Node.js, on port 3333 or a free port if 3333 is taken, waits until it reports ready, and stops it (SIGTERM first) when the app quits;
  • writes the sidecar's output to <data>/logs/service.log;
  • keeps one instance running, adds a tray icon, and toggles the window with Ctrl+Shift+W;
  • exposes a short list of IPC commands, allowed explicitly in app/src-tauri/capabilities/.

A chat turn

  1. The UI sends POST /api/chat with the message, workspace and session, and reads the reply as a Server-Sent Events stream.
  2. The orchestrator recalls memory for the message (see memory.md) and builds the system prompt from the core rules, the persona, active skills and workspace context.
  3. The agent loop calls the model through the built-in proxy (local Ollama models are called directly). When the model asks for a tool, the loop checks the approval rules (some actions wait for the user to approve), runs the tool, and scans the tool output for prompt injection before the model sees it. External output is passed to the model as data, never as instructions.
  4. Text, tool calls and approval requests stream to the UI as they happen.
  5. The session is appended to <data>/workspaces/<id>/sessions/<session>.jsonl. Costs go into the execution traces in waggle.db, and the finished turn is queued for background fact extraction.

Data

One data directory per user: WAGGLE_DATA_DIR, or ~/.waggle. install.md lists what it contains.

  • Memory goes only through MemoryStore (@waggle/memory-contract). The shipped store keeps its SQLite files in <data>/memory/. Embeddings come from an in-process model, so memory works offline. See memory.md.
  • waggle.db holds Waggle's own data, which is not memory: automations, notifications, held actions, skill hashes, thumbs feedback, cost tracking, the install audit trail, the file index, and the profile card and task list per scope.
  • The vault (vault.json, key in .vault-key) keeps provider keys and connector credentials, each encrypted with AES-256-GCM.
  • Local telemetry (telemetry.db, off by default) and the audit log (audit.db) have their own files.

The SQLite files are opened with better-sqlite3, a native module (ADR-0008).

Models

  • Provider keys. The user enters keys in Settings → Models or in the Vault. The proxy calls the provider directly from the user's computer.
  • Local models. The Waggle-managed Ollama runtime, or an Ollama the user already runs (OLLAMA_HOST, default http://localhost:11434).
  • Cost tracking. CostTracker prices each call and the execution traces are kept in waggle.db (ADR-0004). Settings → Models sets an optional daily budget.

Installer and server archive

The server installer (packages/launcher, ADR-0009) is one self-contained script that uses only Node.js built-in modules. It downloads or reads a server archive, checks its SHA-256, unpacks it into a per-user program directory and writes a waggle-server command. The command runs the archive's own Node.js, so the user's Node.js is needed only for the first npx call.

A server archive (waggle-server-<version>-<target>.tar.gz) contains the same sidecar payload the desktop app ships, the built web UI under web/, and a manifest.json with the version, target and Node.js version. run starts service.js with the environment the desktop shell uses, plus WAGGLE_FRONTEND_DIR pointing at web/.

How a release is built

Native modules (better-sqlite3, onnxruntime-node) must match the bundled Node.js, so each target is built on its own system (ADR-0008). The desktop build scripts in app/package.json run one staging chain into app/src-tauri/resources/:

  1. scripts/bundle-node.mjs downloads and verifies the pinned Node.js (22.23.2);
  2. scripts/build-sidecar.mjs bundles the sidecar into service.js;
  3. scripts/bundle-native-deps.mjs copies the native modules for the target;
  4. scripts/stage-sidecar-deps.mjs stages the packages the bundle keeps external;
  5. apps/web is built with Vite into apps/web/dist;
  6. tauri build produces the installers: .exe (NSIS) and .msi on Windows, .app and .dmg on macOS, .deb and .AppImage on Linux.

Then npm run build:server-archive (scripts/build-server-archive.mjs) packs the same staged payload and apps/web/dist into the server archive for that target, with a .sha256 next to it.

npm ci
(cd app && npm ci)
(cd app && npm run tauri:build:mac:arm64)   # or tauri:build:mac:x64, tauri:build:win, tauri:build
npm run build:server-archive                # set TARGET_ARCH=x64 after an x64 macOS build

The Windows build must run on Windows; see docs/oss/build-windows.md. The first community release is unsigned (docs/oss/signing.md). The release workflow for the community edition is not set up yet, so releases are built by hand on each system.

Shipped dependencies are checked for licenses that allow MIT distribution (npm run check:licenses, and cargo deny for the Rust crates), and their notices are in THIRD_PARTY_NOTICES.md.

Extension points

  • Skills: Markdown files with YAML frontmatter in <data>/skills/, added to the system prompt when active. See guides/capabilities.md.
  • Plugins and MCP servers: installed from the marketplace or a local directory.
  • Connectors: classes in packages/agent/src/connectors/, registered in packages/server/src/local/setup-connectors.ts. A connected service adds tools to the agent.
  • Slash commands: CommandDefinitions in packages/agent/src/commands/, registered with the CommandRegistry.
  • Memory backends: an implementation of MemoryStore that passes the compatibility suite in @waggle/memory-contract.

Security

The threat model, the controls and the known gaps are in THREAT_MODEL.md. In short: the user is trusted, external content is not. Connector input, tool output and recalled memory pass the injection scanner; secrets live in the vault; sensitive tools wait for approval; the sidecar answers only local requests that carry the session token.