# asserthq/lorasat architecture

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

- Interactive diagram: https://gitdiagram.com/asserthq/lorasat
- Repository: https://github.com/asserthq/lorasat

## Overview

This workspace implements embedded satellite communications and control software, with MCU firmware, client and ground-station applications, reusable protocol layers, and hardware drivers. A principal workflow is a client communicating over LoRa through link/transport layers to satellite software, which supports command handling, ADCS, telemetry/beacons, and logging. The sampled entry points confirm radio/link/transport construction and several application roles; deeper dispatch and subsystem wiring is not shown, so uncertain calls are omitted. The supplied README describes an unrelated embedded app template and does not document these capabilities.

Main entry points: [`drivers/src/proto_impl/link/mod.rs`](https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/link/mod.rs) (Link protocol), [`drivers/src/proto_impl/transport/mod.rs`](https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/transport/mod.rs) (Transport protocol), [`firmware/src/main.rs`](https://github.com/asserthq/lorasat/blob/master/firmware/src/main.rs) (Satellite firmware), [`sandbox-mcu/src/bin/satellite/main.rs`](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/satellite/main.rs) (Satellite sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_mcu_client["MCU client<br/>[main.rs]"]
  node_client_device["Client device<br/>[main.rs]"]
  node_ground_station["Ground station<br/>[main.rs]"]
  node_pc_sim["PC simulator<br/>[main.rs]"]
  node_firmware_entry["Satellite firmware<br/>[main.rs]"]
  node_sandbox_sat["Satellite sandbox<br/>[main.rs]"]
  node_client_logic["Client behavior<br/>[client_device.rs]"]
  node_gs_task["Ground task<br/>[task.rs]"]
end

subgraph group_protocol["Protocol and Domain"]
  node_core_comm["Comm abstractions<br/>[mod.rs]"]
  node_proto_link["Link protocol<br/>[mod.rs]"]
  node_proto_transport["Transport protocol<br/>[mod.rs]"]
  node_entities["Messages and telemetry<br/>[mod.rs]"]
  node_adcs_domain["ADCS domain<br/>[mod.rs]"]
end

subgraph group_hardware["Hardware Drivers"]
  node_radio["LoRa radio<br/>[mod.rs]"]
  node_flash_store[("Flash ring<br/>[ring.rs]")]
  node_sd_logger[("SD logger<br/>[sdcard_logger.rs]")]
end

subgraph group_satellite["Satellite Subsystems"]
  node_sat_comm["Comm subsystem<br/>[comm.rs]"]
  node_sat_adcs["ADCS subsystem<br/>[adcs.rs]"]
  node_firmware_adcs["Firmware ADCS<br/>[adcs.rs]"]
  node_satellite_logic["Satellite orchestration<br/>[sat.rs]"]
  node_sandbox_tasks["Satellite tasks<br/>[task.rs]"]
  node_logger_core["Core logger<br/>[logger.rs]"]
end

node_client_actor(("Client user"))
node_ground_actor(("Ground operator"))

node_client_actor -->|"uses"| node_mcu_client
node_ground_actor -->|"operates"| node_ground_station
node_mcu_client -->|"initializes"| node_radio
node_mcu_client -->|"constructs"| node_proto_link
node_mcu_client -->|"constructs"| node_proto_transport
node_mcu_client -->|"runs"| node_client_logic
node_client_logic -->|"communicates through"| node_proto_transport
node_client_device -->|"initializes"| node_radio
node_client_device -->|"constructs"| node_proto_link
node_ground_station -->|"constructs"| node_proto_link
node_ground_station -->|"constructs"| node_proto_transport
node_ground_station -->|"runs"| node_gs_task
node_gs_task -->|"communicates through"| node_proto_transport
node_pc_sim -->|"runs"| node_sat_comm
node_firmware_entry -->|"initializes"| node_radio
node_firmware_entry -->|"constructs"| node_proto_link
node_firmware_entry -->|"constructs"| node_proto_transport
node_firmware_entry -->|"constructs"| node_satellite_logic
node_firmware_entry -->|"declares"| node_firmware_adcs
node_sandbox_sat -->|"initializes"| node_radio
node_sandbox_sat -->|"constructs"| node_proto_link
node_sandbox_sat -->|"constructs"| node_proto_transport
node_sandbox_sat -->|"initializes"| node_sd_logger
node_sandbox_sat -->|"runs"| node_sandbox_tasks
node_proto_link -->|"implements"| node_core_comm
node_proto_transport -->|"wraps"| node_proto_link
node_radio -->|"implements PHY"| node_core_comm
node_sat_comm -->|"uses"| node_core_comm
node_satellite_logic -->|"uses"| node_sat_comm
node_satellite_logic -->|"uses"| node_sat_adcs
node_satellite_logic -->|"handles"| node_entities
node_sat_adcs -->|"uses"| node_adcs_domain
node_firmware_adcs -->|"uses"| node_adcs_domain
node_sandbox_tasks -->|"handles"| node_entities
node_sandbox_tasks -->|"logs through"| node_logger_core
node_logger_core -.->|"stores via"| node_flash_store
node_logger_core -.->|"stores via"| node_sd_logger

click node_mcu_client "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/client/main.rs"
click node_client_device "https://github.com/asserthq/lorasat/blob/master/client/src/main.rs"
click node_ground_station "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/gs/main.rs"
click node_pc_sim "https://github.com/asserthq/lorasat/blob/master/sandbox-pc/src/bin/sat/main.rs"
click node_firmware_entry "https://github.com/asserthq/lorasat/blob/master/firmware/src/main.rs"
click node_sandbox_sat "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/satellite/main.rs"
click node_client_logic "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/client/client_device.rs"
click node_gs_task "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/gs/task.rs"
click node_core_comm "https://github.com/asserthq/lorasat/blob/master/core/src/comm/mod.rs"
click node_proto_link "https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/link/mod.rs"
click node_proto_transport "https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/transport/mod.rs"
click node_entities "https://github.com/asserthq/lorasat/blob/master/core/src/entity/mod.rs"
click node_adcs_domain "https://github.com/asserthq/lorasat/blob/master/core/src/adcs/mod.rs"
click node_radio "https://github.com/asserthq/lorasat/blob/master/drivers/src/lora/mod.rs"
click node_flash_store "https://github.com/asserthq/lorasat/blob/master/drivers/src/flash/ring.rs"
click node_sd_logger "https://github.com/asserthq/lorasat/blob/master/drivers/src/sd/sdcard_logger.rs"
click node_sat_comm "https://github.com/asserthq/lorasat/blob/master/subsystems/src/comm/comm.rs"
click node_sat_adcs "https://github.com/asserthq/lorasat/blob/master/subsystems/src/adcs/adcs.rs"
click node_firmware_adcs "https://github.com/asserthq/lorasat/blob/master/firmware/src/adcs.rs"
click node_satellite_logic "https://github.com/asserthq/lorasat/blob/master/firmware/src/sat.rs"
click node_sandbox_tasks "https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/satellite/task.rs"
click node_logger_core "https://github.com/asserthq/lorasat/blob/master/core/src/storage/logger.rs"

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_mcu_client,node_client_device,node_ground_station,node_pc_sim,node_firmware_entry,node_sandbox_sat,node_client_logic,node_gs_task,node_client_actor toneBlue
class node_core_comm,node_proto_link,node_proto_transport,node_entities,node_adcs_domain toneAmber
class node_radio,node_flash_store,node_sd_logger toneMint
class node_sat_comm,node_sat_adcs,node_firmware_adcs,node_satellite_logic,node_sandbox_tasks,node_logger_core toneRose
class node_ground_actor toneIndigo
```

## Components

### Applications

- [MCU client](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/client/main.rs): `sandbox-mcu/src/bin/client/main.rs`
- [Client device](https://github.com/asserthq/lorasat/blob/master/client/src/main.rs): `client/src/main.rs`
- [Ground station](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/gs/main.rs): `sandbox-mcu/src/bin/gs/main.rs`
- [PC simulator](https://github.com/asserthq/lorasat/blob/master/sandbox-pc/src/bin/sat/main.rs): `sandbox-pc/src/bin/sat/main.rs`
- [Satellite firmware](https://github.com/asserthq/lorasat/blob/master/firmware/src/main.rs): `firmware/src/main.rs`
- [Satellite sandbox](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/satellite/main.rs): `sandbox-mcu/src/bin/satellite/main.rs`
- [Client behavior](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/client/client_device.rs): `sandbox-mcu/src/bin/client/client_device.rs`
- [Ground task](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/gs/task.rs): `sandbox-mcu/src/bin/gs/task.rs`

### Protocol and Domain

- [Comm abstractions](https://github.com/asserthq/lorasat/blob/master/core/src/comm/mod.rs): `core/src/comm/mod.rs`
- [Link protocol](https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/link/mod.rs): `drivers/src/proto_impl/link/mod.rs`
- [Transport protocol](https://github.com/asserthq/lorasat/blob/master/drivers/src/proto_impl/transport/mod.rs): `drivers/src/proto_impl/transport/mod.rs`
- [Messages and telemetry](https://github.com/asserthq/lorasat/blob/master/core/src/entity/mod.rs): `core/src/entity/mod.rs`
- [ADCS domain](https://github.com/asserthq/lorasat/blob/master/core/src/adcs/mod.rs): `core/src/adcs/mod.rs`

### Hardware Drivers

- [LoRa radio](https://github.com/asserthq/lorasat/blob/master/drivers/src/lora/mod.rs): `drivers/src/lora/mod.rs`
- [Flash ring](https://github.com/asserthq/lorasat/blob/master/drivers/src/flash/ring.rs): `drivers/src/flash/ring.rs`
- [SD logger](https://github.com/asserthq/lorasat/blob/master/drivers/src/sd/sdcard_logger.rs): `drivers/src/sd/sdcard_logger.rs`

### Satellite Subsystems

- [Comm subsystem](https://github.com/asserthq/lorasat/blob/master/subsystems/src/comm/comm.rs): `subsystems/src/comm/comm.rs`
- [ADCS subsystem](https://github.com/asserthq/lorasat/blob/master/subsystems/src/adcs/adcs.rs): `subsystems/src/adcs/adcs.rs`
- [Firmware ADCS](https://github.com/asserthq/lorasat/blob/master/firmware/src/adcs.rs): `firmware/src/adcs.rs`
- [Satellite orchestration](https://github.com/asserthq/lorasat/blob/master/firmware/src/sat.rs): `firmware/src/sat.rs`
- [Satellite tasks](https://github.com/asserthq/lorasat/blob/master/sandbox-mcu/src/bin/satellite/task.rs): `sandbox-mcu/src/bin/satellite/task.rs`
- [Core logger](https://github.com/asserthq/lorasat/blob/master/core/src/storage/logger.rs): `core/src/storage/logger.rs`

### Other components

- **Client user**
- **Ground operator**

## Connections

- Client user → MCU client: uses
- Ground operator → Ground station: operates
- MCU client → LoRa radio: initializes
- MCU client → Link protocol: constructs
- MCU client → Transport protocol: constructs
- MCU client → Client behavior: runs
- Client behavior → Transport protocol: communicates through
- Client device → LoRa radio: initializes
- Client device → Link protocol: constructs
- Ground station → Link protocol: constructs
- Ground station → Transport protocol: constructs
- Ground station → Ground task: runs
- Ground task → Transport protocol: communicates through
- PC simulator → Comm subsystem: runs
- Satellite firmware → LoRa radio: initializes
- Satellite firmware → Link protocol: constructs
- Satellite firmware → Transport protocol: constructs
- Satellite firmware → Satellite orchestration: constructs
- Satellite firmware → Firmware ADCS: declares
- Satellite sandbox → LoRa radio: initializes
- Satellite sandbox → Link protocol: constructs
- Satellite sandbox → Transport protocol: constructs
- Satellite sandbox → SD logger: initializes
- Satellite sandbox → Satellite tasks: runs
- Link protocol → Comm abstractions: implements
- Transport protocol → Link protocol: wraps
- LoRa radio → Comm abstractions: implements PHY
- Comm subsystem → Comm abstractions: uses
- Satellite orchestration → Comm subsystem: uses
- Satellite orchestration → ADCS subsystem: uses
- Satellite orchestration → Messages and telemetry: handles
- ADCS subsystem → ADCS domain: uses
- Firmware ADCS → ADCS domain: uses
- Satellite tasks → Messages and telemetry: handles
- Satellite tasks → Core logger: logs through
- Core logger → Flash ring: stores via
- Core logger → SD logger: stores via