# seymenkonuk/esp32-handheld-application-platform architecture

> Architecture diagram of the GitHub repository seymenkonuk/esp32-handheld-application-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seymenkonuk/esp32-handheld-application-platform
- Repository: https://github.com/seymenkonuk/esp32-handheld-application-platform

## Overview

ROWS is an ESP32 application platform with companion OTA and MQTT-auth backend services and asset converters. The principal workflow is device startup, input-driven application execution and rendering, with optional network configuration, MQTT communication, and OTA checks/downloads. The graph combines sampled call sites and SOURCE INDEX references with documented capabilities; unsampled subsystems and external service wiring are linked only where the README supports them.

Main entry points: [`firmware/src/main.cpp`](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/main.cpp) (Firmware Loop), [`firmware/src/app/system/netmanager/NetManager.cpp`](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/netmanager/NetManager.cpp) (Network Settings), [`firmware/src/network/OTAService.cpp`](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/OTAService.cpp) (OTA Updater), [`firmware/src/core/system/AppManager.cpp`](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/AppManager.cpp) (App Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware Runtime"]
  node_main["Firmware Loop<br/>[main.cpp]"]
  node_apps_stack["App Registry<br/>[AppStack.cpp]"]
  node_app_manager["App Lifecycle<br/>[AppManager.cpp]"]
  node_input["Input Manager<br/>[InputManager.cpp]"]
  node_screen["Screen Driver<br/>[Screen.cpp]"]
  node_renderer["Graphics Renderer<br/>[Renderer.cpp]"]
  node_filesystem["LittleFS Access<br/>[Filesystem.cpp]"]
  node_network["Wi-Fi and AP<br/>[Network.cpp]"]
  node_device_server["Device Web Server<br/>[DeviceServer.cpp]"]
  node_api_client["HTTP API Client<br/>[APIClient.cpp]"]
  node_certificates["Device Certificates<br/>[Certificate.cpp]"]
  node_ota["OTA Updater<br/>[OTAService.cpp]"]
  node_mqtt["MQTT Client<br/>[MQTTClient.cpp]"]
  node_audio["Audio Playback<br/>[MusicPlayer.cpp]"]
end

subgraph group_apps["Device Applications"]
  node_net_manager["Network Settings<br/>[NetManager.cpp]"]
  node_update_center["Update Center<br/>[UpdateCenter.cpp]"]
  node_system_apps["System Apps<br/>[Launcher.cpp]"]
  node_user_apps["User Apps<br/>[App1.cpp]"]
end

subgraph group_backend["Backend Services"]
  node_ota_service["Firmware Update API"]
  node_firmware_domain["Firmware Metadata"]
  node_firmware_store[("Firmware Repository")]
  node_mqtt_auth["MQTT Auth API<br/>[AuthController.php]"]
end

subgraph group_assets["Asset Converters"]
  node_image_converter["Image Converter<br/>[writer.c]"]
  node_image_writer["Image Writer<br/>[writer.c]"]
  node_melody_converter["Melody Converter<br/>[main.c]"]
  node_melody_writer["Melody Writer<br/>[writer.c]"]
  node_note_definitions["Note Definitions<br/>[pitches.h]"]
end

node_user(("Device User"))
node_mqtt_broker["MQTT Broker"]

node_user -->|"uses device"| node_main
node_main -->|"updates input"| node_input
node_main -->|"runs lifecycle"| node_app_manager
node_main -->|"initializes"| node_filesystem
node_main -->|"starts networking"| node_network
node_main -->|"starts and loops"| node_device_server
node_main -->|"initializes"| node_api_client
node_main -->|"initializes"| node_certificates
node_main -->|"initializes"| node_ota
node_main -->|"initializes playback"| node_audio
node_main -->|"selects initial app"| node_apps_stack
node_app_manager -.->|"runs current app"| node_system_apps
node_app_manager -.->|"runs current app"| node_user_apps
node_net_manager -->|"reads controls"| node_input
node_net_manager -->|"switches app"| node_app_manager
node_net_manager -->|"toggles network"| node_network
node_net_manager -->|"toggles server"| node_device_server
node_net_manager -->|"renders settings"| node_renderer
node_renderer -->|"draws on"| node_screen
node_ota -->|"requests updates"| node_api_client
node_ota -->|"writes firmware"| node_filesystem
node_api_client -->|"uses client TLS"| node_certificates
node_ota -->|"checks and downloads"| node_ota_service
node_ota_service -->|"gets version data"| node_firmware_domain
node_firmware_domain -->|"queries metadata"| node_firmware_store
node_mqtt -->|"communicates"| node_mqtt_broker
node_mqtt_broker -->|"authenticates via HTTP"| node_mqtt_auth
node_image_converter -.->|"writes converted image"| node_image_writer
node_melody_converter -.->|"writes converted melody"| node_melody_writer
node_melody_converter -->|"uses note data"| node_note_definitions
node_image_converter -->|"prepares device assets"| node_user
node_melody_converter -->|"prepares device assets"| node_user

click node_main "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/main.cpp"
click node_apps_stack "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/AppStack.cpp"
click node_app_manager "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/AppManager.cpp"
click node_input "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/InputManager.cpp"
click node_screen "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/device/Screen.cpp"
click node_renderer "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/graphics/Renderer.cpp"
click node_filesystem "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/Filesystem.cpp"
click node_network "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/Network.cpp"
click node_device_server "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/DeviceServer.cpp"
click node_api_client "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/APIClient.cpp"
click node_certificates "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/Certificate.cpp"
click node_ota "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/OTAService.cpp"
click node_mqtt "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/MQTTClient.cpp"
click node_audio "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/audio/MusicPlayer.cpp"
click node_net_manager "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/netmanager/NetManager.cpp"
click node_update_center "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/updatecenter/UpdateCenter.cpp"
click node_system_apps "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/launcher/Launcher.cpp"
click node_user_apps "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/user/app1/App1.cpp"
click node_ota_service "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Http/Controllers/UpdateController.php"
click node_firmware_domain "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Domain/Services/FirmwareService.php"
click node_firmware_store "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Domain/Repositories/FirmwareRepository.php"
click node_mqtt_auth "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/mqtt-auth-service/app/Http/Controllers/AuthController.php"
click node_image_converter "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/image-converter/src/writer.c"
click node_image_writer "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/image-converter/src/writer.c"
click node_melody_converter "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/src/main.c"
click node_melody_writer "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/src/writer.c"
click node_note_definitions "https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/include/pitches.h"

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_main,node_apps_stack,node_app_manager,node_input,node_screen,node_renderer,node_filesystem,node_network,node_device_server,node_api_client,node_certificates,node_ota,node_mqtt,node_audio,node_user toneBlue
class node_net_manager,node_update_center,node_system_apps,node_user_apps toneAmber
class node_ota_service,node_firmware_domain,node_firmware_store,node_mqtt_auth toneMint
class node_image_converter,node_image_writer,node_melody_converter,node_melody_writer,node_note_definitions toneRose
class node_mqtt_broker toneIndigo
```

## Components

### Firmware Runtime

- [Firmware Loop](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [App Registry](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/AppStack.cpp): `firmware/src/app/AppStack.cpp`
- [App Lifecycle](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/AppManager.cpp): `firmware/src/core/system/AppManager.cpp`
- [Input Manager](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/InputManager.cpp): `firmware/src/core/system/InputManager.cpp`
- [Screen Driver](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/device/Screen.cpp): `firmware/src/device/Screen.cpp`
- [Graphics Renderer](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/graphics/Renderer.cpp): `firmware/src/graphics/Renderer.cpp`
- [LittleFS Access](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/core/system/Filesystem.cpp): `firmware/src/core/system/Filesystem.cpp`
- [Wi-Fi and AP](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/Network.cpp): `firmware/src/network/Network.cpp`
- [Device Web Server](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/DeviceServer.cpp): `firmware/src/network/DeviceServer.cpp`
- [HTTP API Client](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/APIClient.cpp): `firmware/src/network/APIClient.cpp`
- [Device Certificates](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/Certificate.cpp): `firmware/src/network/Certificate.cpp`
- [OTA Updater](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/OTAService.cpp): `firmware/src/network/OTAService.cpp`
- [MQTT Client](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/network/MQTTClient.cpp): `firmware/src/network/MQTTClient.cpp`
- [Audio Playback](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/audio/MusicPlayer.cpp): `firmware/src/audio/MusicPlayer.cpp`

### Device Applications

- [Network Settings](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/netmanager/NetManager.cpp): `firmware/src/app/system/netmanager/NetManager.cpp`
- [Update Center](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/updatecenter/UpdateCenter.cpp): `firmware/src/app/system/updatecenter/UpdateCenter.cpp`
- [System Apps](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/system/launcher/Launcher.cpp): `firmware/src/app/system/launcher/Launcher.cpp`
- [User Apps](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/firmware/src/app/user/app1/App1.cpp): `firmware/src/app/user/app1/App1.cpp`

### Backend Services

- [Firmware Update API](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Http/Controllers/UpdateController.php): `backends/services/firmware-update-service/app/Http/Controllers/UpdateController.php`
- [Firmware Metadata](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Domain/Services/FirmwareService.php): `backends/services/firmware-update-service/app/Domain/Services/FirmwareService.php`
- [Firmware Repository](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/firmware-update-service/app/Domain/Repositories/FirmwareRepository.php): `backends/services/firmware-update-service/app/Domain/Repositories/FirmwareRepository.php`
- [MQTT Auth API](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/backends/services/mqtt-auth-service/app/Http/Controllers/AuthController.php): `backends/services/mqtt-auth-service/app/Http/Controllers/AuthController.php`

### Asset Converters

- [Image Converter](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/image-converter/src/writer.c): `tools/image-converter/src/writer.c`
- [Image Writer](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/image-converter/src/writer.c): `tools/image-converter/src/writer.c`
- [Melody Converter](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/src/main.c): `tools/melody-converter/src/main.c`
- [Melody Writer](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/src/writer.c): `tools/melody-converter/src/writer.c`
- [Note Definitions](https://github.com/seymenkonuk/esp32-handheld-application-platform/blob/main/tools/melody-converter/include/pitches.h): `tools/melody-converter/include/pitches.h`

### Other components

- **Device User**
- **MQTT Broker**

## Connections

- Device User → Firmware Loop: uses device (evidence: `README.md`)
- Firmware Loop → Input Manager: updates input (evidence: `firmware/src/main.cpp`)
- Firmware Loop → App Lifecycle: runs lifecycle (evidence: `firmware/src/main.cpp`)
- Firmware Loop → LittleFS Access: initializes (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Wi-Fi and AP: starts networking (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Device Web Server: starts and loops (evidence: `firmware/src/main.cpp`)
- Firmware Loop → HTTP API Client: initializes (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Device Certificates: initializes (evidence: `firmware/src/main.cpp`)
- Firmware Loop → OTA Updater: initializes (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Audio Playback: initializes playback (evidence: `firmware/src/main.cpp`)
- Firmware Loop → App Registry: selects initial app (evidence: `firmware/src/main.cpp`)
- App Lifecycle → System Apps: runs current app
- App Lifecycle → User Apps: runs current app
- Network Settings → Input Manager: reads controls (evidence: `firmware/src/app/system/netmanager/NetManager.cpp`)
- Network Settings → App Lifecycle: switches app (evidence: `firmware/src/app/system/netmanager/NetManager.cpp`)
- Network Settings → Wi-Fi and AP: toggles network (evidence: `firmware/src/app/system/netmanager/NetManager.cpp`)
- Network Settings → Device Web Server: toggles server (evidence: `firmware/src/app/system/netmanager/NetManager.cpp`)
- Network Settings → Graphics Renderer: renders settings (evidence: `firmware/src/app/system/netmanager/NetManager.cpp`)
- Graphics Renderer → Screen Driver: draws on
- OTA Updater → HTTP API Client: requests updates (evidence: `firmware/src/network/OTAService.cpp`)
- OTA Updater → LittleFS Access: writes firmware (evidence: `firmware/src/network/OTAService.cpp`)
- HTTP API Client → Device Certificates: uses client TLS (evidence: `firmware/src/network/APIClient.cpp`)
- OTA Updater → Firmware Update API: checks and downloads (evidence: `README.md`)
- Firmware Update API → Firmware Metadata: gets version data (evidence: `backends/services/firmware-update-service/app/Http/Controllers/UpdateController.php`)
- Firmware Metadata → Firmware Repository: queries metadata (evidence: `backends/services/firmware-update-service/app/Domain/Services/FirmwareService.php`)
- MQTT Client → MQTT Broker: communicates (evidence: `README.md`)
- MQTT Broker → MQTT Auth API: authenticates via HTTP (evidence: `README.md`)
- Image Converter → Image Writer: writes converted image
- Melody Converter → Melody Writer: writes converted melody
- Melody Converter → Note Definitions: uses note data
- Image Converter → Device User: prepares device assets (evidence: `README.md`)
- Melody Converter → Device User: prepares device assets (evidence: `README.md`)