# mr-pian/grub-friendly-starting-up-system architecture

> Architecture diagram of the GitHub repository mr-pian/grub-friendly-starting-up-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-pian/grub-friendly-starting-up-system
- Repository: https://github.com/mr-pian/grub-friendly-starting-up-system

## Overview

This is a remote-start gateway system: an ESP32-S3 gateway presents a screen and network control, communicates with an EFR32BG22 BLE key, and can act as a USB keyboard during boot to help select a GRUB entry. The key advertises PC state and battery information and handles physical-button events; the Web service provides LAN browser control. The main firmware excerpts show Wi-Fi provisioning, USB HID, and HTTP activity, but not the full UI or Web request flow. Some subsystem links are therefore documented or left unverified.

Main entry points: [`Firmware/GRUB_Key/app.c`](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/app.c) (Key Application), [`Firmware/ESP32_S3_Mesh/main/main.c`](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c) (Gateway Runtime), [`Firmware/ESP32_S3_Mesh/components/ble_client.c`](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/components/ble_client.c) (BLE Client), [`Web/server.js`](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Web/server.js) (Web Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["ESP32 Gateway"]
  node_gateway_main["Gateway Runtime<br/>[main.c]"]
  node_gateway_net["Wi-Fi Network<br/>[main.c]"]
  node_gateway_ui["Screen UI<br/>[LVGL_UI.c]"]
  node_gateway_ble["BLE Client<br/>[ble_client.c]"]
  node_gateway_usb["USB HID<br/>[main.c]"]
  node_mesh["Mesh Networking"]
end

subgraph group_key["BLE Key"]
  node_key_app["Key Application<br/>[app.c]"]
  node_key_ble["Bluetooth Stack<br/>[sl_bluetooth.c]"]
  node_key_gatt[("GATT Database<br/>[gatt_db.c]")]
  node_key_init["Device Runtime<br/>[main.c]"]
  node_key_power["Power Management"]
end

subgraph group_web["Web Control"]
  node_web_server["Web Server<br/>[server.js]"]
end

subgraph group_boot["PC Startup"]
  node_pc(("Target PC"))
  node_grub["GRUB Boot Menu"]
end

node_user(("User"))
node_browser(("Browser"))

node_user -.->|"interacts with"| node_gateway_ui
node_user -->|"controls through"| node_browser
node_browser -.->|"requests control"| node_web_server
node_web_server -.->|"controls remotely"| node_gateway_main
node_gateway_main -->|"initializes Wi-Fi"| node_gateway_net
node_gateway_main -->|"installs HID"| node_gateway_usb
node_gateway_usb -->|"sends keystrokes"| node_pc
node_pc -.->|"boots into"| node_grub
node_gateway_main -.->|"starts display"| node_gateway_ui
node_gateway_main -.->|"uses BLE client"| node_gateway_ble
node_gateway_ble -->|"scans and connects"| node_key_app
node_key_app -.->|"updates advertising"| node_key_ble
node_key_app -.->|"uses GATT data"| node_key_gatt
node_key_init -->|"initializes application"| node_key_app
node_key_app -->|"advertises state"| node_gateway_ble
node_gateway_ble -->|"writes commands"| node_key_app
node_key_app -.->|"coordinates sleep"| node_key_power
node_gateway_main -.->|"supports mesh"| node_mesh

click node_gateway_main "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c"
click node_gateway_net "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c"
click node_gateway_ui "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/components/LVGL_UI.c"
click node_gateway_ble "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/components/ble_client.c"
click node_gateway_usb "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c"
click node_mesh "https://github.com/mr-pian/grub-friendly-starting-up-system/tree/main/Firmware/ESP32_S3_Mesh"
click node_key_app "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/app.c"
click node_key_ble "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/sl_bluetooth.c"
click node_key_gatt "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/gatt_db.c"
click node_key_init "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/main.c"
click node_key_power "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/sl_power_manager_handler.c"
click node_web_server "https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Web/server.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_gateway_main,node_gateway_net,node_gateway_ui,node_gateway_ble,node_gateway_usb,node_mesh,node_user,node_browser toneBlue
class node_key_app,node_key_ble,node_key_gatt,node_key_init,node_key_power toneAmber
class node_web_server toneMint
class node_pc,node_grub toneRose
```

## Components

### ESP32 Gateway

- [Gateway Runtime](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c): `Firmware/ESP32_S3_Mesh/main/main.c`
- [Wi-Fi Network](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c): `Firmware/ESP32_S3_Mesh/main/main.c`
- [Screen UI](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/components/LVGL_UI.c): `Firmware/ESP32_S3_Mesh/components/LVGL_UI.c`
- [BLE Client](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/components/ble_client.c): `Firmware/ESP32_S3_Mesh/components/ble_client.c`
- [USB HID](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/ESP32_S3_Mesh/main/main.c): `Firmware/ESP32_S3_Mesh/main/main.c`
- [Mesh Networking](https://github.com/mr-pian/grub-friendly-starting-up-system/tree/main/Firmware/ESP32_S3_Mesh): `Firmware/ESP32_S3_Mesh`

### BLE Key

- [Key Application](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/app.c): `Firmware/GRUB_Key/app.c`
- [Bluetooth Stack](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/sl_bluetooth.c): `Firmware/GRUB_Key/autogen/sl_bluetooth.c`
- [GATT Database](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/gatt_db.c): `Firmware/GRUB_Key/autogen/gatt_db.c`
- [Device Runtime](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/main.c): `Firmware/GRUB_Key/main.c`
- [Power Management](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Firmware/GRUB_Key/autogen/sl_power_manager_handler.c): `Firmware/GRUB_Key/autogen/sl_power_manager_handler.c`

### Web Control

- [Web Server](https://github.com/mr-pian/grub-friendly-starting-up-system/blob/main/Web/server.js): `Web/server.js`

### PC Startup

- **Target PC**
- **GRUB Boot Menu**

### Other components

- **User**
- **Browser**

## Connections

- User → Screen UI: interacts with (evidence: `README.md`)
- User → Browser: controls through (evidence: `README.md`)
- Browser → Web Server: requests control (evidence: `README.md`)
- Web Server → Gateway Runtime: controls remotely (evidence: `README.md`)
- Gateway Runtime → Wi-Fi Network: initializes Wi-Fi (evidence: `Firmware/ESP32_S3_Mesh/main/main.c`)
- Gateway Runtime → USB HID: installs HID (evidence: `Firmware/ESP32_S3_Mesh/main/main.c`)
- USB HID → Target PC: sends keystrokes (evidence: `Firmware/ESP32_S3_Mesh/main/main.c`)
- Target PC → GRUB Boot Menu: boots into (evidence: `README.md`)
- Gateway Runtime → Screen UI: starts display (evidence: `README.md`)
- Gateway Runtime → BLE Client: uses BLE client (evidence: `README.md`)
- BLE Client → Key Application: scans and connects (evidence: `Firmware/ESP32_S3_Mesh/components/ble_client.c`)
- Key Application → Bluetooth Stack: updates advertising (evidence: `Firmware/GRUB_Key/app.c`)
- Key Application → GATT Database: uses GATT data (evidence: `Firmware/GRUB_Key/app.c`)
- Device Runtime → Key Application: initializes application (evidence: `Firmware/GRUB_Key/main.c`)
- Key Application → BLE Client: advertises state (evidence: `Firmware/GRUB_Key/app.c`)
- BLE Client → Key Application: writes commands (evidence: `Firmware/ESP32_S3_Mesh/components/ble_client.c`)
- Key Application → Power Management: coordinates sleep
- Gateway Runtime → Mesh Networking: supports mesh (evidence: `README.md`)
