# agharsallah/esp-labs architecture

> Architecture diagram of the GitHub repository agharsallah/esp-labs, 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/agharsallah/esp-labs
- Repository: https://github.com/agharsallah/esp-labs

## Overview

esp-labs is an ESP32-S3 learning-lab repository: learners run standalone firmware labs across display/input, Wi-Fi, RFID/NFC, Bluetooth LE and sound, reusing shared kit libraries. Some labs extend into companion phone or desktop workflows, including door-card management, a friends game, BLE control, Wi-Fi control and AI-assisted weather. The graph preserves these branches and central shared layers; source excerpts are selective, so connections among unsampled subsystems are shown only where the README documents them.

Main entry points: [`labs/ble-lab-b7/src/main.cpp`](https://github.com/agharsallah/esp-labs/blob/main/labs/ble-lab-b7/src/main.cpp) (BLE labs), [`labs/wifi-lab-w2/src/main.cpp`](https://github.com/agharsallah/esp-labs/blob/main/labs/wifi-lab-w2/src/main.cpp) (Wi-Fi labs), [`labs/rfid-lab-r7/src/main.cpp`](https://github.com/agharsallah/esp-labs/blob/main/labs/rfid-lab-r7/src/main.cpp) (RFID labs), [`labs/sound-lab-s8/src/main.cpp`](https://github.com/agharsallah/esp-labs/blob/main/labs/sound-lab-s8/src/main.cpp) (Sound labs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracks["Firmware tracks"]
  node_display["Display labs<br/>[main.cpp]"]
  node_wifi["Wi-Fi labs<br/>[main.cpp]"]
  node_rfid["RFID labs<br/>[main.cpp]"]
  node_ble["BLE labs<br/>[main.cpp]"]
  node_sound["Sound labs<br/>[main.cpp]"]
  node_weather_ai["Weather and AI<br/>[main.cpp]"]
end

subgraph group_kits["Shared firmware kits"]
  node_wifi_kit["Wi-Fi kit"]
  node_ble_shell["BLE shell<br/>[ble_lab.h]"]
  node_ble_link["BLE links<br/>[ble_link.h]"]
  node_ble_server["BLE peripheral<br/>[server_link.h]"]
  node_ble_views["BLE views<br/>[bench_views.h]"]
  node_sound_shell["Sound shell<br/>[sound_lab.h]"]
  node_sound_dsp["Sound analysis<br/>[onsets.h]"]
end

subgraph group_apps["Companion apps"]
  node_door_app["Door manager<br/>[App.tsx]"]
  node_friends_app["Friends game<br/>[App.tsx]"]
  node_ble_app["BLE controller<br/>[App.tsx]"]
  node_dashboard["Wi-Fi dashboard<br/>[App.tsx]"]
end

subgraph group_services["Network services"]
  node_gateway["AI gateway"]
end

node_learner(("Learner"))

node_learner -->|"runs labs"| node_display
node_learner -->|"runs labs"| node_wifi
node_learner -->|"runs labs"| node_rfid
node_learner -->|"runs labs"| node_ble
node_learner -->|"runs labs"| node_sound
node_wifi -->|"uses kit"| node_wifi_kit
node_rfid -->|"uses kit"| node_wifi_kit
node_ble -->|"uses shell"| node_ble_shell
node_ble -->|"uses peripheral"| node_ble_server
node_ble -->|"uses views"| node_ble_views
node_ble_shell -->|"reads link state"| node_ble_link
node_ble_server -->|"updates state"| node_ble_link
node_sound -->|"uses shell"| node_sound_shell
node_sound -->|"uses onset analysis"| node_sound_dsp
node_rfid -->|"companion app"| node_door_app
node_rfid -->|"companion app"| node_friends_app
node_ble -->|"companion app"| node_ble_app
node_wifi -->|"phone control"| node_dashboard
node_wifi -->|"extends Wi-Fi"| node_weather_ai
node_weather_ai -->|"AI requests"| node_gateway

click node_display "https://github.com/agharsallah/esp-labs/blob/main/labs/03b-showcase/src/main.cpp"
click node_wifi "https://github.com/agharsallah/esp-labs/blob/main/labs/wifi-lab-w2/src/main.cpp"
click node_rfid "https://github.com/agharsallah/esp-labs/blob/main/labs/rfid-lab-r7/src/main.cpp"
click node_ble "https://github.com/agharsallah/esp-labs/blob/main/labs/ble-lab-b7/src/main.cpp"
click node_sound "https://github.com/agharsallah/esp-labs/blob/main/labs/sound-lab-s8/src/main.cpp"
click node_wifi_kit "https://github.com/agharsallah/esp-labs/tree/main/kit/lib/wifi-kit/src"
click node_ble_shell "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/ble_lab.h"
click node_ble_link "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/ble_link.h"
click node_ble_server "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/server_link.h"
click node_ble_views "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/bench_views.h"
click node_sound_shell "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/sound-kit/src/sound_lab.h"
click node_sound_dsp "https://github.com/agharsallah/esp-labs/blob/main/kit/lib/sound-kit/src/onsets.h"
click node_door_app "https://github.com/agharsallah/esp-labs/blob/main/apps/door-app/src/App.tsx"
click node_friends_app "https://github.com/agharsallah/esp-labs/blob/main/apps/friends-app/src/App.tsx"
click node_ble_app "https://github.com/agharsallah/esp-labs/blob/main/apps/ble-app/src/App.tsx"
click node_dashboard "https://github.com/agharsallah/esp-labs/blob/main/apps/dashboard/web/src/App.tsx"
click node_gateway "https://github.com/agharsallah/esp-labs/tree/main/apps/ai-gateway"
click node_weather_ai "https://github.com/agharsallah/esp-labs/blob/main/labs/wifi-lab-w3/src/main.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_display,node_wifi,node_rfid,node_ble,node_sound,node_weather_ai toneBlue
class node_wifi_kit,node_ble_shell,node_ble_link,node_ble_server,node_ble_views,node_sound_shell,node_sound_dsp toneAmber
class node_door_app,node_friends_app,node_ble_app,node_dashboard toneMint
class node_gateway toneRose
class node_learner toneIndigo
```

## Components

### Firmware tracks

- [Display labs](https://github.com/agharsallah/esp-labs/blob/main/labs/03b-showcase/src/main.cpp): `labs/03b-showcase/src/main.cpp`
- [Wi-Fi labs](https://github.com/agharsallah/esp-labs/blob/main/labs/wifi-lab-w2/src/main.cpp): `labs/wifi-lab-w2/src/main.cpp`
- [RFID labs](https://github.com/agharsallah/esp-labs/blob/main/labs/rfid-lab-r7/src/main.cpp): `labs/rfid-lab-r7/src/main.cpp`
- [BLE labs](https://github.com/agharsallah/esp-labs/blob/main/labs/ble-lab-b7/src/main.cpp): `labs/ble-lab-b7/src/main.cpp`
- [Sound labs](https://github.com/agharsallah/esp-labs/blob/main/labs/sound-lab-s8/src/main.cpp): `labs/sound-lab-s8/src/main.cpp`
- [Weather and AI](https://github.com/agharsallah/esp-labs/blob/main/labs/wifi-lab-w3/src/main.cpp): `labs/wifi-lab-w3/src/main.cpp`

### Shared firmware kits

- [Wi-Fi kit](https://github.com/agharsallah/esp-labs/tree/main/kit/lib/wifi-kit/src): `kit/lib/wifi-kit/src`
- [BLE shell](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/ble_lab.h): `kit/lib/ble-kit/src/ble_lab.h`
- [BLE links](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/ble_link.h): `kit/lib/ble-kit/src/ble_link.h`
- [BLE peripheral](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/server_link.h): `kit/lib/ble-kit/src/server_link.h`
- [BLE views](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/ble-kit/src/bench_views.h): `kit/lib/ble-kit/src/bench_views.h`
- [Sound shell](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/sound-kit/src/sound_lab.h): `kit/lib/sound-kit/src/sound_lab.h`
- [Sound analysis](https://github.com/agharsallah/esp-labs/blob/main/kit/lib/sound-kit/src/onsets.h): `kit/lib/sound-kit/src/onsets.h`

### Companion apps

- [Door manager](https://github.com/agharsallah/esp-labs/blob/main/apps/door-app/src/App.tsx): `apps/door-app/src/App.tsx`
- [Friends game](https://github.com/agharsallah/esp-labs/blob/main/apps/friends-app/src/App.tsx): `apps/friends-app/src/App.tsx`
- [BLE controller](https://github.com/agharsallah/esp-labs/blob/main/apps/ble-app/src/App.tsx): `apps/ble-app/src/App.tsx`
- [Wi-Fi dashboard](https://github.com/agharsallah/esp-labs/blob/main/apps/dashboard/web/src/App.tsx): `apps/dashboard/web/src/App.tsx`

### Network services

- [AI gateway](https://github.com/agharsallah/esp-labs/tree/main/apps/ai-gateway): `apps/ai-gateway`

### Other components

- **Learner**

## Connections

- Learner → Display labs: runs labs (evidence: `README.md`)
- Learner → Wi-Fi labs: runs labs (evidence: `README.md`)
- Learner → RFID labs: runs labs (evidence: `README.md`)
- Learner → BLE labs: runs labs (evidence: `README.md`)
- Learner → Sound labs: runs labs (evidence: `README.md`)
- Wi-Fi labs → Wi-Fi kit: uses kit (evidence: `README.md`)
- RFID labs → Wi-Fi kit: uses kit (evidence: `README.md`)
- BLE labs → BLE shell: uses shell (evidence: `labs/ble-lab-b7/src/main.cpp`)
- BLE labs → BLE peripheral: uses peripheral (evidence: `labs/ble-lab-b7/src/main.cpp`)
- BLE labs → BLE views: uses views
- BLE shell → BLE links: reads link state (evidence: `kit/lib/ble-kit/src/ble_lab.h`)
- BLE peripheral → BLE links: updates state (evidence: `kit/lib/ble-kit/src/server_link.h`)
- Sound labs → Sound shell: uses shell (evidence: `labs/sound-lab-s8/src/main.cpp`)
- Sound labs → Sound analysis: uses onset analysis
- RFID labs → Door manager: companion app (evidence: `labs/rfid-lab-r7/src/main.cpp`)
- RFID labs → Friends game: companion app
- BLE labs → BLE controller: companion app (evidence: `README.md`)
- Wi-Fi labs → Wi-Fi dashboard: phone control (evidence: `labs/wifi-lab-w2/src/main.cpp`)
- Wi-Fi labs → Weather and AI: extends Wi-Fi (evidence: `README.md`)
- Weather and AI → AI gateway: AI requests (evidence: `labs/wifi-lab-w3/src/main.cpp`)