Architecture Overview
Snippbot is organized as a Python monorepo with a React frontend. All components run on your own infrastructure as a single self-hosted daemon.
System diagram
Section titled “System diagram” ┌──────────────────────────────────┐ │ Client Interfaces │ │ CLI · Web UI · REST API · WS │ └────────────────┬─────────────────┘ │ ┌────────────────▼─────────────────┐ │ Starlette HTTP Server │ │ packages/local/src/snippbot/ │ │ server.py │ │ port 18781 (API + UI) │ │ │ │ Middleware: Auth · CORS · CSRF │ │ Rate Limiting · Security Headers │ └────────────────┬─────────────────┘ │ ┌───────────────────────────┼──────────────────────────┐ │ │ │┌────────▼───────┐ ┌──────────▼────────┐ ┌──────────▼────────┐│ Core Engine │ │ Background │ │ Integrations ││ snippbot_core │ │ Workers │ │ ││ │ │ │ │ • Browser (CDP) ││ • Projects │ │ • Scheduler │ │ • Sandbox ││ • Agents │ │ • Workflow engine │ │ (Docker/Podman) ││ • Memory │ │ • Sub-agent mgr │ │ • Channels (6) ││ • Security │ │ • Insight queue │ │ • Email (SMTP) ││ • SNIPP │ │ • Digest engine │ │ • Devices (WS) ││ • Hooks │ │ • MCP servers │ │ • Audio (STT/TTS) ││ • Config │ │ • Thinking engine │ │ • Push (APNs/FCM) ││ • Security │ │ • Game engine │ │ • Files / Assets ││ • Proactivity │ │ │ │ │└────────┬───────┘ └──────────┬─────────┘ └────────────────────┘ │ │ └───────────────────────────┤ │ ┌────────────────▼─────────────────┐ │ SQLite Databases │ │ ~/.snippbot/*.db │ └──────────────────────────────────┘Package structure
Section titled “Package structure”packages/├── core/ → snippbot_core Shared business logic│ └── src/snippbot_core/│ ├── config.py 40+ env vars, multi-DB config│ ├── event_bus.py Pub/sub, JSONL logging, 100+ event types│ ├── project_store.py Project/Phase/Task FSM
│ ├── executor.py Task execution with worker pools│ ├── proactivity.py 5-level insight generation│ ├── risk_scorer.py Execution risk computation│ ├── memory/ 5-tier: episodic, keyword, vector, hybrid, graph│ ├── scheduler/ Cron/every/at jobs, NL parsing, chains│ ├── workflows/ DAG step execution, templates, checkpoints│ ├── sub_agent/ Multi-agent orchestration, team models│ ├── thinking/ Autonomous reasoning cycles│ ├── chat/ Conversations, context, command processor│ ├── channel_adapter/ 6 messaging platform adapters│ ├── tools/browser/ CDP browser automation, stealth, recording│ ├── sandbox/ Docker/Podman/bubblewrap/firejail isolation│ ├── hooks/ Event hooks, webhooks, analytics│ ├── mcp/ MCP server lifecycle, tool discovery│ ├── audio/ STT + TTS providers (local + cloud)│ ├── email/ IMAP + SMTP, templates│ ├── device/ Device registry, pairing, protocol│ ├── snipp/ Token economy, wallets, escrow, reputation│ ├── security/ DLP, CSRF, rate limiting, secret store, scanner│ ├── game/ Game saves, world state (My Infinite Saga)│ ├── license/ Tier-based feature gating│ ├── marketplace/ Package management, manifests, permissions│ ├── push/ APNs, FCM, Web Push│ ├── notifications/ Webhook delivery, subscriptions│ ├── digest/ Periodic summary composition│ ├── remote_session/ Secure session sharing, TOTP│ ├── assets/ File and asset storage│ └── insight_queue.py Proactive insight delivery│├── local/ → snippbot Self-hosted daemon│ └── src/snippbot/│ ├── server.py Starlette app, middleware stack│ └── api/ 47 REST API route modules (236+ endpoints)│├── cli/ → snippbot_cli CLI commands│ └── src/snippbot_cli/│ ├── commands/ 17 command groups (60+ commands)│ └── user_config.py ~/.snippbot/config.toml│├── ui/ → React frontend Web interface│ └── src/│ ├── pages/ 37 page components│ ├── components/ 30+ feature areas│ └── stores/ 12 Zustand state stores│├── device/ → snippbot_device Device agent (runs on remote devices)├── shared/ → Shared types TypeScript type definitions├── docs/ → Documentation Starlight docs site├── desktop/ → Desktop app Electron wrapper├── mobile/ → Mobile app React Native├── registry/ → Package registry Singularity registry├── site/ → Marketing site snippbot.com├── site-marketplace/ → Marketplace site Singularity marketplace├── snipp-api/ → SNIPP API Token economy backend├── snipp-contracts/ → SNIPP contracts Smart contracts├── edge/ → snippbot_edge [Future: hybrid edge]└── cloud/ → snippbot_cloud [Future: managed service]Request flow
Section titled “Request flow”REST API request:
Client │ HTTP request + Bearer token ▼Starlette middleware │ Auth check (token → user lookup) │ CORS validation │ CSRF protection │ Rate limiting │ Security headers ▼Route handler (packages/local/src/snippbot/api/) │ Input validation │ Permission check │ Business logic call ▼snippbot_core module │ Database read/write │ Background task dispatch │ Event bus publish ▼JSON responseTask execution flow:
POST /api/projects/{id}/approve │ ▼project_store.py: status → approved │ ▼Background worker picks up project │ ▼Permission check: verify agent permissions │ ▼executor.py: load agent + tools + memory context │ ▼Team orchestration: Architect → Executor → Reviewer │ ▼LLM API call (streaming) │ ▼Tool calls executed (browser, files, search, sandbox, etc.) │ ▼Episode written to memory │ ▼Task status → completed / failed │ ▼Event bus → hooks, notifications, digest, insightsEvent bus
Section titled “Event bus”All components communicate via an in-process pub/sub event bus with 100+ event types:
# Publish an eventawait event_bus.publish("task.completed", {"task_id": "...", "status": "completed"})
# Subscribe to events@event_bus.subscribe("task.*")async def on_task_event(event_type: str, data: dict): ...Events are also written to a JSONL log at ~/.snippbot/events.jsonl for replay and debugging.
Databases
Section titled “Databases”Snippbot uses multiple SQLite databases, all in ~/.snippbot/:
| File | Purpose |
|---|---|
snippbot.db | Projects, phases, tasks, agents, conversations, messages |
auth.db | Users, sessions, API keys, refresh tokens |
memory.db | Episodic memory, embeddings, metadata |
vector.db | Vector embeddings (FTS5 + faiss) |
graph.db | Knowledge graph (entities, relations) |
scheduler.db | Jobs, run history, chains, NL parsing history |
workflows.db | Workflow definitions, versions, templates, runs, step runs |
sub_agents.db | Sub-agent state, messages, approvals |
| settings.db | UI settings (14 categories) |
| channels.db | Channel platform credentials, bindings, access |
| devices.db | Paired device registry, capabilities, health |
| insights.db | Proactive insights, engagement signals |
| credentials.db | Encrypted secrets and audit log |
| execution.db | Execution jobs, plans, messages, worker state |
Plus additional databases for metrics, sandbox audit, game saves, notifications, thinking cycles, and subsystem configuration.
Related
Section titled “Related”- Packages — detailed package responsibilities
- Events — event bus and event types
- Database — full schema reference
- Execution Flow — task lifecycle internals
