# samubraila/stackchan architecture

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

- Interactive diagram: https://gitdiagram.com/samubraila/stackchan
- Repository: https://github.com/samubraila/stackchan

## Overview

StackChan is an open-source AI desktop robot ecosystem: CoreS3 firmware drives the robot, with a handheld ESP-NOW controller, iOS/Android mobile apps, a desktop BLE tool, and a Go server. The principal user workflow is controlling or configuring the robot through its screens or companion apps, then seeing movement, expression, or video on the robot/app. Firmware capabilities also include AI-agent interaction, dances, app downloads, and OTA. Groups show the separate products; edges are limited to relationships visible in excerpts or explicitly documented in the README.

Main entry points: [`firmware/main/apps/apps.h`](https://github.com/samubraila/stackchan/blob/main/firmware/main/apps/apps.h) (Built-in apps), [`firmware/main/main.cpp`](https://github.com/samubraila/stackchan/blob/main/firmware/main/main.cpp) (Firmware runtime), [`app/ios/Runner/SceneDelegate.swift`](https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/SceneDelegate.swift) (iOS app setup), [`remote/code/main/StackChan-RemoteControl-ESPNow.cpp`](https://github.com/samubraila/stackchan/blob/main/remote/code/main/StackChan-RemoteControl-ESPNow.cpp) (Remote runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Robot firmware"]
  node_fw_entry["Firmware runtime<br/>[main.cpp]"]
  node_app_registry["Built-in apps<br/>[apps.h]"]
  node_launcher["App launcher"]
  node_ai_agent["AI agent"]
  node_avatar["Avatar display"]
  node_dance["Dance playback"]
  node_app_center["App downloads"]
  node_setup["Device setup"]
  node_ezdata["EZData app"]
  node_motion["Motion and servos"]
  node_avatar_engine["Avatar rendering"]
  node_hal["Hardware interface"]
end

subgraph group_remote["Remote controller"]
  node_remote_main["Remote runtime"]
  node_joystick["Joystick control<br/>[joystick_handle.c]"]
  node_remote_ui["Remote screens"]
  node_espnow["ESP-NOW link"]
end

subgraph group_mobile["Mobile apps"]
  node_ios_ar["AR robot view"]
  node_ios_bridge["iOS native bridge<br/>[NativeBridge.swift]"]
  node_ios_setup["iOS app setup"]
  node_android_app["Android app<br/>[MainActivity.kt]"]
end

subgraph group_backend["Cloud services"]
  node_server["Go service"]
  node_server_api["Service APIs"]
  node_server_services["Domain services"]
end

subgraph group_desktop["Desktop tool"]
  node_desktop_app["Desktop interface<br/>[app.js]"]
  node_desktop_ble["Desktop BLE<br/>[ble.js]"]
end

node_user(("Robot user"))

node_user -->|"uses robot"| node_fw_entry
node_user -->|"uses controller"| node_remote_main
node_user -->|"uses mobile app"| node_ios_setup
node_fw_entry -.->|"loads apps"| node_app_registry
node_app_registry -->|"registers"| node_launcher
node_app_registry -->|"registers"| node_ai_agent
node_app_registry -->|"registers"| node_avatar
node_app_registry -->|"registers"| node_dance
node_app_registry -->|"registers"| node_app_center
node_app_registry -->|"registers"| node_setup
node_app_registry -->|"registers"| node_ezdata
node_remote_main -->|"starts tasks"| node_joystick
node_remote_main -->|"initializes UI"| node_remote_ui
node_remote_main -->|"initializes link"| node_espnow
node_joystick -->|"sends commands"| node_espnow
node_remote_main -.->|"controls robot"| node_user
node_ios_setup -->|"sets up bridge"| node_ios_bridge
node_ios_setup -->|"registers view"| node_ios_ar
node_ios_ar -.->|"shows robot view"| node_user
node_ios_setup -.->|"parallel app"| node_android_app
node_ios_setup -.->|"companion integration"| node_server
node_ios_setup -.->|"connects to robot"| node_fw_entry
node_server -.->|"exposes endpoints"| node_server_api
node_server_api -.->|"delegates domain work"| node_server_services
node_desktop_app -.->|"uses BLE"| node_desktop_ble
node_desktop_ble -.->|"controls robot"| node_fw_entry
node_fw_entry -.->|"downloads apps"| node_app_center
node_fw_entry -.->|"online updates"| node_server
node_ios_ar -.->|"remote avatar control"| node_fw_entry
node_ios_ar -.->|"views video"| node_fw_entry

click node_fw_entry "https://github.com/samubraila/stackchan/blob/main/firmware/main/main.cpp"
click node_app_registry "https://github.com/samubraila/stackchan/blob/main/firmware/main/apps/apps.h"
click node_launcher "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_launcher"
click node_ai_agent "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_ai_agent"
click node_avatar "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_avatar"
click node_dance "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_dance"
click node_app_center "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_app_center"
click node_setup "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_setup"
click node_ezdata "https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_ezdata"
click node_motion "https://github.com/samubraila/stackchan/tree/main/firmware/main/stackchan/motion"
click node_avatar_engine "https://github.com/samubraila/stackchan/tree/main/firmware/main/stackchan/avatar"
click node_hal "https://github.com/samubraila/stackchan/tree/main/firmware/main/hal"
click node_remote_main "https://github.com/samubraila/stackchan/blob/main/remote/code/main/StackChan-RemoteControl-ESPNow.cpp"
click node_joystick "https://github.com/samubraila/stackchan/blob/main/remote/code/main/joystick/joystick_handle.c"
click node_remote_ui "https://github.com/samubraila/stackchan/tree/main/remote/code/main/ui"
click node_espnow "https://github.com/samubraila/stackchan/tree/main/remote/code/main/esp_now"
click node_ios_ar "https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/View/StackChanArView.swift"
click node_ios_bridge "https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/Utils/NativeBridge.swift"
click node_ios_setup "https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/SceneDelegate.swift"
click node_android_app "https://github.com/samubraila/stackchan/blob/main/app/android/app/src/main/kotlin/com/m5stack/stackchan/MainActivity.kt"
click node_server "https://github.com/samubraila/stackchan/tree/main/server"
click node_server_api "https://github.com/samubraila/stackchan/tree/main/server/api"
click node_server_services "https://github.com/samubraila/stackchan/tree/main/server/internal/service"
click node_desktop_app "https://github.com/samubraila/stackchan/blob/main/desktop/renderer/app.js"
click node_desktop_ble "https://github.com/samubraila/stackchan/blob/main/desktop/renderer/ble.js"

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_fw_entry,node_app_registry,node_launcher,node_ai_agent,node_avatar,node_dance,node_app_center,node_setup,node_ezdata,node_motion,node_avatar_engine,node_hal,node_user toneBlue
class node_remote_main,node_joystick,node_remote_ui,node_espnow toneAmber
class node_ios_ar,node_ios_bridge,node_ios_setup,node_android_app toneMint
class node_server,node_server_api,node_server_services toneRose
class node_desktop_app,node_desktop_ble toneIndigo
```

## Components

### Robot firmware

- [Firmware runtime](https://github.com/samubraila/stackchan/blob/main/firmware/main/main.cpp): `firmware/main/main.cpp`
- [Built-in apps](https://github.com/samubraila/stackchan/blob/main/firmware/main/apps/apps.h): `firmware/main/apps/apps.h`
- [App launcher](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_launcher): `firmware/main/apps/app_launcher`
- [AI agent](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_ai_agent): `firmware/main/apps/app_ai_agent`
- [Avatar display](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_avatar): `firmware/main/apps/app_avatar`
- [Dance playback](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_dance): `firmware/main/apps/app_dance`
- [App downloads](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_app_center): `firmware/main/apps/app_app_center`
- [Device setup](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_setup): `firmware/main/apps/app_setup`
- [EZData app](https://github.com/samubraila/stackchan/tree/main/firmware/main/apps/app_ezdata): `firmware/main/apps/app_ezdata`
- [Motion and servos](https://github.com/samubraila/stackchan/tree/main/firmware/main/stackchan/motion): `firmware/main/stackchan/motion`
- [Avatar rendering](https://github.com/samubraila/stackchan/tree/main/firmware/main/stackchan/avatar): `firmware/main/stackchan/avatar`
- [Hardware interface](https://github.com/samubraila/stackchan/tree/main/firmware/main/hal): `firmware/main/hal`

### Remote controller

- [Remote runtime](https://github.com/samubraila/stackchan/blob/main/remote/code/main/StackChan-RemoteControl-ESPNow.cpp): `remote/code/main/StackChan-RemoteControl-ESPNow.cpp`
- [Joystick control](https://github.com/samubraila/stackchan/blob/main/remote/code/main/joystick/joystick_handle.c): `remote/code/main/joystick/joystick_handle.c`
- [Remote screens](https://github.com/samubraila/stackchan/tree/main/remote/code/main/ui): `remote/code/main/ui`
- [ESP-NOW link](https://github.com/samubraila/stackchan/tree/main/remote/code/main/esp_now): `remote/code/main/esp_now`

### Mobile apps

- [AR robot view](https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/View/StackChanArView.swift): `app/ios/Runner/View/StackChanArView.swift`
- [iOS native bridge](https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/Utils/NativeBridge.swift): `app/ios/Runner/Utils/NativeBridge.swift`
- [iOS app setup](https://github.com/samubraila/stackchan/blob/main/app/ios/Runner/SceneDelegate.swift): `app/ios/Runner/SceneDelegate.swift`
- [Android app](https://github.com/samubraila/stackchan/blob/main/app/android/app/src/main/kotlin/com/m5stack/stackchan/MainActivity.kt): `app/android/app/src/main/kotlin/com/m5stack/stackchan/MainActivity.kt`

### Cloud services

- [Go service](https://github.com/samubraila/stackchan/tree/main/server): `server`
- [Service APIs](https://github.com/samubraila/stackchan/tree/main/server/api): `server/api`
- [Domain services](https://github.com/samubraila/stackchan/tree/main/server/internal/service): `server/internal/service`

### Desktop tool

- [Desktop interface](https://github.com/samubraila/stackchan/blob/main/desktop/renderer/app.js): `desktop/renderer/app.js`
- [Desktop BLE](https://github.com/samubraila/stackchan/blob/main/desktop/renderer/ble.js): `desktop/renderer/ble.js`

### Other components

- **Robot user**

## Connections

- Robot user → Firmware runtime: uses robot
- Robot user → Remote runtime: uses controller
- Robot user → iOS app setup: uses mobile app
- Firmware runtime → Built-in apps: loads apps
- Built-in apps → App launcher: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → AI agent: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → Avatar display: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → Dance playback: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → App downloads: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → Device setup: registers (evidence: `firmware/main/apps/apps.h`)
- Built-in apps → EZData app: registers (evidence: `firmware/main/apps/apps.h`)
- Remote runtime → Joystick control: starts tasks (evidence: `remote/code/main/StackChan-RemoteControl-ESPNow.cpp`)
- Remote runtime → Remote screens: initializes UI (evidence: `remote/code/main/StackChan-RemoteControl-ESPNow.cpp`)
- Remote runtime → ESP-NOW link: initializes link (evidence: `remote/code/main/StackChan-RemoteControl-ESPNow.cpp`)
- Joystick control → ESP-NOW link: sends commands (evidence: `remote/code/main/joystick/joystick_handle.c`)
- Remote runtime → Robot user: controls robot
- iOS app setup → iOS native bridge: sets up bridge (evidence: `app/ios/Runner/SceneDelegate.swift`)
- iOS app setup → AR robot view: registers view (evidence: `app/ios/Runner/SceneDelegate.swift`)
- AR robot view → Robot user: shows robot view
- iOS app setup → Android app: parallel app
- iOS app setup → Go service: companion integration
- iOS app setup → Firmware runtime: connects to robot
- Go service → Service APIs: exposes endpoints
- Service APIs → Domain services: delegates domain work
- Desktop interface → Desktop BLE: uses BLE
- Desktop BLE → Firmware runtime: controls robot
- Firmware runtime → App downloads: downloads apps
- Firmware runtime → Go service: online updates
- AR robot view → Firmware runtime: remote avatar control
- AR robot view → Firmware runtime: views video
