Architecture
Roboticus compiles to a single static Go binary. Every subsystem runs in one OS process using goroutines, sharing one SQLite database. Key subsystems: 12-stage pipeline, 25-guard chain, Context Observatory, SSE streaming, browser tool adapter, MCP client, response transform pipeline, sub-agent orchestration, and approval workflows.
Dependency Graph
C4 System Context
Context Observatory
Records context snapshots per LLM turn (token allocation, memory tiers, model, complexity), runs 22 heuristic rules across 7 categories, computes efficiency metrics, and generates actionable optimization recommendations.
Streaming Pipeline
SSE chunk stream adapter for token-by-token LLM output. Server-Sent Events endpoint with EventBus fan-out to WebSocket clients. StreamAccumulator collects the full response for the transform pipeline.
Synchronized Architecture Corpus
Website architecture docs are synchronized against 32 canonical files in ../roboticus/docs/architecture.
Dataflow Coverage
Define a single, auditable control plane for autonomous revenue pursuit so each strategy (paid services, micro-bounty, data feeds) reuses the same intake, gating, execution, and settlement path.
Data flows for the Roboticus architecture -- a single Go binary autonomous agent runtime.
Skills Catalog Contract architecture reference.
Sequence Coverage
Companion to the dataflow diagrams (roboticus-dataflow.md). These show temporal ordering of interactions between packages during key operations.
C4 Corpus
Additional Architecture Specs
Recommended Next Diagrams
- Plugin catalog install path (`manifest.plugins.catalog` -> archive fetch -> checksum verify -> install -> enable).
- Release sync lifecycle (`roboticus` release tag -> site sync workflow -> registry validation -> static deploy).
- Approval-gated tool execution sequence (request -> guard -> pending approval -> approve/deny -> resume/cancel).
- Channel ingress/egress path with dead-letter replay (adapter receive -> normalization -> agent pipeline -> delivery -> replay on failure).
Package Map
| Package | Purpose |
|---|---|
core | Shared types (SurvivalTier, ApiFormat, ModelTier, RiskLevel, SkillKind), unified config parsing, personality system (4-layer TOML), keystore, error types |
db | SQLite persistence — 35 migrations, WAL mode, FTS5 full-text search, ANN vector index, embedding storage, context snapshots, turn feedback |
llm | LLM client pipeline — format translation (5 API formats), circuit breaker, in-flight dedup, metascore model router, ML router (logistic regression), 3-level semantic cache, tier-based prompt adaptation |
agent | Agent core — ReAct loop state machine, 27 built-in tools, policy engine, 4-layer injection defense, HMAC trust boundaries, 5-tier memory system, dual-format skill loader, sandboxed script runner, intent classifier, 25-guard chain, MCP client, browser tool adapter |
pipeline | 12-stage request pipeline, 25 output guards (3 chain variants), intent registry, semantic classifier, context assembly, prompt compression |
wallet | Ethereum wallet (secp256k1 ECDSA), AES-256-GCM encrypted storage (Argon2id KDF), x402 payment protocol (EIP-712 + EIP-3009), treasury policy engine, DeFi yield engine (Aave V3 on Base) |
schedule | Unified cron/heartbeat scheduler — DB-backed with lease-based mutual exclusion, slot probing, timezone-aware cron evaluation |
channel | 8 channel adapters (Telegram, WhatsApp, Discord, Signal, Email, Matrix, Voice, WebSocket) + zero-trust A2A protocol (X25519 ECDH, AES-256-GCM) + durable delivery queue |
plugin | Plugin registry, manifest parser (plugin.toml), script runner (env-cleared, path-confined), auto-discovery, hot-reload, security permissions model (filesystem, network, exec) |
browser | Headless browser automation via Chrome DevTools Protocol (CDP) — navigate, click, type, screenshot, evaluate, scroll, extract, hover, select |
mcp | Model Context Protocol client — gateway, manager, tool discovery, SSE streaming, connect/disconnect lifecycle |
api | HTTP server (chi/v5, 44 route handlers), embedded dashboard SPA (go:embed), WebSocket push, ticket-based auth, 4 themes |
daemon | Lifecycle management, channel wiring, heartbeat, bootstrap sequence |
tui | Terminal UI via Bubbletea — interactive agent chat, status display, configuration in the terminal |
security | OS-level sandboxing (Landlock on Linux, sandbox-exec on macOS), claim-based authority composition |
session | Session management types, scoping (Agent/Peer/Group), lifecycle governance |
Workspace Layout
roboticus/
├── go.mod # Go module (go 1.26)
├── main.go # Entry point
├── README.md
├── banner.txt # ASCII robot logo
├── install.sh # Linux/macOS/WSL installer
├── install.ps1 # Windows PowerShell installer
├── justfile # Dev recipes
├── cmd/ # CLI commands (37 total)
├── internal/
│ ├── core/ # Shared types, config, personality
│ ├── db/ # SQLite persistence (35 migrations)
│ ├── llm/ # LLM client + format translation
│ ├── agent/ # Agent loop + tools + policy
│ ├── pipeline/ # 12-stage pipeline + 25 guards
│ ├── wallet/ # secp256k1 + x402 + yield
│ ├── schedule/ # Heartbeat + cron
│ ├── channel/ # 8 chat adapters + A2A
│ ├── api/ # HTTP API (chi/v5), dashboard (go:embed)
│ ├── plugin/ # Plugin registry
│ ├── browser/ # CDP automation
│ ├── mcp/ # MCP client
│ ├── tui/ # Bubbletea terminal UI
│ ├── security/ # OS-level sandboxing
│ ├── session/ # Session management
│ └── daemon/ # Lifecycle + bootstrap
├── docs/ # Architecture docs (32 files)
├── registry/ # Bundled skills + providers
├── migrations/ # SQLite migration files
└── tools/ # Dev tooling