# shadowroot2/zephcore architecture

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

- Interactive diagram: https://gitdiagram.com/shadowroot2/zephcore
- Repository: https://github.com/shadowroot2/zephcore

## Overview

ZephCore is Zephyr-based firmware for MeshCore-compatible LoRa mesh nodes. A companion node exchanges MeshCore protocol traffic with an app over BLE, USB, or (on supported ESP32 boards) WiFi; the firmware also provides distinct repeater, room-server, observer, KISS-modem, and repeater-bridge roles. The sampled sources show companion composition, GPS event processing, sensor telemetry, and adaptive CAD; the README documents additional role and feature branches. Many role implementations and transport links are unsampled, so those relationships are omitted or marked unverified.

Main entry points: [`zephcore/src/main_companion.cpp`](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/main_companion.cpp) (Companion runtime), [`zephcore/adapters/radio/LoRaRadio.cpp`](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/radio/LoRaRadio.cpp) (LoRa radio), [`zephcore/src/Mesh.cpp`](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Mesh.cpp) (Mesh engine), [`zephcore/app/CompanionMesh.cpp`](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/CompanionMesh.cpp) (Companion mesh)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Mesh runtime"]
  node_companion_main["Companion runtime<br/>[main_companion.cpp]"]
  node_companion_mesh["Companion mesh<br/>[CompanionMesh.cpp]"]
  node_mesh_engine["Mesh engine<br/>[Mesh.cpp]"]
  node_packet_dispatch["Packet dispatch<br/>[Dispatcher.cpp]"]
  node_identity["Mesh identity<br/>[Identity.cpp]"]
  node_companion_protocol["Companion protocol"]
  node_crypto["Cryptography<br/>[monocypher.c]"]
end

subgraph group_roles["Device roles"]
  node_repeater["Repeater role<br/>[RepeaterMesh.cpp]"]
  node_room_server["Room server<br/>[RoomServerMesh.cpp]"]
  node_observer["Observer role<br/>[ObserverMesh.cpp]"]
  node_kiss_modem["KISS modem<br/>[KissModem.cpp]"]
  node_repeater_bridge["Repeater bridge<br/>[RepeaterBridge.cpp]"]
end

subgraph group_io["Radio and transports"]
  node_lora_radio["LoRa radio<br/>[LoRaRadio.cpp]"]
  node_cad_control["Adaptive CAD<br/>[CadController.cpp]"]
  node_lr20xx_driver["LR20xx driver"]
  node_ble["BLE adapter<br/>[ZephyrBLE.cpp]"]
  node_usb["USB companion"]
  node_wifi["WiFi station"]
  node_mqtt["MQTT uplink"]
end

subgraph group_device["Device services"]
  node_gps["GPS manager"]
  node_sensors["Sensor telemetry"]
  node_datastore[("Persistent data")]
end

subgraph group_features["User features"]
  node_display["Display UI<br/>[display.h]"]
  node_ui_task["UI task<br/>[ui_task.h]"]
  node_ota["WiFi OTA<br/>[wifi_ota.c]"]
end

node_meshcore_app(("MeshCore app"))

node_meshcore_app -->|"connects to"| node_companion_main
node_companion_main -->|"runs"| node_companion_mesh
node_companion_main -->|"enables transport"| node_ble
node_companion_main -->|"enables transport"| node_usb
node_companion_mesh -->|"implements protocol"| node_companion_protocol
node_companion_main -->|"instantiates"| node_lora_radio
node_companion_main -.->|"uses mesh runtime"| node_mesh_engine
node_mesh_engine -.->|"dispatches packets"| node_packet_dispatch
node_mesh_engine -.->|"uses identity"| node_identity
node_lora_radio -->|"feeds probe results"| node_cad_control
node_lora_radio -.->|"uses radio driver"| node_lr20xx_driver
node_companion_main -.->|"processes GPS events"| node_gps
node_sensors -->|"reads position"| node_gps
node_sensors -.->|"provides telemetry"| node_companion_mesh
node_companion_main -->|"composes UI"| node_display
node_companion_main -->|"starts UI"| node_ui_task
node_repeater -.->|"uses mesh radio"| node_lora_radio
node_room_server -->|"serves app users"| node_companion_protocol
node_observer -->|"publishes received traffic"| node_mqtt
node_kiss_modem -->|"provides raw modem"| node_lora_radio
node_repeater_bridge -->|"bridges radio nodes"| node_lora_radio
node_companion_main -->|"optional transport"| node_wifi
node_companion_main -.->|"persists settings"| node_datastore
node_companion_main -.->|"offers update service"| node_ota
node_mesh_engine -.->|"uses cryptography"| node_crypto

click node_companion_main "https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/main_companion.cpp"
click node_companion_mesh "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/CompanionMesh.cpp"
click node_mesh_engine "https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Mesh.cpp"
click node_packet_dispatch "https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Dispatcher.cpp"
click node_identity "https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Identity.cpp"
click node_companion_protocol "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/CompanionProtocol.h"
click node_repeater "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RepeaterMesh.cpp"
click node_room_server "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RoomServerMesh.cpp"
click node_observer "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/ObserverMesh.cpp"
click node_kiss_modem "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/KissModem.cpp"
click node_repeater_bridge "https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RepeaterBridge.cpp"
click node_lora_radio "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/radio/LoRaRadio.cpp"
click node_cad_control "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/radio/CadController.cpp"
click node_lr20xx_driver "https://github.com/shadowroot2/zephcore/tree/master/zephcore/patches/zephyr-new/drivers/lora/lr20xx"
click node_ble "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/ble/ZephyrBLE.cpp"
click node_usb "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/usb/ZephyrCompanionUSB.cpp"
click node_wifi "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/wifi/ZephyrWiFiStation.c"
click node_mqtt "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/mqtt/ZephyrMQTTPublisher.c"
click node_gps "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/gps/ZephyrGPSManager.cpp"
click node_sensors "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/sensors/ZephyrSensorManager.cpp"
click node_datastore "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/datastore/ZephyrDataStore.cpp"
click node_display "https://github.com/shadowroot2/zephcore/blob/master/zephcore/helpers/ui/display.h"
click node_ui_task "https://github.com/shadowroot2/zephcore/blob/master/zephcore/helpers/ui/ui_task.h"
click node_ota "https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/ota/wifi_ota.c"
click node_crypto "https://github.com/shadowroot2/zephcore/blob/master/zephcore/lib/monocypher/monocypher.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_companion_main,node_companion_mesh,node_mesh_engine,node_packet_dispatch,node_identity,node_companion_protocol,node_crypto toneBlue
class node_repeater,node_room_server,node_observer,node_kiss_modem,node_repeater_bridge toneAmber
class node_lora_radio,node_cad_control,node_lr20xx_driver,node_ble,node_usb,node_wifi,node_mqtt toneMint
class node_gps,node_sensors,node_datastore toneRose
class node_display,node_ui_task,node_ota,node_meshcore_app toneIndigo
```

## Components

### Mesh runtime

- [Companion runtime](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/main_companion.cpp): `zephcore/src/main_companion.cpp`
- [Companion mesh](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/CompanionMesh.cpp): `zephcore/app/CompanionMesh.cpp`
- [Mesh engine](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Mesh.cpp): `zephcore/src/Mesh.cpp`
- [Packet dispatch](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Dispatcher.cpp): `zephcore/src/Dispatcher.cpp`
- [Mesh identity](https://github.com/shadowroot2/zephcore/blob/master/zephcore/src/Identity.cpp): `zephcore/src/Identity.cpp`
- [Companion protocol](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/CompanionProtocol.h): `zephcore/app/CompanionProtocol.h`
- [Cryptography](https://github.com/shadowroot2/zephcore/blob/master/zephcore/lib/monocypher/monocypher.c): `zephcore/lib/monocypher/monocypher.c`

### Device roles

- [Repeater role](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RepeaterMesh.cpp): `zephcore/app/RepeaterMesh.cpp`
- [Room server](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RoomServerMesh.cpp): `zephcore/app/RoomServerMesh.cpp`
- [Observer role](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/ObserverMesh.cpp): `zephcore/app/ObserverMesh.cpp`
- [KISS modem](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/KissModem.cpp): `zephcore/app/KissModem.cpp`
- [Repeater bridge](https://github.com/shadowroot2/zephcore/blob/master/zephcore/app/RepeaterBridge.cpp): `zephcore/app/RepeaterBridge.cpp`

### Radio and transports

- [LoRa radio](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/radio/LoRaRadio.cpp): `zephcore/adapters/radio/LoRaRadio.cpp`
- [Adaptive CAD](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/radio/CadController.cpp): `zephcore/adapters/radio/CadController.cpp`
- [LR20xx driver](https://github.com/shadowroot2/zephcore/tree/master/zephcore/patches/zephyr-new/drivers/lora/lr20xx): `zephcore/patches/zephyr-new/drivers/lora/lr20xx`
- [BLE adapter](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/ble/ZephyrBLE.cpp): `zephcore/adapters/ble/ZephyrBLE.cpp`
- [USB companion](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/usb/ZephyrCompanionUSB.cpp): `zephcore/adapters/usb/ZephyrCompanionUSB.cpp`
- [WiFi station](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/wifi/ZephyrWiFiStation.c): `zephcore/adapters/wifi/ZephyrWiFiStation.c`
- [MQTT uplink](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/mqtt/ZephyrMQTTPublisher.c): `zephcore/adapters/mqtt/ZephyrMQTTPublisher.c`

### Device services

- [GPS manager](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/gps/ZephyrGPSManager.cpp): `zephcore/adapters/gps/ZephyrGPSManager.cpp`
- [Sensor telemetry](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/sensors/ZephyrSensorManager.cpp): `zephcore/adapters/sensors/ZephyrSensorManager.cpp`
- [Persistent data](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/datastore/ZephyrDataStore.cpp): `zephcore/adapters/datastore/ZephyrDataStore.cpp`

### User features

- [Display UI](https://github.com/shadowroot2/zephcore/blob/master/zephcore/helpers/ui/display.h): `zephcore/helpers/ui/display.h`
- [UI task](https://github.com/shadowroot2/zephcore/blob/master/zephcore/helpers/ui/ui_task.h): `zephcore/helpers/ui/ui_task.h`
- [WiFi OTA](https://github.com/shadowroot2/zephcore/blob/master/zephcore/adapters/ota/wifi_ota.c): `zephcore/adapters/ota/wifi_ota.c`

### Other components

- **MeshCore app**

## Connections

- MeshCore app → Companion runtime: connects to (evidence: `README.md`)
- Companion runtime → Companion mesh: runs (evidence: `zephcore/src/main_companion.cpp`)
- Companion runtime → BLE adapter: enables transport (evidence: `zephcore/src/main_companion.cpp`)
- Companion runtime → USB companion: enables transport (evidence: `zephcore/src/main_companion.cpp`)
- Companion mesh → Companion protocol: implements protocol (evidence: `zephcore/app/CompanionMesh.cpp`)
- Companion runtime → LoRa radio: instantiates (evidence: `zephcore/src/main_companion.cpp`)
- Companion runtime → Mesh engine: uses mesh runtime
- Mesh engine → Packet dispatch: dispatches packets
- Mesh engine → Mesh identity: uses identity
- LoRa radio → Adaptive CAD: feeds probe results
- LoRa radio → LR20xx driver: uses radio driver
- Companion runtime → GPS manager: processes GPS events
- Sensor telemetry → GPS manager: reads position (evidence: `zephcore/adapters/sensors/ZephyrSensorManager.cpp`)
- Sensor telemetry → Companion mesh: provides telemetry
- Companion runtime → Display UI: composes UI (evidence: `zephcore/src/main_companion.cpp`)
- Companion runtime → UI task: starts UI (evidence: `zephcore/src/main_companion.cpp`)
- Repeater role → LoRa radio: uses mesh radio
- Room server → Companion protocol: serves app users (evidence: `README.md`)
- Observer role → MQTT uplink: publishes received traffic (evidence: `README.md`)
- KISS modem → LoRa radio: provides raw modem (evidence: `README.md`)
- Repeater bridge → LoRa radio: bridges radio nodes (evidence: `README.md`)
- Companion runtime → WiFi station: optional transport (evidence: `README.md`)
- Companion runtime → Persistent data: persists settings
- Companion runtime → WiFi OTA: offers update service
- Mesh engine → Cryptography: uses cryptography