# gedxxe/adaptive-lora architecture

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

- Interactive diagram: https://gitdiagram.com/gedxxe/adaptive-lora
- Repository: https://github.com/gedxxe/adaptive-lora

## Overview

Adaptive-LoRa is ESP32 firmware for a private, single-radio LoRa peer-to-peer network, currently implementing a fixed-PHY HELLO/ACK baseline rather than the planned TDMA and link-adaptation features. Its principal workflow loads and validates a provisioned role, then runs the client or gateway state machine over a shared radio driver; serial provisioning handles missing or invalid configuration. The README documents these boundaries and responsibilities, while sampled source confirms several interfaces and imports. Some runtime wiring is documented rather than visible in the excerpts, so the graph cites the README for those links.

Main entry points: [`src/app/firmware_runtime.cpp`](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/firmware_runtime.cpp) (Runtime coordinator), [`src/client/client_app.cpp`](https://github.com/gedxxe/adaptive-lora/blob/main/src/client/client_app.cpp) (Client state machine), [`src/gateway/gateway_app.cpp`](https://github.com/gedxxe/adaptive-lora/blob/main/src/gateway/gateway_app.cpp) (Gateway state machine), [`src/app/nvs_config_store.cpp`](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/nvs_config_store.cpp) (NVS config store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware runtime"]
  node_main["Firmware entry<br/>[main.cpp]"]
  node_runtime_core["Runtime coordinator"]
  node_provision["Provisioning console"]
  node_client["Client state machine<br/>[client_app.cpp]"]
  node_gateway["Gateway state machine<br/>[gateway_app.cpp]"]
end

subgraph group_config["Configuration"]
  node_config_model["Config model<br/>[device_config.cpp]"]
  node_nvs_store["NVS config store"]
  node_config_contract["Storage contract<br/>[config_storage.h]"]
  node_preferences["Preferences adapter"]
end

subgraph group_protocol["Protocol"]
  node_codec["Frame codec<br/>[frame_codec.cpp]"]
  node_sequence["Sequence and sessions"]
end

subgraph group_radio["Radio"]
  node_radio_driver["Radio driver<br/>[radio_driver.cpp]"]
  node_llcc68["LLCC68 hardware"]
end

subgraph group_ops["Diagnostics"]
  node_logger["Serial logger<br/>[serial_logger.cpp]"]
end

node_operator(("Serial operator"))
node_flash[("ESP32 NVS")]
node_peer(("LoRa peer"))

node_operator -->|"enters commands"| node_provision
node_main -->|"starts runtime"| node_runtime_core
node_runtime_core -->|"loads configuration"| node_nvs_store
node_nvs_store -->|"validates config"| node_config_model
node_runtime_core -->|"routes invalid config"| node_provision
node_provision -->|"saves configuration"| node_nvs_store
node_preferences -->|"implements"| node_config_contract
node_nvs_store -->|"uses storage contract"| node_config_contract
node_preferences -->|"accesses Preferences"| node_flash
node_runtime_core -->|"selects client role"| node_client
node_runtime_core -->|"selects gateway role"| node_gateway
node_client -->|"transmits and receives"| node_radio_driver
node_gateway -->|"listens and replies"| node_radio_driver
node_client -.->|"encodes and checks frames"| node_codec
node_gateway -.->|"encodes and checks frames"| node_codec
node_gateway -->|"tracks duplicates"| node_sequence
node_client -->|"tracks sessions"| node_sequence
node_radio_driver -->|"delegates hardware"| node_llcc68
node_llcc68 -->|"sends and receives radio"| node_peer
node_client -.->|"records events"| node_logger
node_gateway -.->|"records events"| node_logger

click node_main "https://github.com/gedxxe/adaptive-lora/blob/main/src/main.cpp"
click node_runtime_core "https://github.com/gedxxe/adaptive-lora/blob/main/src/app/firmware_runtime.cpp"
click node_provision "https://github.com/gedxxe/adaptive-lora/blob/main/src/app/provisioning_console.cpp"
click node_client "https://github.com/gedxxe/adaptive-lora/blob/main/src/client/client_app.cpp"
click node_gateway "https://github.com/gedxxe/adaptive-lora/blob/main/src/gateway/gateway_app.cpp"
click node_config_model "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/config/device_config.cpp"
click node_nvs_store "https://github.com/gedxxe/adaptive-lora/blob/main/src/app/nvs_config_store.cpp"
click node_config_contract "https://github.com/gedxxe/adaptive-lora/blob/main/src/app/config_storage.h"
click node_preferences "https://github.com/gedxxe/adaptive-lora/blob/main/src/app/preferences_config_storage.cpp"
click node_codec "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/protocol/frame_codec.cpp"
click node_sequence "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/protocol/sequence_tracker.cpp"
click node_radio_driver "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/radio/radio_driver.cpp"
click node_llcc68 "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/radio/llcc68_hardware.cpp"
click node_logger "https://github.com/gedxxe/adaptive-lora/blob/main/src/common/diagnostics/serial_logger.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_main,node_runtime_core,node_provision,node_client,node_gateway toneBlue
class node_config_model,node_nvs_store,node_config_contract,node_preferences,node_flash toneAmber
class node_codec,node_sequence toneMint
class node_radio_driver,node_llcc68 toneRose
class node_logger,node_operator,node_peer toneIndigo
```

## Components

### Firmware runtime

- [Firmware entry](https://github.com/gedxxe/adaptive-lora/blob/main/src/main.cpp): `src/main.cpp`
- [Runtime coordinator](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/firmware_runtime.cpp): `src/app/firmware_runtime.cpp`
- [Provisioning console](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/provisioning_console.cpp): `src/app/provisioning_console.cpp`
- [Client state machine](https://github.com/gedxxe/adaptive-lora/blob/main/src/client/client_app.cpp): `src/client/client_app.cpp`
- [Gateway state machine](https://github.com/gedxxe/adaptive-lora/blob/main/src/gateway/gateway_app.cpp): `src/gateway/gateway_app.cpp`

### Configuration

- [Config model](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/config/device_config.cpp): `src/common/config/device_config.cpp`
- [NVS config store](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/nvs_config_store.cpp): `src/app/nvs_config_store.cpp`
- [Storage contract](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/config_storage.h): `src/app/config_storage.h`
- [Preferences adapter](https://github.com/gedxxe/adaptive-lora/blob/main/src/app/preferences_config_storage.cpp): `src/app/preferences_config_storage.cpp`

### Protocol

- [Frame codec](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/protocol/frame_codec.cpp): `src/common/protocol/frame_codec.cpp`
- [Sequence and sessions](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/protocol/sequence_tracker.cpp): `src/common/protocol/sequence_tracker.cpp`

### Radio

- [Radio driver](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/radio/radio_driver.cpp): `src/common/radio/radio_driver.cpp`
- [LLCC68 hardware](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/radio/llcc68_hardware.cpp): `src/common/radio/llcc68_hardware.cpp`

### Diagnostics

- [Serial logger](https://github.com/gedxxe/adaptive-lora/blob/main/src/common/diagnostics/serial_logger.cpp): `src/common/diagnostics/serial_logger.cpp`

### Other components

- **Serial operator**
- **ESP32 NVS**
- **LoRa peer**

## Connections

- Serial operator → Provisioning console: enters commands (evidence: `README.md`)
- Firmware entry → Runtime coordinator: starts runtime (evidence: `README.md`)
- Runtime coordinator → NVS config store: loads configuration (evidence: `README.md`)
- NVS config store → Config model: validates config (evidence: `README.md`)
- Runtime coordinator → Provisioning console: routes invalid config (evidence: `README.md`)
- Provisioning console → NVS config store: saves configuration (evidence: `README.md`)
- Preferences adapter → Storage contract: implements (evidence: `src/app/preferences_config_storage.cpp`)
- NVS config store → Storage contract: uses storage contract (evidence: `README.md`)
- Preferences adapter → ESP32 NVS: accesses Preferences (evidence: `README.md`)
- Runtime coordinator → Client state machine: selects client role (evidence: `README.md`)
- Runtime coordinator → Gateway state machine: selects gateway role (evidence: `README.md`)
- Client state machine → Radio driver: transmits and receives (evidence: `README.md`)
- Gateway state machine → Radio driver: listens and replies (evidence: `README.md`)
- Client state machine → Frame codec: encodes and checks frames
- Gateway state machine → Frame codec: encodes and checks frames
- Gateway state machine → Sequence and sessions: tracks duplicates (evidence: `README.md`)
- Client state machine → Sequence and sessions: tracks sessions (evidence: `README.md`)
- Radio driver → LLCC68 hardware: delegates hardware (evidence: `README.md`)
- LLCC68 hardware → LoRa peer: sends and receives radio (evidence: `README.md`)
- Client state machine → Serial logger: records events
- Gateway state machine → Serial logger: records events