Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Web UI (Next.js :3007)                   │
├─────────────────────────────────────────────────────────────────┤
│                     API Server (Elysia :3005)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  REST API │ │WebSocket │ │  Swagger │ │Auth Guard│          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
├─────────────────────────────────────────────────────────────────┤
│                        Core Runtime                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  Agent   │ │  Agent   │ │  Router  │ │Scheduler │          │
│  │ Manager  │ │  Worker  │ │          │ │          │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
├──────────┬──────────┬──────────┬──────────┬────────────────────┤
│ Channels │  Skills  │ Security │  Models  │   Integrations     │
│──────────│──────────│──────────│──────────│────────────────────│
│ Telegram │Filesystem│ Sessions │ Ollama   │ MCP Bridge         │
│ Slack    │ Shell    │ Passkeys │ OpenAI   │ N8N Workflows      │
│ Teams    │ Git      │ TOTP 2FA │Anthropic │ Hooks/Automation   │
│ WebChat  │ Browser  │ Vault    │ Gemini   │ Voice (STT/TTS)    │
│          │          │Permissions│CLI Tools│ Pipelines          │
│          │          │ Notifs   │ LiteLLM  │ Notifications      │
├──────────┴──────────┴──────────┴──────────┴────────────────────┤
│                      Data Layer                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ PostgreSQL   │  │    Redis     │  │   Drizzle    │          │
│  │ + pgvector   │  │   Cache/PubSub│ │     ORM      │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Runtime	Bun
Backend Framework	Elysia
Database ORM	Drizzle
Database	PostgreSQL + pgvector
Cache	Redis (ioredis)
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

assistant/
├── bin/                    # CLI scripts (assistant start/stop)
├── src/
│   ├── api/                # REST API & WebSocket
│   │   ├── routes/         # Endpoint handlers
│   │   ├── middleware/     # Auth guard
│   │   ├── context.ts     # Elysia context plugin
│   │   ├── server.ts      # Server setup
│   │   └── websocket.ts   # WebSocket handler
│   ├── channels/           # Messaging channels
│   │   ├── telegram/       # grammY bot
│   │   ├── slack/          # Bolt.js integration
│   │   ├── teams/          # Bot Framework
│   │   ├── webchat/        # WebSocket chat
│   │   └── linking.ts     # Cross-channel user linking
│   ├── config/             # Zod-validated configuration
│   │   ├── index.ts        # Cache, getConfig(), re-exports
│   │   ├── schema.ts       # Zod schema & Config type
│   │   ├── defaults.ts     # Default values
│   │   ├── bootstrap-loader.ts  # Env-only config (pre-DB)
│   │   ├── legacy-loader.ts     # Full env config (migration)
│   │   ├── runtime-loader.ts    # DB-backed config loader
│   │   ├── settings-service.ts  # Three-tier cache + pub/sub
│   │   ├── settings-registry.ts # Setting definitions manifest
│   │   ├── hot-reload.ts   # Live config updates
│   │   └── utils.ts        # deepMerge helper
│   ├── core/               # Agent runtime
│   │   ├── agent-base.ts   # BaseAgentWorker abstract class
│   │   ├── agent-worker.ts # LLM agent (extends base)
│   │   ├── cli-agent-worker.ts  # CLI agent (extends base)
│   │   ├── tool-executor.ts     # Tool execution & permissions
│   │   ├── cli-adapters.ts      # CLI argument builder & output parser
│   │   ├── agent-manager.ts
│   │   ├── gateway.ts
│   │   ├── router.ts
│   │   ├── scheduler.ts
│   │   ├── notification-service.ts
│   │   ├── orchestrator/   # Multi-agent orchestration
│   │   │   ├── service.ts           # Message routing
│   │   │   ├── approval-manager.ts  # User approval lifecycle
│   │   │   ├── model-selector.ts    # Model selection & fallback
│   │   │   ├── meta-tools.ts        # Orchestrator tool definitions
│   │   │   ├── pipeline-manager.ts  # Multi-stage pipelines
│   │   │   ├── classifier.ts        # Message classification
│   │   │   ├── roles.ts    # Role configs & tool sets
│   │   │   └── types.ts
│   │   └── types.ts
│   ├── db/                 # Database layer
│   │   ├── schema/         # Drizzle table definitions
│   │   ├── repositories/   # Data access layer
│   │   ├── migrations/     # SQL migrations
│   │   ├── postgres.ts     # Connection management
│   │   └── redis.ts        # Redis cache wrapper
│   ├── hooks/              # Event-driven automation
│   ├── mcp/                # Model Context Protocol
│   │   ├── bridge.ts       # Server connection manager
│   │   ├── protocol.ts     # MCP message handling
│   │   └── transports/     # Stdio & SSE transports
│   ├── models/             # LLM management
│   │   ├── providers/      # Direct, CLI, LiteLLM providers
│   │   ├── litellm-client.ts
│   │   ├── model-registry.ts
│   │   ├── cost-tracker.ts
│   │   ├── quota-tracker.ts
│   │   └── health-checker.ts
│   ├── security/           # Auth & encryption
│   │   ├── auth/           # Session, passkey, TOTP
│   │   ├── vault.ts        # AES-256-GCM encrypted storage
│   │   ├── permissions.ts  # Three-tier permission system
│   │   └── secret-injector.ts
│   ├── skills/             # Built-in tool implementations
│   │   ├── filesystem/
│   │   ├── shell/
│   │   ├── git/
│   │   ├── browser/
│   │   ├── websearch/
│   │   └── docker/
│   ├── utils/              # Crypto, logger, sanitize
│   ├── visual/             # Playwright visual debugger
│   ├── voice/              # STT, TTS, wake word
│   └── index.ts            # Entry point
├── mcp-server/             # MCP server bridge for CLI models
│   ├── src/
│   │   ├── index.ts        # Entry point (stdio/HTTP)
│   │   ├── server.ts       # McpServer setup
│   │   ├── client.ts       # HTTP client
│   │   ├── auth.ts         # Auth helper
│   │   └── tools/          # Tool definitions
│   ├── package.json
│   └── tsconfig.json
├── web/                    # Next.js 14 web UI
│   ├── app/                # App Router pages
│   ├── components/         # React components
│   └── lib/
│       ├── api.ts          # API client
│       └── types/          # TypeScript interfaces
├── scripts/
│   ├── db/                 # Database utility scripts
│   ├── e2e/                # E2E test suite
│   └── setup.ts            # Bootstrap setup wizard
├── octipus.desktop       # Linux desktop entry
├── .mcp.json               # Claude Code MCP server config
├── package.json
├── tsconfig.json
└── drizzle.config.ts

Database Schema

Key database tables managed by Drizzle ORM:

Table	Purpose
users	User accounts and credentials
sessions	Chat sessions
messages	Message history
model_config	Model registry and configuration
cost_log	Token cost tracking
audit_log	Security event audit trail
vault	Encrypted credential storage
hooks	Automation hook definitions
skill_permissions	Per-user permission overrides
permission_requests	Pending approval requests
embeddings	Vector embeddings (pgvector)
pipelines	Pipeline run instances
pipeline_stages	Individual pipeline stages
pipeline_templates	Reusable pipeline templates
notifications	Persistent notification storage

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