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.

Go 1.26

Language

Go Packages

SQLite Tables

287489

Lines of Code

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 5 manifest-backed files in ../roboticus/docs.

Total Docs5Dataflow0Sequences0C42Supporting3

Dataflow Coverage

Sequence Coverage

C4 Corpus

diagrams.md architecture-rules-diagrams.md

Additional Architecture Specs

memory-architecture-spec.md architecture-gap-report.md roadmap-architecture-intake.md

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, 30 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 (40 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 (5 files)
├── registry/                   # Bundled skills + providers
├── migrations/                 # SQLite migration files
└── tools/                      # Dev tooling

←PreviousOverview NextFeatures→