# xvirobotics/metabot architecture

> Architecture diagram of the GitHub repository xvirobotics/metabot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xvirobotics/metabot
- Repository: https://github.com/xvirobotics/metabot

## Overview

MetaBot is a self-hosted personal agent workspace: a user sends a chat or web request, the Bridge routes it to a configured Codex, Kimi, or Claude engine, and the result returns through the originating channel. Its wider product includes a token-authenticated Core Console and server-backed Agents, Memory, Skills, T5T, Teams, and Agent Bus capabilities, plus scheduling, peers, and document sync. Relationships for sampled Bridge and engine modules are supported by the SOURCE INDEX; broader feature links use the README, since most implementation excerpts were not provided.

Main entry points: [`src/bridge/message-bridge.ts`](https://github.com/xvirobotics/metabot/blob/main/src/bridge/message-bridge.ts) (Message bridge), [`packages/server/src/server.ts`](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/server.ts) (Core server), [`src/engines/index.ts`](https://github.com/xvirobotics/metabot/blob/main/src/engines/index.ts) (Engine selection), [`src/feishu/event-handler.ts`](https://github.com/xvirobotics/metabot/blob/main/src/feishu/event-handler.ts) (Feishu adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Chat channels"]
  node_feishu["Feishu adapter<br/>[event-handler.ts]"]
  node_telegram["Telegram bot<br/>[telegram-bot.ts]"]
  node_slack["Slack bot<br/>[slack-bot.ts]"]
  node_wechat["WeChat bot<br/>[wechat-bot.ts]"]
  node_webchat["Web chat API"]
end

subgraph group_runtime["Bridge runtime"]
  node_bridge["Message bridge<br/>[message-bridge.ts]"]
  node_sender["Channel sender"]
  node_outputs["Output files<br/>[outputs-manager.ts]"]
  node_config["Bot configuration<br/>[config.ts]"]
end

subgraph group_engines["Execution engines"]
  node_engines["Engine selection<br/>[index.ts]"]
  node_codex["Codex executor<br/>[executor.ts]"]
  node_kimi["Kimi executor<br/>[executor.ts]"]
  node_claude["Claude executor<br/>[executor.ts]"]
end

subgraph group_core["Core services"]
  node_teams[("Agent Teams<br/>[team-store.ts]")]
  node_peers["Peer manager<br/>[peer-manager.ts]"]
  node_scheduler["Task scheduler<br/>[task-scheduler.ts]"]
  node_sessions[("Session registry")]
  node_sync["Document sync<br/>[doc-sync.ts]"]
end

subgraph group_console["Core Console"]
  node_coreapp["Core server<br/>[server.ts]"]
  node_agentbus["Agent Bus<br/>[message-routes.ts]"]
  node_memory["Memory service<br/>[memory-routes.ts]"]
  node_skills["Skills service<br/>[skill-routes.ts]"]
  node_t5t["T5T service<br/>[t5t-routes.ts]"]
  node_ui["Web Console<br/>[App.tsx]"]
  node_cli["Metabot CLI<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"sends message"| node_feishu
node_user -->|"sends message"| node_telegram
node_user -->|"sends message"| node_slack
node_user -->|"sends message"| node_wechat
node_user -->|"sends request"| node_webchat
node_feishu -->|"routes message"| node_bridge
node_telegram -.->|"routes message"| node_bridge
node_slack -.->|"routes message"| node_bridge
node_wechat -.->|"routes message"| node_bridge
node_webchat -->|"accepts chat run"| node_bridge
node_bridge -->|"dispatches turn"| node_engines
node_engines -->|"creates executor"| node_codex
node_engines -->|"creates executor"| node_kimi
node_engines -->|"creates executor"| node_claude
node_bridge -->|"sends replies"| node_sender
node_bridge -->|"manages outputs"| node_outputs
node_config -->|"selects engine"| node_engines
node_user -->|"opens console"| node_ui
node_ui -->|"uses Core API"| node_coreapp
node_coreapp -.->|"routes bus requests"| node_agentbus
node_coreapp -.->|"serves memory"| node_memory
node_coreapp -.->|"serves skills"| node_skills
node_coreapp -.->|"serves T5T"| node_t5t
node_user -->|"runs commands"| node_cli
node_bridge -.->|"supports teamwork"| node_teams
node_bridge -.->|"forwards peer tasks"| node_peers
node_bridge -.->|"schedules tasks"| node_scheduler
node_bridge -.->|"tracks sessions"| node_sessions
node_bridge -->|"syncs documents"| node_sync

click node_feishu "https://github.com/xvirobotics/metabot/blob/main/src/feishu/event-handler.ts"
click node_telegram "https://github.com/xvirobotics/metabot/blob/main/src/telegram/telegram-bot.ts"
click node_slack "https://github.com/xvirobotics/metabot/blob/main/src/slack/slack-bot.ts"
click node_wechat "https://github.com/xvirobotics/metabot/blob/main/src/wechat/wechat-bot.ts"
click node_webchat "https://github.com/xvirobotics/metabot/blob/main/src/api/routes/core-chat-routes.ts"
click node_bridge "https://github.com/xvirobotics/metabot/blob/main/src/bridge/message-bridge.ts"
click node_sender "https://github.com/xvirobotics/metabot/blob/main/src/bridge/message-sender.interface.ts"
click node_outputs "https://github.com/xvirobotics/metabot/blob/main/src/bridge/outputs-manager.ts"
click node_config "https://github.com/xvirobotics/metabot/blob/main/src/config.ts"
click node_engines "https://github.com/xvirobotics/metabot/blob/main/src/engines/index.ts"
click node_codex "https://github.com/xvirobotics/metabot/blob/main/src/engines/codex/executor.ts"
click node_kimi "https://github.com/xvirobotics/metabot/blob/main/src/engines/kimi/executor.ts"
click node_claude "https://github.com/xvirobotics/metabot/blob/main/src/engines/claude/executor.ts"
click node_teams "https://github.com/xvirobotics/metabot/blob/main/src/agent-teams/team-store.ts"
click node_peers "https://github.com/xvirobotics/metabot/blob/main/src/api/peer-manager.ts"
click node_scheduler "https://github.com/xvirobotics/metabot/blob/main/src/scheduler/task-scheduler.ts"
click node_sessions "https://github.com/xvirobotics/metabot/blob/main/src/session/session-registry.ts"
click node_sync "https://github.com/xvirobotics/metabot/blob/main/src/sync/doc-sync.ts"
click node_coreapp "https://github.com/xvirobotics/metabot/blob/main/packages/server/src/server.ts"
click node_agentbus "https://github.com/xvirobotics/metabot/blob/main/packages/server/src/bus/message-routes.ts"
click node_memory "https://github.com/xvirobotics/metabot/blob/main/packages/server/src/memory/memory-routes.ts"
click node_skills "https://github.com/xvirobotics/metabot/blob/main/packages/server/src/skills/skill-routes.ts"
click node_t5t "https://github.com/xvirobotics/metabot/blob/main/packages/server/src/t5t/t5t-routes.ts"
click node_ui "https://github.com/xvirobotics/metabot/blob/main/packages/web-ui/src/App.tsx"
click node_cli "https://github.com/xvirobotics/metabot/blob/main/packages/cli/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_feishu,node_telegram,node_slack,node_wechat,node_webchat,node_user toneBlue
class node_bridge,node_sender,node_outputs,node_config toneAmber
class node_engines,node_codex,node_kimi,node_claude toneMint
class node_teams,node_peers,node_scheduler,node_sessions,node_sync toneRose
class node_coreapp,node_agentbus,node_memory,node_skills,node_t5t,node_ui,node_cli toneIndigo
```

## Components

### Chat channels

- [Feishu adapter](https://github.com/xvirobotics/metabot/blob/main/src/feishu/event-handler.ts): `src/feishu/event-handler.ts`
- [Telegram bot](https://github.com/xvirobotics/metabot/blob/main/src/telegram/telegram-bot.ts): `src/telegram/telegram-bot.ts`
- [Slack bot](https://github.com/xvirobotics/metabot/blob/main/src/slack/slack-bot.ts): `src/slack/slack-bot.ts`
- [WeChat bot](https://github.com/xvirobotics/metabot/blob/main/src/wechat/wechat-bot.ts): `src/wechat/wechat-bot.ts`
- [Web chat API](https://github.com/xvirobotics/metabot/blob/main/src/api/routes/core-chat-routes.ts): `src/api/routes/core-chat-routes.ts`

### Bridge runtime

- [Message bridge](https://github.com/xvirobotics/metabot/blob/main/src/bridge/message-bridge.ts): `src/bridge/message-bridge.ts`
- [Channel sender](https://github.com/xvirobotics/metabot/blob/main/src/bridge/message-sender.interface.ts): `src/bridge/message-sender.interface.ts`
- [Output files](https://github.com/xvirobotics/metabot/blob/main/src/bridge/outputs-manager.ts): `src/bridge/outputs-manager.ts`
- [Bot configuration](https://github.com/xvirobotics/metabot/blob/main/src/config.ts): `src/config.ts`

### Execution engines

- [Engine selection](https://github.com/xvirobotics/metabot/blob/main/src/engines/index.ts): `src/engines/index.ts`
- [Codex executor](https://github.com/xvirobotics/metabot/blob/main/src/engines/codex/executor.ts): `src/engines/codex/executor.ts`
- [Kimi executor](https://github.com/xvirobotics/metabot/blob/main/src/engines/kimi/executor.ts): `src/engines/kimi/executor.ts`
- [Claude executor](https://github.com/xvirobotics/metabot/blob/main/src/engines/claude/executor.ts): `src/engines/claude/executor.ts`

### Core services

- [Agent Teams](https://github.com/xvirobotics/metabot/blob/main/src/agent-teams/team-store.ts): `src/agent-teams/team-store.ts`
- [Peer manager](https://github.com/xvirobotics/metabot/blob/main/src/api/peer-manager.ts): `src/api/peer-manager.ts`
- [Task scheduler](https://github.com/xvirobotics/metabot/blob/main/src/scheduler/task-scheduler.ts): `src/scheduler/task-scheduler.ts`
- [Session registry](https://github.com/xvirobotics/metabot/blob/main/src/session/session-registry.ts): `src/session/session-registry.ts`
- [Document sync](https://github.com/xvirobotics/metabot/blob/main/src/sync/doc-sync.ts): `src/sync/doc-sync.ts`

### Core Console

- [Core server](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Agent Bus](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/bus/message-routes.ts): `packages/server/src/bus/message-routes.ts`
- [Memory service](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/memory/memory-routes.ts): `packages/server/src/memory/memory-routes.ts`
- [Skills service](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/skills/skill-routes.ts): `packages/server/src/skills/skill-routes.ts`
- [T5T service](https://github.com/xvirobotics/metabot/blob/main/packages/server/src/t5t/t5t-routes.ts): `packages/server/src/t5t/t5t-routes.ts`
- [Web Console](https://github.com/xvirobotics/metabot/blob/main/packages/web-ui/src/App.tsx): `packages/web-ui/src/App.tsx`
- [Metabot CLI](https://github.com/xvirobotics/metabot/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`

### Other components

- **User**

## Connections

- User → Feishu adapter: sends message (evidence: `README.md`)
- User → Telegram bot: sends message (evidence: `README.md`)
- User → Slack bot: sends message (evidence: `README.md`)
- User → WeChat bot: sends message (evidence: `README.md`)
- User → Web chat API: sends request (evidence: `README.md`)
- Feishu adapter → Message bridge: routes message (evidence: `src/index.ts`)
- Telegram bot → Message bridge: routes message
- Slack bot → Message bridge: routes message
- WeChat bot → Message bridge: routes message
- Web chat API → Message bridge: accepts chat run (evidence: `src/api/routes/core-chat-routes.ts`)
- Message bridge → Engine selection: dispatches turn (evidence: `src/bridge/message-bridge.ts`)
- Engine selection → Codex executor: creates executor (evidence: `src/engines/index.ts`)
- Engine selection → Kimi executor: creates executor (evidence: `src/engines/index.ts`)
- Engine selection → Claude executor: creates executor (evidence: `src/engines/index.ts`)
- Message bridge → Channel sender: sends replies (evidence: `src/bridge/message-bridge.ts`)
- Message bridge → Output files: manages outputs (evidence: `src/bridge/message-bridge.ts`)
- Bot configuration → Engine selection: selects engine (evidence: `src/engines/index.ts`)
- User → Web Console: opens console (evidence: `README.md`)
- Web Console → Core server: uses Core API (evidence: `README.md`)
- Core server → Agent Bus: routes bus requests
- Core server → Memory service: serves memory
- Core server → Skills service: serves skills
- Core server → T5T service: serves T5T
- User → Metabot CLI: runs commands (evidence: `README.md`)
- Message bridge → Agent Teams: supports teamwork (evidence: `src/bridge/message-bridge.ts`)
- Message bridge → Peer manager: forwards peer tasks
- Message bridge → Task scheduler: schedules tasks
- Message bridge → Session registry: tracks sessions (evidence: `src/bridge/message-bridge.ts`)
- Message bridge → Document sync: syncs documents (evidence: `src/bridge/message-bridge.ts`)
