# tristanedu/litime-esp32-gateway architecture

> Architecture diagram of the GitHub repository tristanedu/litime-esp32-gateway, 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/tristanedu/litime-esp32-gateway
- Repository: https://github.com/tristanedu/litime-esp32-gateway

## Overview

LiTime ESP32 Gateway is a read-only battery-monitoring gateway. The main workflow discovers a LiTime battery over BLE, obtains live telemetry, exposes it through local APIs and the browser dashboard, and buffers bounded history and remote-sync data in LittleFS. Setup users can scan for and save Wi-Fi networks while retaining the setup access point. Optional branches push queued batches to a configured HTTPS endpoint or relay live status through a Cloudflare-hosted dashboard. The README documents these capabilities; the available firmware excerpts do not include the main API and BLE orchestration source, so those links use the existing firmware source directory and are limited to documented behavior.

Main entry points: [`firmware/src`](https://github.com/tristanedu/litime-esp32-gateway/tree/main/firmware/src) (Gateway runtime), [`firmware/src/StorageManager.cpp`](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/src/StorageManager.cpp) (Telemetry buffer), [`cloudflare/remote-dashboard/public/app.js`](https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/public/app.js) (Remote dashboard), [`firmware/libraries/NimBLE-Arduino/src/NimBLEClient.cpp`](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/libraries/NimBLE-Arduino/src/NimBLEClient.cpp) (NimBLE central)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway firmware"]
  node_firmware["Gateway runtime"]
  node_network["Wi-Fi management<br/>[NetworkManager.cpp]"]
  node_storage["Telemetry buffer<br/>[StorageManager.cpp]"]
  node_littlefs[("LittleFS")]
end

subgraph group_ble["BLE transport"]
  node_nimble["NimBLE central<br/>[NimBLEClient.cpp]"]
  node_blehost["NimBLE host"]
end

subgraph group_local["Local dashboard"]
  node_webui["Local web UI<br/>[app.js]"]
end

subgraph group_remote["Remote access"]
  node_remoteui["Remote dashboard<br/>[app.js]"]
  node_estimator["Runtime estimator"]
  node_worker["WebSocket relay<br/>[index.js]"]
end

node_owner(("Gateway owner"))
node_battery(("LiTime battery"))
node_browser(("Local browser"))
node_https(("User HTTPS endpoint"))

node_owner -->|"opens dashboard"| node_browser
node_battery -->|"BLE telemetry"| node_nimble
node_firmware -->|"scans and connects"| node_nimble
node_nimble -->|"uses host stack"| node_blehost
node_firmware -->|"records telemetry"| node_storage
node_storage -->|"reads and writes"| node_littlefs
node_firmware -->|"manages Wi-Fi"| node_network
node_browser -->|"loads UI"| node_webui
node_webui -->|"requests local APIs"| node_firmware
node_network -->|"provides network status"| node_firmware
node_firmware -->|"serves history and events"| node_storage
node_firmware -.->|"posts queued batches"| node_https
node_storage -.->|"provides remote batches"| node_firmware
node_browser -.->|"opens dashboard"| node_remoteui
node_remoteui -.->|"requests status"| node_worker
node_worker -.->|"relays authenticated status"| node_firmware
node_firmware -.->|"sends battery snapshot"| node_worker
node_remoteui -.->|"estimates runtime"| node_estimator

click node_firmware "https://github.com/tristanedu/litime-esp32-gateway/tree/main/firmware/src"
click node_network "https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/src/NetworkManager.cpp"
click node_storage "https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/src/StorageManager.cpp"
click node_nimble "https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/libraries/NimBLE-Arduino/src/NimBLEClient.cpp"
click node_blehost "https://github.com/tristanedu/litime-esp32-gateway/tree/main/firmware/libraries/NimBLE-Arduino/src/nimble/nimble/host/src"
click node_webui "https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/data/app.js"
click node_remoteui "https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/public/app.js"
click node_estimator "https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/public/runtime-estimate.mjs"
click node_worker "https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/src/index.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_firmware,node_network,node_storage,node_littlefs,node_browser,node_https toneBlue
class node_nimble,node_blehost toneAmber
class node_webui toneMint
class node_remoteui,node_estimator,node_worker toneRose
class node_owner,node_battery toneIndigo
```

## Components

### Gateway firmware

- [Gateway runtime](https://github.com/tristanedu/litime-esp32-gateway/tree/main/firmware/src): `firmware/src`
- [Wi-Fi management](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/src/NetworkManager.cpp): `firmware/src/NetworkManager.cpp`
- [Telemetry buffer](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/src/StorageManager.cpp): `firmware/src/StorageManager.cpp`
- **LittleFS**

### BLE transport

- [NimBLE central](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/libraries/NimBLE-Arduino/src/NimBLEClient.cpp): `firmware/libraries/NimBLE-Arduino/src/NimBLEClient.cpp`
- [NimBLE host](https://github.com/tristanedu/litime-esp32-gateway/tree/main/firmware/libraries/NimBLE-Arduino/src/nimble/nimble/host/src): `firmware/libraries/NimBLE-Arduino/src/nimble/nimble/host/src`

### Local dashboard

- [Local web UI](https://github.com/tristanedu/litime-esp32-gateway/blob/main/firmware/data/app.js): `firmware/data/app.js`

### Remote access

- [Remote dashboard](https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/public/app.js): `cloudflare/remote-dashboard/public/app.js`
- [Runtime estimator](https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/public/runtime-estimate.mjs): `cloudflare/remote-dashboard/public/runtime-estimate.mjs`
- [WebSocket relay](https://github.com/tristanedu/litime-esp32-gateway/blob/main/cloudflare/remote-dashboard/src/index.js): `cloudflare/remote-dashboard/src/index.js`

### Other components

- **Gateway owner**
- **LiTime battery**
- **Local browser**
- **User HTTPS endpoint**

## Connections

- Gateway owner → Local browser: opens dashboard
- LiTime battery → NimBLE central: BLE telemetry
- Gateway runtime → NimBLE central: scans and connects
- NimBLE central → NimBLE host: uses host stack
- Gateway runtime → Telemetry buffer: records telemetry
- Telemetry buffer → LittleFS: reads and writes
- Gateway runtime → Wi-Fi management: manages Wi-Fi
- Local browser → Local web UI: loads UI
- Local web UI → Gateway runtime: requests local APIs
- Wi-Fi management → Gateway runtime: provides network status
- Gateway runtime → Telemetry buffer: serves history and events
- Gateway runtime → User HTTPS endpoint: posts queued batches
- Telemetry buffer → Gateway runtime: provides remote batches
- Local browser → Remote dashboard: opens dashboard
- Remote dashboard → WebSocket relay: requests status
- WebSocket relay → Gateway runtime: relays authenticated status
- Gateway runtime → WebSocket relay: sends battery snapshot
- Remote dashboard → Runtime estimator: estimates runtime