Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│  Surfaces:  Web UI (Next.js :3007)   ·   octi tui / octi edit (pi-tui)  │
│             Telegram · Slack · Teams · WhatsApp · WebChat · MCP clients │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                      Gateway Hub (WebSocket :3005)                      │
│   typed protocol · multi-auth (session / octi_… token / HMAC) ·         │
│   event bus · rate limiter · 12 gateway commands · presence             │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                        API Server (Elysia :3005)                        │
│   REST routes · WebSocket · Swagger · auth derive · scoped repos        │
├─────────────────────────────────────────────────────────────────────────┤
│                              Core Runtime                               │
│   Agent Manager · Worker (LLM + CLI) · Router · Scheduler · Cron        │
│   Orchestrator (classify · roles · pipelines · approvals · guards)      │
│   Swarm (spawner · call-graph · fan-out budget · orphan reaper)         │
│   RAG · Documents · Trajectories · Context compaction · Tool executor   │
├──────────┬───────────┬──────────────────┬──────────┬───────────────────┤
│ Channels │  Tools    │     Security     │  Models  │     Plugins /     │
│          │  (24+)    │                  │          │     Extensions    │
│──────────│───────────│──────────────────│──────────│───────────────────│
│ Telegram │ Filesystem│ Multi-user/RLS   │ Ollama   │  MCP Bridge       │
│ Slack    │ Shell     │ Sessions/Passkey │ OpenAI   │  N8N Workflows    │
│ Teams    │ Git       │ TOTP 2FA         │Anthropic │  Hooks            │
│ WhatsApp │ Browser   │ Vault (HKDF DEK) │ Gemini   │  Voice (STT/TTS)  │
│ WebChat  │ Docker    │ API tokens       │ DeepSeek │  Pipelines        │
│ Voice    │ GitHub    │ Quotas/Rate-lim. │ LiteLLM  │  Notifications    │
│ MCP      │ Knowledge │ Workspace FS     │ OpenRouter│  Browser ext     │
│          │ +17 more  │ Sandboxes        │ CLI tools│  External skills  │
├──────────┴───────────┴──────────────────┴──────────┴───────────────────┤
│                                Data Layer                               │
│   PostgreSQL + pgvector  ·  Valkey (cache / pub-sub)  ·  Drizzle ORM    │
└─────────────────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Runtime	Bun
Backend Framework	Elysia
Database ORM	Drizzle
Database	PostgreSQL + pgvector
Cache	Valkey, Redis-compatible (ioredis client)
Web UI	Next.js 14, React 18, Tailwind CSS, Zustand, TanStack Query
LLM Client	OpenAI SDK (via LiteLLM proxy)
Telegram	grammY
Slack	Bolt.js
Teams	Bot Framework
Auth	argon2, @simplewebauthn/server, otplib
Browser	Playwright
Logging	Pino
Validation	Zod

Project Structure

octipus/
├── bin/
│   └── octi                # Main CLI (start/stop/restart, tui, edit, …)
├── src/
│   ├── api/                # Elysia REST API & WebSocket
│   │   ├── routes/         # Endpoint handlers (sessions, agents, vault, users, …)
│   │   ├── middleware/     # Auth guard, scoped repos derive
│   │   ├── server.ts       # Server setup, principal derivation
│   │   └── websocket.ts    # Gateway WebSocket handler
│   ├── channels/           # Messaging channels (telegram, slack, teams,
│   │                       #   whatsapp, webchat) + linking + attachments
│   ├── config/             # Zod-validated config
│   │   ├── schema.ts             # Config type
│   │   ├── defaults.ts           # Default values
│   │   ├── settings-service.ts   # Three-tier cache + pub/sub (DB > env > default)
│   │   ├── settings-registry.ts  # Setting definitions manifest
│   │   ├── hot-reload.ts         # Live config updates
│   │   └── runtime-loader.ts     # DB-backed config loader
│   ├── core/               # Agent runtime
│   │   ├── agent-base.ts            # BaseAgentWorker abstract class
│   │   ├── agent-worker.ts          # LLM agent
│   │   ├── cli-agent-worker.ts      # CLI agent (claude, codex, gemini, …)
│   │   ├── cli-agent-factory.ts
│   │   ├── tool-executor.ts         # Tool execution & permissions
│   │   ├── context-compaction.ts    # Token budget compaction
│   │   ├── response-cache.ts
│   │   ├── cron-runner.ts           # Cron-triggered hook runs
│   │   ├── agent-manager.ts · router.ts · scheduler.ts · gateway.ts
│   │   ├── commands/                # Internal slash-command handlers
│   │   ├── documents/               # Document ingest / OCR
│   │   ├── rag/                     # Retrieval, embeddings, hybrid search
│   │   ├── skills/                  # Skill loading / topic routing
│   │   ├── trajectories/            # Replayable agent traces
│   │   ├── gateway/                 # Hub, connection-manager, event-bus, …
│   │   ├── orchestrator/            # Classify, route, approve, pipelines
│   │   │   ├── service.ts · classifier.ts · types.ts
│   │   │   ├── roles/               # 17 role folders: orchestrator + 16 worker roles
│   │   │   │   └── <role-name>/     # Each role: config.ts + prompt.md (auto-discovered)
│   │   │   ├── pipeline-manager.ts · pipeline-validation.ts
│   │   │   ├── approval-manager.ts · model-selector.ts
│   │   │   ├── input-guard.ts · output-guard.ts · pii-filter.ts
│   │   │   └── handoff.ts · session-resolver.ts · worker-spawner.ts
│   │   └── swarm/                   # Multi-agent fan-out
│   │       ├── spawner.ts · call-graph.ts · fan-out-budget.ts
│   │       ├── orphan-reaper.ts · cascade-cancel.ts
│   │       └── swarm-tool.ts · collect-tool.ts · escalate-tool.ts
│   ├── db/                 # Drizzle ORM
│   │   ├── schema/         # Table definitions
│   │   ├── repositories/   # Data access (scopedRepos(principal))
│   │   ├── migrations/     # SQL + journal
│   │   └── postgres.ts · redis.ts  # ioredis client; talks to Valkey
│   ├── eval/               # Evaluation harness, golden datasets, results
│   ├── extensions/         # External plugin & skill loader
│   ├── hooks/              # Event-driven automation (pre/post tool, cron, …)
│   ├── mcp/                # MCP bridge (stdio / SSE / streamable-http)
│   ├── models/             # LLM providers, registry, cost & quota tracking
│   ├── plugins/            # First-party plugin scaffolding
│   ├── security/           # Auth, multi-user, vault, permissions
│   │   ├── auth/                   # Session, passkey, TOTP
│   │   ├── principal.ts            # Principal type
│   │   ├── api-tokens.ts           # octi_… personal tokens
│   │   ├── mcp-token-bootstrap.ts  # ~/.octipus/mcp-token bootstrap
│   │   ├── impersonation.ts        # "Act as" admin flow
│   │   ├── orgs.ts                 # Multi-org support
│   │   ├── rls.ts                  # Postgres row-level security (opt-in)
│   │   ├── vault.ts                # AES-256-GCM with HKDF-derived per-user DEKs
│   │   ├── permissions.ts          # Three-tier permission engine
│   │   ├── permission-rules.ts
│   │   ├── secret-injector.ts
│   │   ├── workspace-fs.ts · workspace-resolver.ts
│   │   ├── shell-sandbox.ts · docker-isolation.ts
│   │   ├── quotas.ts · rate-limiter.ts
│   │   ├── channel-bindings.ts · oauth.ts
│   │   └── (extensive .test.ts files alongside)
│   ├── skills/             # Skill registry & external markdown loader
│   ├── tools/              # 24+ built-in tools
│   │   ├── filesystem · shell · git · browser · browser-ext · docker
│   │   ├── github · gitlab · google-workspace · microsoft365
│   │   ├── knowledge · websearch · documents · email-processor
│   │   ├── messaging · scheduling · profiles · visual · voice
│   │   ├── base-tool.ts · registry.ts · discovery.ts
│   │   └── (more — see features/tools)
│   ├── tui-pi/             # Chat shell (octi tui) — pi-tui app, theme/glyphs,
│   │                       #   keybindings, overlays
│   ├── tui-editor/         # File editor (octi edit) — split tree + buffer +
│   │                       #   side chat, file picker, multi-buffer cycling
│   ├── utils/              # Crypto, logger, sanitize
│   ├── visual/             # Playwright visual debugger
│   ├── voice/              # STT, TTS, wake word
│   └── index.ts            # Entry point
├── mcp-server/             # External MCP server bridge for CLI models
├── web/                    # Next.js 14 web UI
│   ├── app/                # App Router (chat, agents, models, users, settings, …)
│   ├── components/         # Sidebar, app-shell, impersonation banner, …
│   └── lib/
├── scripts/
│   ├── db/                 # Database utility scripts
│   ├── e2e/                # E2E test suite
│   ├── qa-multiuser.sh     # Multi-user isolation QA
│   ├── rotate-vault-keys.ts
│   └── setup.ts            # Bootstrap setup wizard
├── tests/
│   └── tui/                # pi-tui chat + editor e2e tests
├── docs/                   # In-repo guides & architecture notes
├── .mcp.json               # MCP server config (auto-regenerated by `octi start`)
├── ROADMAP.md · CHANGELOG.md
├── package.json · tsconfig.json · drizzle.config.ts

Database Schema

Key database tables managed by Drizzle ORM:

Table	Purpose
`users`, `orgs`, `org_members`	User accounts, orgs, membership
`api_tokens`	Personal `octi_…` tokens (hashed)
`sessions`, `messages`	Chat sessions and message history
`model_config`	Model registry and configuration
`cost_log`, `quota_usage`	Token cost and quota tracking
`audit_log`	Security event audit trail (incl. impersonation)
`vault`	AES-256-GCM credential storage with per-user HKDF-derived DEKs
`hooks`, `cron_runs`	Automation hooks and run history
`skill_permissions`, `permission_requests`	Permission overrides and pending approvals
`embeddings`, `documents`	Vector store (pgvector) and ingested docs
`pipelines`, `pipeline_stages`, `pipeline_templates`	Pipeline state
`notifications`	Persistent notification storage
`agent_nodes`, `call_graph_edges`	Swarm call graph (parent/child agents)
`channel_bindings`	Cross-channel identity links

Migrations run automatically on startup unless SKIP_MIGRATIONS=true is set.