# wzpan/wukong-robot architecture

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

- Interactive diagram: https://gitdiagram.com/wzpan/wukong-robot
- Repository: https://github.com/wzpan/wukong-robot

## Overview

wukong-robot is a modular Chinese voice-conversation robot and smart-speaker runtime. Its principal interaction is wake detection, audio capture and ASR, NLU and skill matching, plugin handling, then TTS and playback. It also supports online/local dialogue engines, reminders, alternative wake sources, and a web administration/API surface. The graph reflects the README’s workflow and sampled lifecycle, speech, plugin, and server excerpts; wiring for unsampled subsystems is shown only where documented capabilities support it.

Main entry points: [`robot/Conversation.py`](https://github.com/wzpan/wukong-robot/blob/master/robot/Conversation.py) (Conversation), [`robot/LifeCycleHandler.py`](https://github.com/wzpan/wukong-robot/blob/master/robot/LifeCycleHandler.py) (Lifecycle handler), [`server/server.py`](https://github.com/wzpan/wukong-robot/blob/master/server/server.py) (Web API server), [`robot/ASR.py`](https://github.com/wzpan/wukong-robot/blob/master/robot/ASR.py) (Speech recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice interaction"]
  node_wake["Wake detection<br/>[snowboydecoder.py]"]
  node_conversation["Conversation<br/>[Conversation.py]"]
  node_asr["Speech recognition<br/>[ASR.py]"]
  node_nlu["Intent parsing<br/>[NLU.py]"]
  node_tts["Speech synthesis<br/>[TTS.py]"]
  node_player["Audio playback<br/>[Player.py]"]
end

subgraph group_skills["Skills and dialogue"]
  node_pluginloader["Plugin loader<br/>[plugin_loader.py]"]
  node_plugins["Skill plugins"]
  node_ai["Dialogue engines<br/>[AI.py]"]
  node_scheduler["Reminder scheduler<br/>[Scheduler.py]"]
  node_reminder["Reminder skill<br/>[Reminder.py]"]
end

subgraph group_runtime["Runtime and devices"]
  node_entry["Robot entry<br/>[wukong.py]"]
  node_lifecycle["Lifecycle handler"]
  node_bci["BCI wake<br/>[BCI.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_devices["Device drivers"]
end

subgraph group_management["Web management"]
  node_server["Web API server<br/>[server.py]"]
  node_webui["Admin interface"]
end

node_user(("User"))
node_speechservices{{"Speech services"}}
node_dialogueservices{{"Dialogue services"}}
node_smartdevices{{"Smart-home services"}}

node_user -->|"speaks wake word"| node_wake
node_entry -->|"initializes"| node_lifecycle
node_lifecycle -->|"starts listening"| node_wake
node_lifecycle -.->|"starts optionally"| node_bci
node_bci -.->|"triggers listening"| node_conversation
node_wake -->|"triggers listening"| node_conversation
node_user -->|"provides speech"| node_conversation
node_conversation -->|"requests transcription"| node_asr
node_asr -.->|"transcribes audio"| node_speechservices
node_asr -->|"passes text"| node_nlu
node_conversation -->|"parses text"| node_nlu
node_conversation -->|"matches skill"| node_pluginloader
node_pluginloader -->|"loads skills"| node_plugins
node_conversation -.->|"requests dialogue"| node_ai
node_ai -.->|"queries service"| node_dialogueservices
node_conversation -->|"synthesizes response"| node_tts
node_tts -.->|"requests synthesis"| node_speechservices
node_conversation -->|"plays response"| node_player
node_player -->|"returns audio"| node_user
node_plugins -->|"schedules reminders"| node_scheduler
node_reminder -->|"adds or removes jobs"| node_scheduler
node_lifecycle -->|"restores reminders"| node_scheduler
node_reminder -->|"speaks alarm"| node_player
node_lifecycle -.->|"signals device state"| node_devices
node_conversation -.->|"reads settings"| node_config
node_lifecycle -->|"loads and watches"| node_config
node_user -->|"uses admin tools"| node_webui
node_webui -->|"calls API"| node_server
node_server -->|"submits text chat"| node_conversation
node_server -->|"reads or updates"| node_config
node_server -->|"returns chat and status"| node_user
node_plugins -.->|"integrates optionally"| node_smartdevices

click node_entry "https://github.com/wzpan/wukong-robot/blob/master/wukong.py"
click node_lifecycle "https://github.com/wzpan/wukong-robot/blob/master/robot/LifeCycleHandler.py"
click node_wake "https://github.com/wzpan/wukong-robot/blob/master/snowboy/snowboydecoder.py"
click node_bci "https://github.com/wzpan/wukong-robot/blob/master/robot/BCI.py"
click node_conversation "https://github.com/wzpan/wukong-robot/blob/master/robot/Conversation.py"
click node_asr "https://github.com/wzpan/wukong-robot/blob/master/robot/ASR.py"
click node_nlu "https://github.com/wzpan/wukong-robot/blob/master/robot/NLU.py"
click node_pluginloader "https://github.com/wzpan/wukong-robot/blob/master/robot/plugin_loader.py"
click node_plugins "https://github.com/wzpan/wukong-robot/tree/master/plugins"
click node_ai "https://github.com/wzpan/wukong-robot/blob/master/robot/AI.py"
click node_tts "https://github.com/wzpan/wukong-robot/blob/master/robot/TTS.py"
click node_player "https://github.com/wzpan/wukong-robot/blob/master/robot/Player.py"
click node_scheduler "https://github.com/wzpan/wukong-robot/blob/master/robot/Scheduler.py"
click node_reminder "https://github.com/wzpan/wukong-robot/blob/master/plugins/Reminder.py"
click node_config "https://github.com/wzpan/wukong-robot/blob/master/robot/config.py"
click node_devices "https://github.com/wzpan/wukong-robot/tree/master/robot/drivers"
click node_server "https://github.com/wzpan/wukong-robot/blob/master/server/server.py"
click node_webui "https://github.com/wzpan/wukong-robot/tree/master/server/static"

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_wake,node_conversation,node_asr,node_nlu,node_tts,node_player,node_user toneBlue
class node_pluginloader,node_plugins,node_ai,node_scheduler,node_reminder toneAmber
class node_entry,node_lifecycle,node_bci,node_config,node_devices toneMint
class node_server,node_webui toneRose
class node_speechservices,node_dialogueservices,node_smartdevices toneIndigo
```

## Components

### Voice interaction

- [Wake detection](https://github.com/wzpan/wukong-robot/blob/master/snowboy/snowboydecoder.py): `snowboy/snowboydecoder.py`
- [Conversation](https://github.com/wzpan/wukong-robot/blob/master/robot/Conversation.py): `robot/Conversation.py`
- [Speech recognition](https://github.com/wzpan/wukong-robot/blob/master/robot/ASR.py): `robot/ASR.py`
- [Intent parsing](https://github.com/wzpan/wukong-robot/blob/master/robot/NLU.py): `robot/NLU.py`
- [Speech synthesis](https://github.com/wzpan/wukong-robot/blob/master/robot/TTS.py): `robot/TTS.py`
- [Audio playback](https://github.com/wzpan/wukong-robot/blob/master/robot/Player.py): `robot/Player.py`

### Skills and dialogue

- [Plugin loader](https://github.com/wzpan/wukong-robot/blob/master/robot/plugin_loader.py): `robot/plugin_loader.py`
- [Skill plugins](https://github.com/wzpan/wukong-robot/tree/master/plugins): `plugins`
- [Dialogue engines](https://github.com/wzpan/wukong-robot/blob/master/robot/AI.py): `robot/AI.py`
- [Reminder scheduler](https://github.com/wzpan/wukong-robot/blob/master/robot/Scheduler.py): `robot/Scheduler.py`
- [Reminder skill](https://github.com/wzpan/wukong-robot/blob/master/plugins/Reminder.py): `plugins/Reminder.py`

### Runtime and devices

- [Robot entry](https://github.com/wzpan/wukong-robot/blob/master/wukong.py): `wukong.py`
- [Lifecycle handler](https://github.com/wzpan/wukong-robot/blob/master/robot/LifeCycleHandler.py): `robot/LifeCycleHandler.py`
- [BCI wake](https://github.com/wzpan/wukong-robot/blob/master/robot/BCI.py): `robot/BCI.py`
- [Configuration](https://github.com/wzpan/wukong-robot/blob/master/robot/config.py): `robot/config.py`
- [Device drivers](https://github.com/wzpan/wukong-robot/tree/master/robot/drivers): `robot/drivers`

### Web management

- [Web API server](https://github.com/wzpan/wukong-robot/blob/master/server/server.py): `server/server.py`
- [Admin interface](https://github.com/wzpan/wukong-robot/tree/master/server/static): `server/static`

### Other components

- **User**
- **Speech services**
- **Dialogue services**
- **Smart-home services**

## Connections

- User → Wake detection: speaks wake word
- Robot entry → Lifecycle handler: initializes
- Lifecycle handler → Wake detection: starts listening
- Lifecycle handler → BCI wake: starts optionally
- BCI wake → Conversation: triggers listening
- Wake detection → Conversation: triggers listening
- User → Conversation: provides speech
- Conversation → Speech recognition: requests transcription
- Speech recognition → Speech services: transcribes audio
- Speech recognition → Intent parsing: passes text
- Conversation → Intent parsing: parses text
- Conversation → Plugin loader: matches skill
- Plugin loader → Skill plugins: loads skills
- Conversation → Dialogue engines: requests dialogue
- Dialogue engines → Dialogue services: queries service
- Conversation → Speech synthesis: synthesizes response
- Speech synthesis → Speech services: requests synthesis
- Conversation → Audio playback: plays response
- Audio playback → User: returns audio
- Skill plugins → Reminder scheduler: schedules reminders
- Reminder skill → Reminder scheduler: adds or removes jobs
- Lifecycle handler → Reminder scheduler: restores reminders
- Reminder skill → Audio playback: speaks alarm
- Lifecycle handler → Device drivers: signals device state
- Conversation → Configuration: reads settings
- Lifecycle handler → Configuration: loads and watches
- User → Admin interface: uses admin tools
- Admin interface → Web API server: calls API
- Web API server → Conversation: submits text chat
- Web API server → Configuration: reads or updates
- Web API server → User: returns chat and status
- Skill plugins → Smart-home services: integrates optionally