# the-spire/esp32-smart-water-gun architecture

> Architecture diagram of the GitHub repository the-spire/esp32-smart-water-gun, 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/the-spire/esp32-smart-water-gun
- Repository: https://github.com/the-spire/esp32-smart-water-gun

## Overview

This is ESP32-C3 firmware for a configurable sound-and-light water-gun prop. The principal workflow is encoder/trigger input into the state machine, which handles firing, ammunition and reload behavior, updates the display, and controls the pump, laser, indicator, sound, and LEDs. Users navigate separate settings screens to adjust behavior and appearance; settings persist through Preferences. The README documents additional screen capabilities, but excerpts do not show every screen’s wiring, so uncertain links are omitted.

Main entry points: [`src/ui/UIManager.cpp`](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/UIManager.cpp) (UI manager), [`src/logic/WaterGunLogic.cpp`](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/logic/WaterGunLogic.cpp) (Water-gun logic), [`src/main.cpp`](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/main.cpp) (Firmware loop), [`src/hardware/OutputManager.cpp`](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/OutputManager.cpp) (Output manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control flow"]
  node_firmware["Firmware loop<br/>[main.cpp]"]
  node_logic["Water-gun logic<br/>[WaterGunLogic.cpp]"]
end

subgraph group_interface["Display and settings UI"]
  node_ui["UI manager<br/>[UIManager.cpp]"]
  node_main_screen["Main screen<br/>[ScreenMain.cpp]"]
  node_func_screen["Function settings"]
  node_bullet_screen["Bullet settings"]
  node_sound_screen["Sound settings"]
  node_light_screen["Light settings"]
  node_theme_screen["Theme settings"]
  node_sysinfo_screen["System information<br/>[ScreenSysInfo.cpp]"]
end

subgraph group_hardware["Device hardware"]
  node_input["Trigger and encoder<br/>[InputManager.cpp]"]
  node_outputs["Output manager<br/>[OutputManager.cpp]"]
  node_leds["LED strip<br/>[LedStrip.cpp]"]
  node_voice["Voice module<br/>[VoiceModule.cpp]"]
end

subgraph group_persistence["Settings persistence"]
  node_settings["Settings manager"]
  node_preferences[("Preferences store")]
end

node_user(("Prop user"))
node_prop_io["Prop actuators"]
node_speaker["Voice hardware"]

node_user -->|"operates controls"| node_input
node_firmware -->|"updates state"| node_logic
node_logic -->|"reads events"| node_input
node_firmware -->|"updates outputs"| node_outputs
node_firmware -->|"updates LEDs"| node_leds
node_firmware -->|"updates display"| node_ui
node_logic -->|"dispatches UI"| node_ui
node_logic -->|"controls actuators"| node_outputs
node_logic -->|"plays sounds"| node_voice
node_logic -->|"controls lighting"| node_leds
node_logic -->|"reads and saves"| node_settings
node_ui -->|"creates screen"| node_main_screen
node_ui -->|"dispatches actions"| node_func_screen
node_ui -->|"dispatches actions"| node_bullet_screen
node_ui -->|"dispatches actions"| node_sound_screen
node_ui -->|"dispatches actions"| node_light_screen
node_ui -->|"dispatches actions"| node_theme_screen
node_ui -->|"dispatches actions"| node_sysinfo_screen
node_firmware -->|"loads settings"| node_settings
node_settings -->|"reads and writes"| node_preferences
node_outputs -->|"drives actuators"| node_prop_io
node_voice -->|"plays audio"| node_speaker

click node_firmware "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/main.cpp"
click node_logic "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/logic/WaterGunLogic.cpp"
click node_input "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/InputManager.cpp"
click node_ui "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/UIManager.cpp"
click node_main_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenMain.cpp"
click node_func_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenFuncSettings.cpp"
click node_bullet_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenBulletSettings.cpp"
click node_sound_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenSoundSettings.cpp"
click node_light_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenLightSettings.cpp"
click node_theme_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenThemeSettings.cpp"
click node_sysinfo_screen "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenSysInfo.cpp"
click node_outputs "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/OutputManager.cpp"
click node_leds "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/LedStrip.cpp"
click node_voice "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/VoiceModule.cpp"
click node_settings "https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/storage/SettingsManager.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_firmware,node_logic,node_user toneBlue
class node_ui,node_main_screen,node_func_screen,node_bullet_screen,node_sound_screen,node_light_screen,node_theme_screen,node_sysinfo_screen toneAmber
class node_input,node_outputs,node_leds,node_voice toneMint
class node_settings,node_preferences toneRose
class node_prop_io,node_speaker toneIndigo
```

## Components

### Control flow

- [Firmware loop](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/main.cpp): `src/main.cpp`
- [Water-gun logic](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/logic/WaterGunLogic.cpp): `src/logic/WaterGunLogic.cpp`

### Display and settings UI

- [UI manager](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/UIManager.cpp): `src/ui/UIManager.cpp`
- [Main screen](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenMain.cpp): `src/ui/screens/ScreenMain.cpp`
- [Function settings](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenFuncSettings.cpp): `src/ui/screens/ScreenFuncSettings.cpp`
- [Bullet settings](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenBulletSettings.cpp): `src/ui/screens/ScreenBulletSettings.cpp`
- [Sound settings](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenSoundSettings.cpp): `src/ui/screens/ScreenSoundSettings.cpp`
- [Light settings](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenLightSettings.cpp): `src/ui/screens/ScreenLightSettings.cpp`
- [Theme settings](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenThemeSettings.cpp): `src/ui/screens/ScreenThemeSettings.cpp`
- [System information](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/ui/screens/ScreenSysInfo.cpp): `src/ui/screens/ScreenSysInfo.cpp`

### Device hardware

- [Trigger and encoder](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/InputManager.cpp): `src/hardware/InputManager.cpp`
- [Output manager](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/OutputManager.cpp): `src/hardware/OutputManager.cpp`
- [LED strip](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/LedStrip.cpp): `src/hardware/LedStrip.cpp`
- [Voice module](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/hardware/VoiceModule.cpp): `src/hardware/VoiceModule.cpp`

### Settings persistence

- [Settings manager](https://github.com/the-spire/esp32-smart-water-gun/blob/main/src/storage/SettingsManager.cpp): `src/storage/SettingsManager.cpp`
- **Preferences store**

### Other components

- **Prop user**
- **Prop actuators**
- **Voice hardware**

## Connections

- Prop user → Trigger and encoder: operates controls
- Firmware loop → Water-gun logic: updates state
- Water-gun logic → Trigger and encoder: reads events
- Firmware loop → Output manager: updates outputs
- Firmware loop → LED strip: updates LEDs
- Firmware loop → UI manager: updates display
- Water-gun logic → UI manager: dispatches UI
- Water-gun logic → Output manager: controls actuators
- Water-gun logic → Voice module: plays sounds
- Water-gun logic → LED strip: controls lighting
- Water-gun logic → Settings manager: reads and saves
- UI manager → Main screen: creates screen
- UI manager → Function settings: dispatches actions
- UI manager → Bullet settings: dispatches actions
- UI manager → Sound settings: dispatches actions
- UI manager → Light settings: dispatches actions
- UI manager → Theme settings: dispatches actions
- UI manager → System information: dispatches actions
- Firmware loop → Settings manager: loads settings
- Settings manager → Preferences store: reads and writes
- Output manager → Prop actuators: drives actuators
- Voice module → Voice hardware: plays audio