# metay09/orun-tlp-system architecture

> Architecture diagram of the GitHub repository metay09/orun-tlp-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metay09/orun-tlp-system
- Repository: https://github.com/metay09/orun-tlp-system

## Overview

ORUN TLP is embedded firmware for a low-power location and activity-tracking device with LoRa networking and BLE application access. Its principal workflow is to acquire GNSS fixes, map them into position packets, and transmit them over radio; radio networking also supports relaying. Separate capabilities cover accelerometer-based activity capture, geofencing, BLE requests and handoff, and durable configuration, history, and security state. The excerpts show peripheral managers and parts of the main composition, but not the full loop or most subsystem implementations, so uncertain dispatch and persistence links are omitted.

Main entry points: [`firmware/src/position_flow.cpp`](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/position_flow.cpp) (Position flow), [`firmware/src/main.cpp`](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/main.cpp) (Firmware composition), [`firmware/src/activity_capture.cpp`](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_capture.cpp) (Activity capture), [`firmware/src/radio_manager.cpp`](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/radio_manager.cpp) (Radio manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Sensing"]
  node_gnss_manager["GNSS acquisition<br/>[gnss_manager.cpp]"]
  node_accelerometer_manager["Accelerometer sampling"]
  node_sensor_power["Sensor power control"]
  node_i2c_recovery["I2C recovery<br/>[i2c_recovery.cpp]"]
  node_activity_capture["Activity capture"]
  node_activity_quality["Activity quality"]
  node_activity_window["Activity windows"]
end

subgraph group_location_network["Location and LoRa"]
  node_position_flow["Position flow<br/>[position_flow.cpp]"]
  node_position_mapping["Legacy position mapping"]
  node_position_packet["Position packet"]
  node_radio_manager["Radio manager<br/>[radio_manager.cpp]"]
  node_network_service["Network and relay"]
  node_relay_packet["Relay packet"]
end

subgraph group_device_apps["Device applications"]
  node_main["Firmware composition<br/>[main.cpp]"]
  node_geofence_runtime["Geofence runtime"]
  node_ble_transport["BLE application transport"]
  node_ble_handoff["BLE application handoff"]
  node_application_request["Application requests"]
  node_watchdog["Watchdog"]
end

subgraph group_durable_state["Durable state"]
  node_config_store[("Configuration store<br/>[config_store.cpp]")]
  node_history_store[("History store<br/>[history_store.cpp]")]
  node_security_store[("Security store<br/>[security_store.cpp]")]
  node_flash_gate["Flash mutation gate"]
end

node_device_user(("Device user"))
node_gnss_receiver["GNSS receiver"]
node_accelerometer["Accelerometer"]
node_lora_network["LoRa network"]
node_flash[("Device flash")]
node_ble_client(("BLE client"))

node_main -->|"starts and feeds"| node_watchdog
node_main -->|"initializes"| node_sensor_power
node_main -->|"sets identity"| node_radio_manager
node_main -->|"sets identity"| node_position_flow
node_gnss_manager -->|"acquires fixes"| node_gnss_receiver
node_gnss_manager -->|"owns sensor rail"| node_sensor_power
node_gnss_manager -->|"recovers bus"| node_i2c_recovery
node_accelerometer_manager -->|"reads samples"| node_accelerometer
node_accelerometer_manager -->|"recovers bus"| node_i2c_recovery
node_activity_capture -->|"requests samples"| node_accelerometer_manager
node_activity_capture -->|"uses quality checks"| node_activity_quality
node_activity_capture -->|"uses windows"| node_activity_window
node_position_flow -->|"maps fixes"| node_position_mapping
node_position_flow -->|"encodes positions"| node_position_packet
node_position_flow -->|"submits packets"| node_radio_manager
node_radio_manager -->|"transmits and receives"| node_lora_network
node_radio_manager -->|"initializes network"| node_network_service
node_network_service -->|"uses relay format"| node_relay_packet
node_ble_client -->|"exchanges messages"| node_ble_transport
node_ble_transport -->|"hands off data"| node_ble_handoff
node_ble_transport -->|"handles requests"| node_application_request
node_device_user -.->|"starts capture"| node_activity_capture
node_config_store -->|"persists config"| node_flash
node_history_store -->|"persists history"| node_flash
node_security_store -->|"persists security state"| node_flash
node_config_store -.->|"arbitrates mutations"| node_flash_gate
node_history_store -.->|"arbitrates mutations"| node_flash_gate
node_security_store -.->|"arbitrates mutations"| node_flash_gate
node_geofence_runtime -.->|"uses position flow"| node_position_flow

click node_main "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/main.cpp"
click node_gnss_manager "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/gnss_manager.cpp"
click node_accelerometer_manager "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/accelerometer_manager.cpp"
click node_sensor_power "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/sensor_power_manager.cpp"
click node_i2c_recovery "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/i2c_recovery.cpp"
click node_activity_capture "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_capture.cpp"
click node_activity_quality "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_quality.cpp"
click node_activity_window "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_window.cpp"
click node_position_flow "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/position_flow.cpp"
click node_position_mapping "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/legacy_position_mapping.cpp"
click node_position_packet "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/tlp_position_packet.cpp"
click node_radio_manager "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/radio_manager.cpp"
click node_network_service "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/network_service.cpp"
click node_relay_packet "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/tlp_relay_forward_packet.cpp"
click node_geofence_runtime "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/geofence_runtime.cpp"
click node_ble_transport "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/ble_application_transport.cpp"
click node_ble_handoff "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/ble_application_handoff.cpp"
click node_application_request "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/application_request.cpp"
click node_config_store "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/config_store.cpp"
click node_history_store "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/history_store.cpp"
click node_security_store "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/security_store.cpp"
click node_flash_gate "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/flash_mutation_gate.cpp"
click node_watchdog "https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/watchdog_manager.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_gnss_manager,node_accelerometer_manager,node_sensor_power,node_i2c_recovery,node_activity_capture,node_activity_quality,node_activity_window,node_device_user,node_ble_client toneBlue
class node_position_flow,node_position_mapping,node_position_packet,node_radio_manager,node_network_service,node_relay_packet,node_flash toneAmber
class node_main,node_geofence_runtime,node_ble_transport,node_ble_handoff,node_application_request,node_watchdog toneMint
class node_config_store,node_history_store,node_security_store,node_flash_gate toneRose
class node_gnss_receiver,node_accelerometer,node_lora_network toneIndigo
```

## Components

### Sensing

- [GNSS acquisition](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/gnss_manager.cpp): `firmware/src/gnss_manager.cpp`
- [Accelerometer sampling](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/accelerometer_manager.cpp): `firmware/src/accelerometer_manager.cpp`
- [Sensor power control](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/sensor_power_manager.cpp): `firmware/src/sensor_power_manager.cpp`
- [I2C recovery](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/i2c_recovery.cpp): `firmware/src/i2c_recovery.cpp`
- [Activity capture](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_capture.cpp): `firmware/src/activity_capture.cpp`
- [Activity quality](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_quality.cpp): `firmware/src/activity_quality.cpp`
- [Activity windows](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/activity_window.cpp): `firmware/src/activity_window.cpp`

### Location and LoRa

- [Position flow](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/position_flow.cpp): `firmware/src/position_flow.cpp`
- [Legacy position mapping](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/legacy_position_mapping.cpp): `firmware/src/legacy_position_mapping.cpp`
- [Position packet](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/tlp_position_packet.cpp): `firmware/src/tlp_position_packet.cpp`
- [Radio manager](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/radio_manager.cpp): `firmware/src/radio_manager.cpp`
- [Network and relay](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/network_service.cpp): `firmware/src/network_service.cpp`
- [Relay packet](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/tlp_relay_forward_packet.cpp): `firmware/src/tlp_relay_forward_packet.cpp`

### Device applications

- [Firmware composition](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Geofence runtime](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/geofence_runtime.cpp): `firmware/src/geofence_runtime.cpp`
- [BLE application transport](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/ble_application_transport.cpp): `firmware/src/ble_application_transport.cpp`
- [BLE application handoff](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/ble_application_handoff.cpp): `firmware/src/ble_application_handoff.cpp`
- [Application requests](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/application_request.cpp): `firmware/src/application_request.cpp`
- [Watchdog](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/watchdog_manager.cpp): `firmware/src/watchdog_manager.cpp`

### Durable state

- [Configuration store](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/config_store.cpp): `firmware/src/config_store.cpp`
- [History store](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/history_store.cpp): `firmware/src/history_store.cpp`
- [Security store](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/security_store.cpp): `firmware/src/security_store.cpp`
- [Flash mutation gate](https://github.com/metay09/orun-tlp-system/blob/main/firmware/src/flash_mutation_gate.cpp): `firmware/src/flash_mutation_gate.cpp`

### Other components

- **Device user**
- **GNSS receiver**
- **Accelerometer**
- **LoRa network**
- **Device flash**
- **BLE client**

## Connections

- Firmware composition → Watchdog: starts and feeds
- Firmware composition → Sensor power control: initializes
- Firmware composition → Radio manager: sets identity
- Firmware composition → Position flow: sets identity
- GNSS acquisition → GNSS receiver: acquires fixes
- GNSS acquisition → Sensor power control: owns sensor rail
- GNSS acquisition → I2C recovery: recovers bus
- Accelerometer sampling → Accelerometer: reads samples
- Accelerometer sampling → I2C recovery: recovers bus
- Activity capture → Accelerometer sampling: requests samples
- Activity capture → Activity quality: uses quality checks
- Activity capture → Activity windows: uses windows
- Position flow → Legacy position mapping: maps fixes
- Position flow → Position packet: encodes positions
- Position flow → Radio manager: submits packets
- Radio manager → LoRa network: transmits and receives
- Radio manager → Network and relay: initializes network
- Network and relay → Relay packet: uses relay format
- BLE client → BLE application transport: exchanges messages
- BLE application transport → BLE application handoff: hands off data
- BLE application transport → Application requests: handles requests
- Device user → Activity capture: starts capture
- Configuration store → Device flash: persists config
- History store → Device flash: persists history
- Security store → Device flash: persists security state
- Configuration store → Flash mutation gate: arbitrates mutations
- History store → Flash mutation gate: arbitrates mutations
- Security store → Flash mutation gate: arbitrates mutations
- Geofence runtime → Position flow: uses position flow