220 lines
12 KiB
Markdown
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.
|