# solitary-dev-50/tongdou architecture

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

- Interactive diagram: https://gitdiagram.com/solitary-dev-50/tongdou
- Repository: https://github.com/solitary-dev-50/tongdou

## Overview

The repository contains several firmware variants; this map focuses on the documented developer-oriented demo firmware, not the separate hardware-test firmware. Its principal workflow is a device event or command entering the application, which coordinates scenario selection and execution through robot hardware; the firmware also exposes voice, configuration, reminders, and diagnostics. The sampled App header establishes component wiring, while deeper behavior is only shown for selected modules, so unsampled subsystem internals are represented at their existing directories and uncertain links are omitted.

Main entry points: [`demo_firmware/firmware/src/app/App.cpp`](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/app/App.cpp) (Application), [`demo_firmware/firmware/src/realtime/RealtimeVoiceService.cpp`](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/realtime/RealtimeVoiceService.cpp) (Realtime voice service), [`demo_firmware/firmware/src/hardware/HardwareManager.cpp`](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/hardware/HardwareManager.cpp) (Hardware manager), [`demo_firmware/firmware/src/web/WebConfigServer.cpp`](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/web/WebConfigServer.cpp) (Web configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_app["Application<br/>[App.cpp]"]
  node_commands["App commands"]
  node_reminders["Reminders"]
  node_time["Time service<br/>[TimeService.cpp]"]
end

subgraph group_scenarios["Scenes and behavior"]
  node_scenario_engine["Scenario selection<br/>[ScenarioEngine.cpp]"]
  node_scenario_library["Scenario library"]
  node_scenario_executor["Scenario execution"]
  node_demo_scenes["Demo scene player"]
end

subgraph group_voice["Voice interaction"]
  node_realtime["Realtime voice service"]
  node_audio_sender["Realtime audio sender"]
  node_voice_client["TongDou voice client"]
end

subgraph group_hardware["Robot hardware"]
  node_hardware["Hardware manager"]
  node_hardware_devices["Sensors and actuators"]
  node_gyro_motion["Gyro wiggle control"]
  node_diagnostics["Hardware self-test"]
end

subgraph group_interfaces["Device interfaces"]
  node_web["Web configuration"]
  node_mcp["MCP tools<br/>[McpServer.cpp]"]
  node_wifi_store["Wi-Fi settings"]
  node_scenario_config["Scenario configuration"]
end

node_user(("Device user"))

node_user -->|"uses device"| node_app
node_app -->|"owns"| node_hardware
node_app -->|"owns"| node_scenario_engine
node_app -->|"owns"| node_scenario_executor
node_app -->|"owns"| node_realtime
node_app -->|"owns"| node_reminders
node_app -->|"owns"| node_web
node_app -->|"owns"| node_mcp
node_app -->|"owns"| node_demo_scenes
node_scenario_engine -->|"selects from"| node_scenario_library
node_gyro_motion -->|"reads IMU, drives motors"| node_hardware_devices
node_hardware -->|"provides"| node_diagnostics
node_hardware -->|"manages"| node_hardware_devices
node_scenario_executor -.->|"uses"| node_hardware_devices
node_reminders -->|"uses"| node_time
node_realtime -.->|"coordinates"| node_audio_sender
node_realtime -.->|"uses"| node_voice_client
node_web -.->|"routes configuration"| node_scenario_config
node_web -.->|"uses settings"| node_wifi_store
node_commands -.->|"invokes"| node_scenario_engine
node_commands -.->|"invokes"| node_scenario_executor

click node_app "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/app/App.cpp"
click node_commands "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/app"
click node_reminders "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/reminder"
click node_time "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/system/TimeService.cpp"
click node_scenario_engine "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/scenario/ScenarioEngine.cpp"
click node_scenario_library "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/scenario"
click node_scenario_executor "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/scenario"
click node_demo_scenes "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/demo"
click node_realtime "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/realtime/RealtimeVoiceService.cpp"
click node_audio_sender "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/realtime/RealtimeAudioSender.cpp"
click node_voice_client "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/tongdou_voice/TongDouVoiceClient.cpp"
click node_hardware "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/hardware/HardwareManager.cpp"
click node_hardware_devices "https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/hardware"
click node_gyro_motion "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/motion/GyroReturnWiggleController.cpp"
click node_diagnostics "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/diagnostic/HardwareSelfTestService.cpp"
click node_web "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/web/WebConfigServer.cpp"
click node_mcp "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/mcp/McpServer.cpp"
click node_wifi_store "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/system/WifiConfigStore.cpp"
click node_scenario_config "https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/web/ScenarioConfigApi.cpp"

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_app,node_commands,node_reminders,node_time,node_user toneBlue
class node_scenario_engine,node_scenario_library,node_scenario_executor,node_demo_scenes toneAmber
class node_realtime,node_audio_sender,node_voice_client toneMint
class node_hardware,node_hardware_devices,node_gyro_motion,node_diagnostics toneRose
class node_web,node_mcp,node_wifi_store,node_scenario_config toneIndigo
```

## Components

### Application runtime

- [Application](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/app/App.cpp): `demo_firmware/firmware/src/app/App.cpp`
- [App commands](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/app): `demo_firmware/firmware/src/app`
- [Reminders](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/reminder): `demo_firmware/firmware/src/reminder`
- [Time service](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/system/TimeService.cpp): `demo_firmware/firmware/src/system/TimeService.cpp`

### Scenes and behavior

- [Scenario selection](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/scenario/ScenarioEngine.cpp): `demo_firmware/firmware/src/scenario/ScenarioEngine.cpp`
- [Scenario library](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/scenario): `demo_firmware/firmware/src/scenario`
- [Scenario execution](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/scenario): `demo_firmware/firmware/src/scenario`
- [Demo scene player](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/demo): `demo_firmware/firmware/src/demo`

### Voice interaction

- [Realtime voice service](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/realtime/RealtimeVoiceService.cpp): `demo_firmware/firmware/src/realtime/RealtimeVoiceService.cpp`
- [Realtime audio sender](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/realtime/RealtimeAudioSender.cpp): `demo_firmware/firmware/src/realtime/RealtimeAudioSender.cpp`
- [TongDou voice client](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/tongdou_voice/TongDouVoiceClient.cpp): `demo_firmware/firmware/src/tongdou_voice/TongDouVoiceClient.cpp`

### Robot hardware

- [Hardware manager](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/hardware/HardwareManager.cpp): `demo_firmware/firmware/src/hardware/HardwareManager.cpp`
- [Sensors and actuators](https://github.com/solitary-dev-50/tongdou/tree/main/demo_firmware/firmware/src/hardware): `demo_firmware/firmware/src/hardware`
- [Gyro wiggle control](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/motion/GyroReturnWiggleController.cpp): `demo_firmware/firmware/src/motion/GyroReturnWiggleController.cpp`
- [Hardware self-test](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/diagnostic/HardwareSelfTestService.cpp): `demo_firmware/firmware/src/diagnostic/HardwareSelfTestService.cpp`

### Device interfaces

- [Web configuration](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/web/WebConfigServer.cpp): `demo_firmware/firmware/src/web/WebConfigServer.cpp`
- [MCP tools](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/mcp/McpServer.cpp): `demo_firmware/firmware/src/mcp/McpServer.cpp`
- [Wi-Fi settings](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/system/WifiConfigStore.cpp): `demo_firmware/firmware/src/system/WifiConfigStore.cpp`
- [Scenario configuration](https://github.com/solitary-dev-50/tongdou/blob/main/demo_firmware/firmware/src/web/ScenarioConfigApi.cpp): `demo_firmware/firmware/src/web/ScenarioConfigApi.cpp`

### Other components

- **Device user**

## Connections

- Device user → Application: uses device (evidence: `README.md`)
- Application → Hardware manager: owns
- Application → Scenario selection: owns
- Application → Scenario execution: owns
- Application → Realtime voice service: owns
- Application → Reminders: owns
- Application → Web configuration: owns
- Application → MCP tools: owns
- Application → Demo scene player: owns
- Scenario selection → Scenario library: selects from (evidence: `demo_firmware/firmware/src/scenario/ScenarioEngine.h`)
- Gyro wiggle control → Sensors and actuators: reads IMU, drives motors
- Hardware manager → Hardware self-test: provides
- Hardware manager → Sensors and actuators: manages (evidence: `demo_firmware/firmware/src/hardware/HardwareManager.h`)
- Scenario execution → Sensors and actuators: uses
- Reminders → Time service: uses (evidence: `demo_firmware/firmware/src/reminder/ReminderManager.h`)
- Realtime voice service → Realtime audio sender: coordinates
- Realtime voice service → TongDou voice client: uses
- Web configuration → Scenario configuration: routes configuration
- Web configuration → Wi-Fi settings: uses settings
- App commands → Scenario selection: invokes
- App commands → Scenario execution: invokes (evidence: `demo_firmware/firmware/src/app/App.h`)
