Architecture Overview¶

AlexClaw is a BEAM-native personal autonomous AI agent built on Elixir/OTP.

Design Principles¶

• BEAM-native — supervision, concurrency, and fault tolerance are the runtime, not bolted on
• Single-user — one operator, one codebase, fully auditable. Not a platform
• Cost-aware — multi-model LLM router maximizes free tiers across providers
• Runtime-configurable — all settings live in PostgreSQL, cached in ETS, editable via admin UI without restart

Component Diagram¶

Telegram <──> TelegramGateway ──┐
Discord  <──> DiscordGateway  ──┼──> Router ──> Dispatcher ──> Skills
MCP Client <──> MCP.Server ────┘
                                │
Admin UI (Chat) ──────> SkillSupervisor ──> Dynamic Skills
                       (DynamicSupervisor)
Admin UI (Reasoning) ──> Reasoning.Loop ──> Skills (whitelisted)
                        (DynamicSupervisor)
                                │
                 ┌──────────────┼──────────────┐
                 ▼              ▼              ▼
           LLM Router     Memory/Knowledge   Workflows
           (tier-based)   (pgvector)         (cron + on-demand)

Core Components¶

Data Flow¶

A typical workflow execution:

1. Trigger — cron schedule, Telegram command (/run), Admin UI, or MCP tool call
2. Executor — walks the step graph sequentially
3. Per step — resolves skill from registry, checks circuit breaker, executes in supervised task
4. LLM calls — routed by tier to cheapest available provider
5. Results — stored in memory/knowledge, step results persisted to DB
6. Delivery — notify skills send output to Telegram/Discord
7. Audit — run history, step durations, and outcomes recorded

Technology Stack¶