Files
waggle-os/docs/ARCHITECTURE.md
2026-11-04 10:41:40 +01:00

220 lines
12 KiB
Markdown

# 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/`](oss/adr/README.md).
## 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](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](install.md#where-your-data-lives)
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](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.
```bash
npm ci
(cd app && npm ci)
(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build:linux
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](oss/build-windows.md).
Releases are built by `.github/workflows/release.yml`. On each target (Windows x64, macOS
arm64 and x64, Linux x64) it stages the sidecar, packs the server archive, builds the Tauri
bundles and smoke-tests both the server installer and the installed desktop app. A `v*` tag
creates a draft GitHub release with a `SHA256SUMS` file. The first community release is
unsigned, apart from an ad-hoc signature on macOS ([docs/oss/signing.md](oss/signing.md)).
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`](../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](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**: `CommandDefinition`s 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`](../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.