# lara-srl/xiaozhi-openclaw architecture

> Architecture diagram of the GitHub repository lara-srl/xiaozhi-openclaw, 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/lara-srl/xiaozhi-openclaw
- Repository: https://github.com/lara-srl/xiaozhi-openclaw

## Overview

XiaoZhi is ESP32 voice-chatbot firmware: a user speaks or invokes device controls, audio is captured and processed, and a selected network protocol exchanges the interaction with an AI service; replies are played and shown on-device. Application coordinates startup and device state, while board implementations adapt the firmware to many supported hardware designs. The README also documents wake-word detection, MCP control, displays, assets, power management, and multiple connectivity options. Several subsystems are documented but their full implementation was not sampled, so those relationships are cited to the README rather than inferred from filenames.

Main entry points: [`main/application.cc`](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/application.cc) (Application), [`main/audio/audio_service.cc`](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/audio_service.cc) (Audio service), [`main/boards/common/board.cc`](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/board.cc) (Board adapter), [`main/protocols/protocol.cc`](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/protocol.cc) (Protocol interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime coordination"]
  node_application["Application<br/>[application.cc]"]
  node_device_state["Device state"]
  node_settings[("Settings<br/>[settings.cc]")]
end

subgraph group_audio["Voice pipeline"]
  node_audio_service["Audio service<br/>[audio_service.cc]"]
  node_audio_codec["Audio codec<br/>[audio_codec.cc]"]
  node_wake_word["Wake words"]
  node_audio_processor["Audio processing"]
  node_ogg_demuxer["OGG demuxer<br/>[ogg_demuxer.cc]"]
end

subgraph group_connectivity["Network and control"]
  node_protocol["Protocol interface<br/>[protocol.cc]"]
  node_websocket["WebSocket protocol"]
  node_mqtt["MQTT protocol<br/>[mqtt_protocol.cc]"]
  node_mcp["MCP server<br/>[mcp_server.cc]"]
end

subgraph group_device["Hardware and interface"]
  node_board["Board adapter<br/>[board.cc]"]
  node_display["Display<br/>[display.cc]"]
  node_assets["Custom assets<br/>[assets.cc]"]
  node_camera["Camera<br/>[esp32_camera.cc]"]
  node_led["LED control<br/>[led.h]"]
  node_power["Power management"]
end

node_user(("User"))
node_ai_service(("AI service"))

node_user -.->|"starts interaction"| node_application
node_application -->|"gets hardware"| node_board
node_application -->|"transitions state"| node_device_state
node_application -->|"initializes audio"| node_audio_service
node_application -->|"sets up UI"| node_display
node_audio_service -->|"starts codec"| node_audio_codec
node_audio_service -->|"initializes detection"| node_wake_word
node_audio_service -->|"initializes processor"| node_audio_processor
node_audio_service -.->|"uses for playback"| node_ogg_demuxer
node_application -->|"initializes protocol"| node_protocol
node_protocol -.->|"selects transport"| node_websocket
node_protocol -.->|"selects transport"| node_mqtt
node_websocket -.->|"exchanges chat"| node_ai_service
node_mqtt -.->|"exchanges chat"| node_ai_service
node_application -.->|"supports device control"| node_mcp
node_mcp -.->|"invokes device actions"| node_board
node_application -.->|"uses configuration"| node_settings
node_board -.->|"provides camera"| node_camera
node_board -.->|"provides LED"| node_led
node_board -.->|"manages power"| node_power
node_display -.->|"shows custom assets"| node_assets
node_ai_service -.->|"returns voice reply"| node_user

click node_application "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/application.cc"
click node_device_state "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/device_state_machine.cc"
click node_board "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/board.cc"
click node_audio_service "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/audio_service.cc"
click node_audio_codec "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/audio_codec.cc"
click node_wake_word "https://github.com/lara-srl/xiaozhi-openclaw/tree/main/main/audio/wake_words"
click node_audio_processor "https://github.com/lara-srl/xiaozhi-openclaw/tree/main/main/audio/processors"
click node_ogg_demuxer "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/demuxer/ogg_demuxer.cc"
click node_protocol "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/protocol.cc"
click node_websocket "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/websocket_protocol.cc"
click node_mqtt "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/mqtt_protocol.cc"
click node_mcp "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/mcp_server.cc"
click node_settings "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/settings.cc"
click node_display "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/display/display.cc"
click node_assets "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/assets.cc"
click node_camera "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/esp32_camera.cc"
click node_led "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/led/led.h"
click node_power "https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/power_save_timer.cc"

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_application,node_device_state,node_settings,node_user toneBlue
class node_audio_service,node_audio_codec,node_wake_word,node_audio_processor,node_ogg_demuxer toneAmber
class node_protocol,node_websocket,node_mqtt,node_mcp toneMint
class node_board,node_display,node_assets,node_camera,node_led,node_power toneRose
class node_ai_service toneIndigo
```

## Components

### Runtime coordination

- [Application](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/application.cc): `main/application.cc`
- [Device state](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/device_state_machine.cc): `main/device_state_machine.cc`
- [Settings](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/settings.cc): `main/settings.cc`

### Voice pipeline

- [Audio service](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/audio_service.cc): `main/audio/audio_service.cc`
- [Audio codec](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/audio_codec.cc): `main/audio/audio_codec.cc`
- [Wake words](https://github.com/lara-srl/xiaozhi-openclaw/tree/main/main/audio/wake_words): `main/audio/wake_words`
- [Audio processing](https://github.com/lara-srl/xiaozhi-openclaw/tree/main/main/audio/processors): `main/audio/processors`
- [OGG demuxer](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/audio/demuxer/ogg_demuxer.cc): `main/audio/demuxer/ogg_demuxer.cc`

### Network and control

- [Protocol interface](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/protocol.cc): `main/protocols/protocol.cc`
- [WebSocket protocol](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/websocket_protocol.cc): `main/protocols/websocket_protocol.cc`
- [MQTT protocol](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/protocols/mqtt_protocol.cc): `main/protocols/mqtt_protocol.cc`
- [MCP server](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/mcp_server.cc): `main/mcp_server.cc`

### Hardware and interface

- [Board adapter](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/board.cc): `main/boards/common/board.cc`
- [Display](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/display/display.cc): `main/display/display.cc`
- [Custom assets](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/assets.cc): `main/assets.cc`
- [Camera](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/esp32_camera.cc): `main/boards/common/esp32_camera.cc`
- [LED control](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/led/led.h): `main/led/led.h`
- [Power management](https://github.com/lara-srl/xiaozhi-openclaw/blob/main/main/boards/common/power_save_timer.cc): `main/boards/common/power_save_timer.cc`

### Other components

- **User**
- **AI service**

## Connections

- User → Application: starts interaction (evidence: `README.md`)
- Application → Board adapter: gets hardware (evidence: `main/application.cc`)
- Application → Device state: transitions state (evidence: `main/application.cc`)
- Application → Audio service: initializes audio (evidence: `main/application.cc`)
- Application → Display: sets up UI (evidence: `main/application.cc`)
- Audio service → Audio codec: starts codec (evidence: `main/audio/audio_service.cc`)
- Audio service → Wake words: initializes detection (evidence: `main/audio/audio_service.cc`)
- Audio service → Audio processing: initializes processor (evidence: `main/audio/audio_service.cc`)
- Audio service → OGG demuxer: uses for playback
- Application → Protocol interface: initializes protocol (evidence: `main/application.cc`)
- Protocol interface → WebSocket protocol: selects transport (evidence: `README.md`)
- Protocol interface → MQTT protocol: selects transport (evidence: `README.md`)
- WebSocket protocol → AI service: exchanges chat (evidence: `README.md`)
- MQTT protocol → AI service: exchanges chat (evidence: `README.md`)
- Application → MCP server: supports device control (evidence: `README.md`)
- MCP server → Board adapter: invokes device actions (evidence: `README.md`)
- Application → Settings: uses configuration
- Board adapter → Camera: provides camera (evidence: `README.md`)
- Board adapter → LED control: provides LED (evidence: `README.md`)
- Board adapter → Power management: manages power (evidence: `README.md`)
- Display → Custom assets: shows custom assets (evidence: `README.md`)
- AI service → User: returns voice reply (evidence: `README.md`)
