This commit is contained in:
Oleg Maslov
108
docs/ONBOARDING.md
Normal file
108
docs/ONBOARDING.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Onboarding Guide: Waggle OS
|
||||
> Scannable quick-start. The authoritative deep contract is `CLAUDE.md` at repo root — read that before writing code. This guide is the 2-minute orientation layer on top.
|
||||
|
||||
## Overview
|
||||
Waggle OS is a workspace-native AI agent platform with persistent memory. It ships as a Tauri 2 desktop binary (Win/macOS) wrapping a Vite/React 19 web UI and a Node.js Fastify sidecar. Strategically it's the demand-gen funnel for KVARK (Egzakta's sovereign enterprise AI).
|
||||
|
||||
## Tech Stack (verified 2026-05-28)
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| Language | TypeScript 5.8, Node ≥20 |
|
||||
| Frontend | React 19.1 + Vite + Tailwind 4 + @base-ui/react |
|
||||
| Desktop | Tauri 2.10 (Rust shell, `app/src-tauri/`) |
|
||||
| Backend | Fastify sidecar (Node), runs via `tsx` |
|
||||
| LLM routing | LiteLLM (`litellm-config.yaml`) |
|
||||
| DB / Memory | SQLite (better-sqlite3) + sqlite-vec; mind substrate in `packages/core/src/mind/` |
|
||||
| Billing | Stripe 21 |
|
||||
| Tests | Vitest (unit) + Playwright (E2E/visual) |
|
||||
| Pkg manager | npm workspaces (`apps/*`, `packages/*`) |
|
||||
|
||||
## Architecture
|
||||
Monorepo, full-stack. Frontend (`apps/web`) talks to a local sidecar (`packages/server`) over HTTP/WS at `127.0.0.1:3333`. The sidecar owns the SQLite "mind" per workspace. Tauri wraps both for desktop; the same web UI also runs standalone in a browser against the sidecar.
|
||||
|
||||
```
|
||||
Browser / Tauri WebView
|
||||
└─ apps/web (React) ── lib/adapter.ts (RPC) ──▶ Fastify sidecar :3333
|
||||
packages/server/src/local/
|
||||
index.ts (registers routes + decorators)
|
||||
routes/*.ts
|
||||
└─▶ @waggle/core mind substrate
|
||||
FrameStore / SessionStore /
|
||||
KnowledgeGraph / HybridSearch
|
||||
chat.ts ──▶ @waggle/agent agent-loop ──▶ LiteLLM
|
||||
```
|
||||
|
||||
## Key Entry Points
|
||||
- **Sidecar bootstrap**: `packages/server/src/local/start.ts` → `index.ts` (route registration ~line 1916+, server decorators: `multiMind`, `workspaceManager`, `agentState`, `vault`, `scheduler`)
|
||||
- **Frontend root**: `apps/web/src/pages/Index.tsx` → `components/os/Desktop.tsx` (the desktop-OS shell + Dock)
|
||||
- **RPC layer**: `apps/web/src/lib/adapter.ts` (every backend call goes through here)
|
||||
- **Agent loop**: `packages/agent/src/agent-loop.ts`
|
||||
- **Memory substrate**: `packages/core/src/mind/` (db, frames, search, knowledge, sessions)
|
||||
- **Config**: `litellm-config.yaml` (LLM routing), `packages/shared/src/tiers.ts` (5-tier system)
|
||||
|
||||
## Directory Map
|
||||
```
|
||||
apps/web/ MAIN UI — desktop-OS metaphor (Dock, AppWindow, 25 apps, overlays)
|
||||
apps/www/ Marketing landing page (waggle-os.ai)
|
||||
apps/browser-ext/ Chrome MV3 companion extension (FR-1, 2026-05-28)
|
||||
app/ Tauri desktop shell (Rust + minimal React cockpit)
|
||||
packages/ 27 workspaces (see below)
|
||||
sidecar/ Node bundle target for Tauri packaging
|
||||
docs/ Architecture, plans, audits, this guide
|
||||
external/ meta-agents-research-environments (GAIA2 benchmark harness)
|
||||
benchmarks/ Harness + benchmark runners
|
||||
```
|
||||
**packages/ (27):** 15 core — agent (94+ files, agent-loop/personas/evolution), core (mind+harvest), server (Fastify sidecar), shared (types/tiers/mcp-catalog), sdk, cli, worker, marketplace, optimizer, weaver, waggle-dance, wiki-compiler, launcher, admin-web, memory-mcp — plus **12 `hive-mind-*` OSS-split packages** (core, cli, shim-core, mcp-server, wiki-compiler + 7 hooks: claude-code, claude-desktop, codex, codex-desktop, cursor, hermes, openclaw). (No `packages/ui` — it has no package.json.)
|
||||
|
||||
## Request Lifecycle (a chat message)
|
||||
1. User types in `ChatApp.tsx` → `adapter.sendMessage()` POSTs to `/api/chat`
|
||||
2. `routes/chat.ts` resolves workspace mind DB via `server.agentState.getWorkspaceMindDb()`
|
||||
3. Recall: `HybridSearch` (FTS5 + vec0 fused via RRF) pulls relevant frames
|
||||
4. `agent-loop.ts` builds the system prompt (`orchestrator.ts buildSystemPrompt`), runs the LLM via LiteLLM, executes tools (tool-filter gates per persona)
|
||||
5. Response streams back over SSE/WS; new memory written via `FrameStore.createIFrame()`; `TraceRecorder` logs the turn
|
||||
|
||||
## Conventions
|
||||
- **Files**: kebab-case (`sample-workspaces.ts`); React components PascalCase (`LoginBriefing.tsx`)
|
||||
- **Routes**: `export async function xxxRoutes(server: FastifyInstance)`, then `await server.register(xxxRoutes)` in `index.ts`. Reuse existing endpoints before adding new ones (see `docs/addictiveness-audit-2026-05-28/REDUNDANCY-AUDIT.md` for why).
|
||||
- **Secrets**: `server.vault.get(key)` / `.set()` — never hardcode (CLAUDE.md §7)
|
||||
- **SQL**: parameterized only (better-sqlite3 `?` params)
|
||||
- **Errors**: `try/catch` → `reply.status(n).send({ error })`
|
||||
- **Tests**: unit = `*.test.ts` (Vitest, co-located/per-package); E2E+visual = `*.spec.ts` under `tests/` (Playwright)
|
||||
- **Commits**: Conventional (`feat(scope): …`, `fix:`, `refactor:`, `docs:`, `revert:`). No AI attribution (disabled globally).
|
||||
|
||||
## Common Tasks
|
||||
- **Dev UI**: `npm run dev` (Vite, apps/web)
|
||||
- **Run sidecar standalone**: `npx tsx packages/server/src/local/start.ts --skip-litellm` (serves built `dist/` at :3333)
|
||||
- **Build web**: `npm run build` (→ `dist/`)
|
||||
- **Build packages**: `npm run build:packages` (order: shared → core → agent → server)
|
||||
- **Unit tests**: `npm test` (Vitest)
|
||||
- **E2E**: `npm run test:e2e` · **Visual**: `npm run test:visual`
|
||||
- **Lint**: `npm run lint`
|
||||
|
||||
## Verification before claiming done
|
||||
> ⚠️ `npm run build` typechecks **only `apps/web`**. The sidecar runs via `tsx` (transpile-only). Server-side type errors slip through unless you run the server tsconfig explicitly. CLAUDE.md §2's verification block omits this — add it:
|
||||
```bash
|
||||
npx tsc --noEmit --project packages/server/tsconfig.json # ← the missing one
|
||||
npx tsc --noEmit --project packages/agent/tsconfig.json
|
||||
npx tsc --noEmit --project app/tsconfig.json
|
||||
npm run test -- --run
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## Where to Look
|
||||
| I want to... | Look at... |
|
||||
|--------------|-----------|
|
||||
| Add a backend endpoint | `packages/server/src/local/routes/` + register in `index.ts` |
|
||||
| Add/edit a desktop app | `apps/web/src/components/os/apps/` |
|
||||
| Add an overlay/dialog | `apps/web/src/components/os/overlays/` |
|
||||
| Change memory behavior | `packages/core/src/mind/` |
|
||||
| Change agent reasoning | `packages/agent/src/` (agent-loop, orchestrator, personas) |
|
||||
| Add a persona | `packages/agent/src/persona-data.ts` |
|
||||
| Add a workspace template | `packages/server/src/local/routes/workspace-templates.ts` (`BUILT_IN_TEMPLATES`) |
|
||||
| Change LLM routing | `litellm-config.yaml` |
|
||||
| Change tiers/pricing | `packages/shared/src/tiers.ts` |
|
||||
| Browse MCP/skills catalog | `packages/shared/src/mcp-catalog.ts` + `MarketplaceApp.tsx` |
|
||||
|
||||
## Flags for maintainers (found during onboarding recon)
|
||||
1. **CLAUDE.md §2 says "16 workspace packages" — actual count is 27.** The 11 `hive-mind-*` packages (OSS split, synced to `marolinik/hive-mind` per §7.5) were added since the April verification. Worth a CLAUDE.md refresh.
|
||||
2. **Verification block in CLAUDE.md omits `packages/server` tsc** (see above) — server routes can ship type errors undetected.
|
||||
Reference in New Issue
Block a user