# sstrobl/streamdeck4u architecture

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

- Interactive diagram: https://gitdiagram.com/sstrobl/streamdeck4u
- Repository: https://github.com/sstrobl/streamdeck4u

## Overview

StreamDeck4U is ESP32-S3 firmware for a configurable USB macro pad. Buttons are debounced and mapped to HID key combinations; a USB mass-storage interface exposes a FAT configuration file, which is reloaded when the host ejects the drive. The README documents the major runtime capabilities, while the sampled source is partial and places the application logic in one file, so nodes represent responsibilities within that file rather than separate modules.

Main entry points: [`vscode/main/main.c`](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c) (Config Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input_hid["Input and HID"]
  node_buttons(("GPIO Buttons"))
  node_scan_debounce["Scan and Debounce<br/>[main.c]"]
  node_gpio_setup["GPIO Setup<br/>[main.c]"]
  node_hid_reports["HID Reports<br/>[main.c]"]
end

subgraph group_keymap["Keymap Configuration"]
  node_active_map["Active Key Map<br/>[main.c]"]
  node_keymap_file["keymap.txt<br/>[main.c]"]
  node_config_loader["Config Loader<br/>[main.c]"]
  node_combo_parser["Combo Parser<br/>[main.c]"]
  node_keycode_lookup["Keycode Lookup<br/>[main.c]"]
  node_fallback_map["Fallback Map<br/>[main.c]"]
end

subgraph group_usb_storage["USB and Storage"]
  node_usb_composite["USB Composite Device<br/>[main.c]"]
  node_msc_storage[("MSC FAT Storage<br/>[main.c]")]
end

node_usb_host(("USB Host"))

node_buttons -->|"provide levels"| node_scan_debounce
node_scan_debounce -->|"reads mapping"| node_active_map
node_scan_debounce -->|"sends reports"| node_hid_reports
node_hid_reports -->|"delivers keys"| node_usb_host
node_active_map -->|"configures pins"| node_gpio_setup
node_fallback_map -->|"provides defaults"| node_active_map
node_usb_composite -->|"exposes interface"| node_hid_reports
node_usb_composite -->|"exposes interface"| node_msc_storage
node_usb_host -->|"accesses drive"| node_msc_storage
node_msc_storage -->|"stores config"| node_keymap_file
node_config_loader -->|"reads config"| node_keymap_file
node_config_loader -->|"parses bindings"| node_combo_parser
node_combo_parser -->|"resolves keys"| node_keycode_lookup
node_config_loader -->|"applies mapping"| node_active_map
node_msc_storage -->|"reloads on eject"| node_config_loader
node_config_loader -->|"returns drive"| node_msc_storage

click node_scan_debounce "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_active_map "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_gpio_setup "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_hid_reports "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_usb_composite "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_msc_storage "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_keymap_file "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_config_loader "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_combo_parser "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_keycode_lookup "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"
click node_fallback_map "https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c"

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_buttons,node_scan_debounce,node_gpio_setup,node_hid_reports toneBlue
class node_active_map,node_keymap_file,node_config_loader,node_combo_parser,node_keycode_lookup,node_fallback_map toneAmber
class node_usb_composite,node_msc_storage toneMint
class node_usb_host toneIndigo
```

## Components

### Input and HID

- **GPIO Buttons**
- [Scan and Debounce](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [GPIO Setup](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [HID Reports](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`

### Keymap Configuration

- [Active Key Map](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [keymap.txt](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [Config Loader](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [Combo Parser](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [Keycode Lookup](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [Fallback Map](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`

### USB and Storage

- [USB Composite Device](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`
- [MSC FAT Storage](https://github.com/sstrobl/streamdeck4u/blob/main/vscode/main/main.c): `vscode/main/main.c`

### Other components

- **USB Host**

## Connections

- GPIO Buttons → Scan and Debounce: provide levels (evidence: `README.md`)
- Scan and Debounce → Active Key Map: reads mapping (evidence: `README.md`)
- Scan and Debounce → HID Reports: sends reports (evidence: `README.md`)
- HID Reports → USB Host: delivers keys (evidence: `README.md`)
- Active Key Map → GPIO Setup: configures pins (evidence: `README.md`)
- Fallback Map → Active Key Map: provides defaults (evidence: `README.md`)
- USB Composite Device → HID Reports: exposes interface (evidence: `README.md`)
- USB Composite Device → MSC FAT Storage: exposes interface (evidence: `README.md`)
- USB Host → MSC FAT Storage: accesses drive (evidence: `README.md`)
- MSC FAT Storage → keymap.txt: stores config (evidence: `README.md`)
- Config Loader → keymap.txt: reads config (evidence: `vscode/main/main.c`)
- Config Loader → Combo Parser: parses bindings (evidence: `README.md`)
- Combo Parser → Keycode Lookup: resolves keys (evidence: `README.md`)
- Config Loader → Active Key Map: applies mapping (evidence: `vscode/main/main.c`)
- MSC FAT Storage → Config Loader: reloads on eject (evidence: `vscode/main/main.c`)
- Config Loader → MSC FAT Storage: returns drive (evidence: `vscode/main/main.c`)