# chfly2024/mimiclaw architecture

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

- Interactive diagram: https://gitdiagram.com/chfly2024/mimiclaw
- Repository: https://github.com/chfly2024/mimiclaw

## Overview

MimiClaw is an ESP32-S3 AI assistant. Its main workflow takes messages from Telegram or Feishu over WiFi, places them on a message bus, runs an agent loop that builds context and calls an LLM and tools, then dispatches replies back to the originating channel. Local memory and sessions, scheduling, skills, setup, and administration support that workflow. Relationships are based on the README, the shown application entry point, and SOURCE INDEX references; unsampled tool implementations are represented at their enclosing directory where appropriate.

Main entry points: [`main/bus/message_bus.c`](https://github.com/chfly2024/mimiclaw/blob/main/main/bus/message_bus.c) (Message Bus), [`main/mimi.c`](https://github.com/chfly2024/mimiclaw/blob/main/main/mimi.c) (ESP32 Device), [`main/agent/agent_loop.c`](https://github.com/chfly2024/mimiclaw/blob/main/main/agent/agent_loop.c) (Agent Loop), [`main/cli/serial_cli.c`](https://github.com/chfly2024/mimiclaw/blob/main/main/cli/serial_cli.c) (Serial CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connectivity["Connectivity"]
  node_telegram["Telegram Bot<br/>[telegram_bot.c]"]
  node_feishu["Feishu Bot<br/>[feishu_bot.c]"]
  node_wifi["WiFi Manager<br/>[wifi_manager.c]"]
  node_gateway["WebSocket Gateway<br/>[ws_server.c]"]
  node_proxy["HTTP Proxy<br/>[http_proxy.c]"]
end

subgraph group_assistant["Assistant Runtime"]
  node_bus["Message Bus<br/>[message_bus.c]"]
  node_agent["Agent Loop<br/>[agent_loop.c]"]
  node_context["Context Builder<br/>[context_builder.c]"]
  node_llm["LLM Proxy<br/>[llm_proxy.c]"]
  node_sessions[("Session Manager<br/>[session_mgr.c]")]
  node_memory[("Memory Store<br/>[memory_store.c]")]
end

subgraph group_capabilities["Assistant Capabilities"]
  node_tools["Tool Registry<br/>[tool_registry.c]"]
  node_websearch["Web Search<br/>[tool_web_search.c]"]
  node_toolset["Device Tools"]
  node_skills["Skills<br/>[skill_loader.c]"]
  node_cron["Cron Service<br/>[cron_service.c]"]
  node_heartbeat["Heartbeat<br/>[heartbeat.c]"]
end

subgraph group_operations["Device Operations"]
  node_cli["Serial CLI<br/>[serial_cli.c]"]
  node_onboard["WiFi Onboarding<br/>[wifi_onboard.c]"]
  node_device["ESP32 Device<br/>[mimi.c]"]
end

node_user(("User"))
node_llmprovider{{"Anthropic / OpenAI"}}
node_searchservice{{"Search APIs"}}

node_user -->|"sends message"| node_telegram
node_telegram -->|"queues inbound"| node_bus
node_user -.->|"sends message"| node_feishu
node_feishu -->|"queues inbound"| node_bus
node_bus -->|"delivers inbound"| node_agent
node_agent -->|"builds context"| node_context
node_agent -->|"loads history"| node_sessions
node_agent -->|"requests completion"| node_llm
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"queues reply"| node_bus
node_context -->|"reads memory"| node_memory
node_context -->|"includes skills"| node_skills
node_llm -->|"calls API"| node_llmprovider
node_tools -.->|"dispatches search"| node_websearch
node_tools -.->|"dispatches tools"| node_toolset
node_websearch -.->|"queries provider"| node_searchservice
node_cron -->|"queues due jobs"| node_bus
node_heartbeat -->|"queues checks"| node_bus
node_bus -->|"routes reply"| node_telegram
node_bus -->|"routes reply"| node_feishu
node_bus -->|"routes reply"| node_gateway
node_gateway -->|"queues inbound"| node_bus
node_cli -->|"manages sessions"| node_sessions
node_cli -->|"reads and writes"| node_memory
node_cli -->|"starts scheduler"| node_cron
node_cli -->|"sets credentials"| node_wifi
node_onboard -->|"configures network"| node_wifi
node_telegram -->|"uses HTTPS proxy"| node_proxy
node_feishu -->|"uses HTTPS proxy"| node_proxy
node_llm -->|"uses HTTPS proxy"| node_proxy
node_device -->|"initializes and starts"| node_wifi
node_device -->|"starts setup portal"| node_onboard
node_device -->|"initializes queues"| node_bus
node_device -->|"starts agent"| node_agent
node_device -->|"starts console"| node_cli
node_device -->|"starts scheduler"| node_cron
node_device -->|"starts heartbeat"| node_heartbeat

click node_telegram "https://github.com/chfly2024/mimiclaw/blob/main/main/channels/telegram/telegram_bot.c"
click node_feishu "https://github.com/chfly2024/mimiclaw/blob/main/main/channels/feishu/feishu_bot.c"
click node_wifi "https://github.com/chfly2024/mimiclaw/blob/main/main/wifi/wifi_manager.c"
click node_bus "https://github.com/chfly2024/mimiclaw/blob/main/main/bus/message_bus.c"
click node_agent "https://github.com/chfly2024/mimiclaw/blob/main/main/agent/agent_loop.c"
click node_context "https://github.com/chfly2024/mimiclaw/blob/main/main/agent/context_builder.c"
click node_llm "https://github.com/chfly2024/mimiclaw/blob/main/main/llm/llm_proxy.c"
click node_sessions "https://github.com/chfly2024/mimiclaw/blob/main/main/memory/session_mgr.c"
click node_memory "https://github.com/chfly2024/mimiclaw/blob/main/main/memory/memory_store.c"
click node_tools "https://github.com/chfly2024/mimiclaw/blob/main/main/tools/tool_registry.c"
click node_websearch "https://github.com/chfly2024/mimiclaw/blob/main/main/tools/tool_web_search.c"
click node_toolset "https://github.com/chfly2024/mimiclaw/tree/main/main/tools"
click node_skills "https://github.com/chfly2024/mimiclaw/blob/main/main/skills/skill_loader.c"
click node_cron "https://github.com/chfly2024/mimiclaw/blob/main/main/cron/cron_service.c"
click node_heartbeat "https://github.com/chfly2024/mimiclaw/blob/main/main/heartbeat/heartbeat.c"
click node_gateway "https://github.com/chfly2024/mimiclaw/blob/main/main/gateway/ws_server.c"
click node_cli "https://github.com/chfly2024/mimiclaw/blob/main/main/cli/serial_cli.c"
click node_onboard "https://github.com/chfly2024/mimiclaw/blob/main/main/onboard/wifi_onboard.c"
click node_proxy "https://github.com/chfly2024/mimiclaw/blob/main/main/proxy/http_proxy.c"
click node_device "https://github.com/chfly2024/mimiclaw/blob/main/main/mimi.c"

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_telegram,node_feishu,node_wifi,node_gateway,node_proxy,node_user toneBlue
class node_bus,node_agent,node_context,node_llm,node_sessions,node_memory toneAmber
class node_tools,node_websearch,node_toolset,node_skills,node_cron,node_heartbeat,node_searchservice toneMint
class node_cli,node_onboard,node_device toneRose
class node_llmprovider toneIndigo
```

## Components

### Connectivity

- [Telegram Bot](https://github.com/chfly2024/mimiclaw/blob/main/main/channels/telegram/telegram_bot.c): `main/channels/telegram/telegram_bot.c`
- [Feishu Bot](https://github.com/chfly2024/mimiclaw/blob/main/main/channels/feishu/feishu_bot.c): `main/channels/feishu/feishu_bot.c`
- [WiFi Manager](https://github.com/chfly2024/mimiclaw/blob/main/main/wifi/wifi_manager.c): `main/wifi/wifi_manager.c`
- [WebSocket Gateway](https://github.com/chfly2024/mimiclaw/blob/main/main/gateway/ws_server.c): `main/gateway/ws_server.c`
- [HTTP Proxy](https://github.com/chfly2024/mimiclaw/blob/main/main/proxy/http_proxy.c): `main/proxy/http_proxy.c`

### Assistant Runtime

- [Message Bus](https://github.com/chfly2024/mimiclaw/blob/main/main/bus/message_bus.c): `main/bus/message_bus.c`
- [Agent Loop](https://github.com/chfly2024/mimiclaw/blob/main/main/agent/agent_loop.c): `main/agent/agent_loop.c`
- [Context Builder](https://github.com/chfly2024/mimiclaw/blob/main/main/agent/context_builder.c): `main/agent/context_builder.c`
- [LLM Proxy](https://github.com/chfly2024/mimiclaw/blob/main/main/llm/llm_proxy.c): `main/llm/llm_proxy.c`
- [Session Manager](https://github.com/chfly2024/mimiclaw/blob/main/main/memory/session_mgr.c): `main/memory/session_mgr.c`
- [Memory Store](https://github.com/chfly2024/mimiclaw/blob/main/main/memory/memory_store.c): `main/memory/memory_store.c`

### Assistant Capabilities

- [Tool Registry](https://github.com/chfly2024/mimiclaw/blob/main/main/tools/tool_registry.c): `main/tools/tool_registry.c`
- [Web Search](https://github.com/chfly2024/mimiclaw/blob/main/main/tools/tool_web_search.c): `main/tools/tool_web_search.c`
- [Device Tools](https://github.com/chfly2024/mimiclaw/tree/main/main/tools): `main/tools`
- [Skills](https://github.com/chfly2024/mimiclaw/blob/main/main/skills/skill_loader.c): `main/skills/skill_loader.c`
- [Cron Service](https://github.com/chfly2024/mimiclaw/blob/main/main/cron/cron_service.c): `main/cron/cron_service.c`
- [Heartbeat](https://github.com/chfly2024/mimiclaw/blob/main/main/heartbeat/heartbeat.c): `main/heartbeat/heartbeat.c`

### Device Operations

- [Serial CLI](https://github.com/chfly2024/mimiclaw/blob/main/main/cli/serial_cli.c): `main/cli/serial_cli.c`
- [WiFi Onboarding](https://github.com/chfly2024/mimiclaw/blob/main/main/onboard/wifi_onboard.c): `main/onboard/wifi_onboard.c`
- [ESP32 Device](https://github.com/chfly2024/mimiclaw/blob/main/main/mimi.c): `main/mimi.c`

### Other components

- **User**
- **Anthropic / OpenAI**
- **Search APIs**

## Connections

- User → Telegram Bot: sends message (evidence: `README.md`)
- Telegram Bot → Message Bus: queues inbound (evidence: `main/channels/telegram/telegram_bot.c`)
- User → Feishu Bot: sends message (evidence: `README.md`)
- Feishu Bot → Message Bus: queues inbound (evidence: `main/channels/feishu/feishu_bot.c`)
- Message Bus → Agent Loop: delivers inbound (evidence: `main/agent/agent_loop.c`)
- Agent Loop → Context Builder: builds context (evidence: `main/agent/agent_loop.c`)
- Agent Loop → Session Manager: loads history (evidence: `main/agent/agent_loop.c`)
- Agent Loop → LLM Proxy: requests completion (evidence: `main/agent/agent_loop.c`)
- Agent Loop → Tool Registry: dispatches tools (evidence: `main/agent/agent_loop.c`)
- Agent Loop → Message Bus: queues reply (evidence: `main/agent/agent_loop.c`)
- Context Builder → Memory Store: reads memory (evidence: `main/agent/context_builder.c`)
- Context Builder → Skills: includes skills (evidence: `main/agent/context_builder.c`)
- LLM Proxy → Anthropic / OpenAI: calls API (evidence: `README.md`)
- Tool Registry → Web Search: dispatches search
- Tool Registry → Device Tools: dispatches tools
- Web Search → Search APIs: queries provider
- Cron Service → Message Bus: queues due jobs (evidence: `main/cron/cron_service.c`)
- Heartbeat → Message Bus: queues checks (evidence: `main/heartbeat/heartbeat.c`)
- Message Bus → Telegram Bot: routes reply
- Message Bus → Feishu Bot: routes reply
- Message Bus → WebSocket Gateway: routes reply
- WebSocket Gateway → Message Bus: queues inbound (evidence: `main/gateway/ws_server.c`)
- Serial CLI → Session Manager: manages sessions (evidence: `main/cli/serial_cli.c`)
- Serial CLI → Memory Store: reads and writes (evidence: `main/cli/serial_cli.c`)
- Serial CLI → Cron Service: starts scheduler (evidence: `main/cli/serial_cli.c`)
- Serial CLI → WiFi Manager: sets credentials (evidence: `main/cli/serial_cli.c`)
- WiFi Onboarding → WiFi Manager: configures network (evidence: `main/onboard/wifi_onboard.c`)
- Telegram Bot → HTTP Proxy: uses HTTPS proxy (evidence: `main/channels/telegram/telegram_bot.c`)
- Feishu Bot → HTTP Proxy: uses HTTPS proxy (evidence: `main/channels/feishu/feishu_bot.c`)
- LLM Proxy → HTTP Proxy: uses HTTPS proxy (evidence: `main/llm/llm_proxy.c`)
- ESP32 Device → WiFi Manager: initializes and starts (evidence: `main/mimi.c`)
- ESP32 Device → WiFi Onboarding: starts setup portal (evidence: `main/mimi.c`)
- ESP32 Device → Message Bus: initializes queues (evidence: `main/mimi.c`)
- ESP32 Device → Agent Loop: starts agent (evidence: `main/mimi.c`)
- ESP32 Device → Serial CLI: starts console (evidence: `main/mimi.c`)
- ESP32 Device → Cron Service: starts scheduler (evidence: `main/mimi.c`)
- ESP32 Device → Heartbeat: starts heartbeat (evidence: `main/mimi.c`)
