Waggle OS -- Teams Architecture

1 Deployment Options ▼

Desktop

Tauri 2.0 Binary

Self-contained desktop app with bundled Node.js sidecar. SQLite local storage. Zero infrastructure required.

FREE/PRO SQLite

Self-Hosted

Docker Compose

4-service stack: Waggle server + PostgreSQL 16 + Redis 7 + MinIO S3. Health-checked containers with persistent volumes.

TEAMS Docker

Cloud

Render.com Blueprint

One-click cloud deploy: managed PostgreSQL + Redis + 10GB disk. Auto-deploy from Git. Render starter plan.

TEAMS Managed

Enterprise

KVARK On-Prem

Sovereign deployment via Egzakta Group. Full data pipeline, your permissions, complete audit trail. Data stays in your perimeter.

ENTERPRISE Air-gapped

2 Server Architecture ▼

Application

Fastify Sidecar

Node.js Fastify server bundled into Tauri binary. Hosts all API routes: chat, team, workspaces, memory, evolution, compliance.

Port 3333

LLM Routing

LiteLLM Router

3-layer LLM routing: built-in proxy, LiteLLM gateway, echo fallback. Model normalization, vault key resolution, cost tracking.

Multi-model

Database

PostgreSQL / SQLite

Cloud deployments use PostgreSQL 16. Desktop uses SQLite (better-sqlite3 + sqlite-vec). Both use WAL mode for concurrency.

PG 16 SQLite

Cache / Queue

Redis 7

Job queues and session caching for cloud deployments. Used in Docker and Render configs. Not required for local desktop.

Cloud only

Object Storage

MinIO / S3

S3-compatible object storage for team files and document sharing. MinIO in Docker stack, or native S3 in cloud. Bucket: waggle-files.

Team files

Authentication

Clerk / Token Auth

Clerk for managed auth in team mode. Token-based authentication for team server connections. Local desktop uses vault identity.

Clerk

3 Workspace Isolation ▼

Personal (Always Local)

personal.mind -- SQLite + sqlite-vec

FrameStore -- I/P/B frames + compaction

IdentityLayer -- personal identity persistence

HybridSearch -- FTS5 + vec0 fused via RRF

KnowledgeGraph -- bitemporal entity relations

Vault -- API keys, secrets (never synced)

Team (Shared via Sync)

TeamSync -- push-on-write, pull-on-activate

SyncedFrame -- gopId + t composite key

Frame attribution -- authorId + authorName

Team entities API -- entityType=memory_frame

Conflict resolution: last-write-wins (append-mostly)

S3/MinIO -- shared file storage (waggle-files bucket)

Per-Workspace Agents

Per-session orchestrators

Per-window persona binding

Agent loop scoped to workspace mind

Tool filtering via filterToolsForContext()

Autonomy levels: Normal / Trusted / YOLO

Approval inbox with capability grants

4 WaggleDance -- Multi-Agent Coordination ▼

The WaggleDance protocol enables multi-agent collaboration within team workspaces. Agents communicate through typed messages with validated type-subtype combinations.

Message Type	Subtypes	Purpose
request	knowledge_check, task_delegation, skill_request, model_recommendation	Agent asks the hive for information, delegates tasks, or requests capabilities
response	knowledge_match, task_claim	Another agent responds with knowledge or claims a delegated task
broadcast	discovery, routed_share, skill_share, model_recipe	Agent broadcasts discoveries, shares skills, or publishes model evolution recipes

Core

Task Dispatcher

Routes typed messages to handlers. task_delegation spawns workers, knowledge_check queries memory, skill_request resolves capabilities.

dispatcher.ts

Discovery

HiveQuery Broadcast

Broadcasts topic queries across team agents. Collects entities, related tasks, and messages. Scoped by workspace or global.

hive-query.ts

Routing

Capability Router

Per-capability routing across the agent fleet. Resolves available tools, skills, and connectors. Reports availability status.

capability-router.ts

Sharing

Shared Team Memory

TeamSync pushes frames to shared pool. Skill sharing via broadcast. Agents read team context on workspace activation.

team-sync.ts

5 Team Governance ▼

R

Role-Based Access Control

Four roles: owner, admin, member, viewer. Enforced on all team entity operations. Owner/admin gate on create, update, delete, and member management.

A

Audit Trail

Aggregated audit events across all team workspaces. Captures workspace_create, workspace_delete, tool usage, session activity. Queryable by date range.

C

EU AI Act Compliance

Five-article compliance checker: Art. 12 event logging, Art. 14 human oversight, Art. 19 log retention (6 months), Art. 26 deployer monitoring, Art. 50 model transparency.

P

Capability Governance

Enterprise-tier capability policy enforcement. Proxied from team server with 5-minute cache. Defines which tools, models, and connectors each role can access.

S

Team Skill Library

Shared skill repository scoped to team. Skills shared via WaggleDance protocol. Available in TEAMS and ENTERPRISE tiers. Managed by admin role.

T

Tier Enforcement

Middleware-enforced tier gating on all team routes. Controls workspace limits, connector limits, team member caps, admin panel access, and audit log depth.

6 Data Flow -- Team Memory Sync ▼

Memory frames flow between local workspaces and the team server. Push-on-write ensures team context is available immediately. Pull-on-activate keeps each member's view current.

Step 1

Agent A Writes

FrameStore.write() to local .mind

➔

Step 2

TeamSync Push

pushFrame() with attribution

➔

Step 3

S3 + Server

PostgreSQL + MinIO storage

➔

Step 4

Agent B Pulls

pullFrames(since) on activate

➔

Step 5

Shared Context

recallMemory() includes team data

Config

TeamSyncConfig

serverUrl, teamSlug, authToken, userId, displayName. Persisted in WaggleConfig. Token validated against team server /health.

team-sync.ts

Frame Format

SyncedFrame

remoteId, gopId, t, frameType, content, importance, authorId, authorName, createdAt. Identified by gopId + t composite key.

Composite key

Conflict Strategy

Last-Write-Wins

Append-mostly frame model minimizes conflicts. Last-write-wins at individual frame level. Incremental sync via lastSyncTimestamp.

Append-mostly