# trevor16gordon/flatsat architecture

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

- Interactive diagram: https://gitdiagram.com/trevor16gordon/flatsat
- Repository: https://github.com/trevor16gordon/flatsat

## Overview

#### Purpose and deployment target
`flatsat` is a distributed flat-satellite testbed: Python flight software runs on a Jetson Orin Nano with a PREEMPT_RT kernel, connects to real or simulated devices, and supports a ground physics simulator plus two ADALM-Pluto SDRs. Its central demonstration is telemetry-driven ML-policy retraining, RF uplink during contacts, A/B-slot activation, and rollback. The deployable package is `flatsat/`; systemd units define the flight composition in `units/generated/flatsat.target` and `units/flatsat-router.service`.

#### Entry points and process composition
Applications are independently runnable daemons rather than a monolithic service. The principal operational processes are the sensor and actuator daemons, ADCS loop, FDIR, mode manager, telemetry recorder, link service, and uplink service:
- `flatsat/apps/sensor_daemon.py`
- `flatsat/apps/control_loop.py`
- `flatsat/apps/actuator_daemon.py`
- `flatsat/apps/fdir.py`
- `flatsat/apps/link_service.py`
- `flatsat/apps/uplink_service.py`
- `flatsat/sim/run_mission.py`

#### Core contracts, runtime bus, and configuration
The internal architectural boundary is typed protobuf messages over a shared runtime/bus, plus registries that resolve config-selected implementations. Common message contracts cover ADCS, HAL, health, telemetry, link, mode, and uplink domains:
- `flatsat/core/bus.py`
- `flatsat/core/registry.py`
- `flatsat/core/rt.py`
- `flatsat/msgs/adcs.proto`
- `flatsat/msgs/hal.proto`
- `flatsat/vehicle.proto`

Vehicle configuration declares physical properties, devices, estimators, controllers, and objectives. Device, mission, orbit, and vehicle files make system composition data-driven, allowing sim/bench/hardware substitutions without changing downstream loops:
- `config/vehicles/flatsat_v1.txtpb`
- `config/devices/imu0.txtpb`
- `config/missions/detumble_3d.txtpb`

#### Hardware abstraction and simulation
Sensor and actuator interfaces isolate applications from physical, synthetic, and Basilisk-backed implementations. Drivers publish the same typed messages regardless of source. The simulator constructs the plant and scenario from the same vehicle-oriented configuration boundary used by flight software:
- `flatsat/hardware/sensor.py`
- `flatsat/hardware/actuator.py`
- `flatsat/hardware/drivers/basilisk_imu.py`
- `flatsat/sim/plant.py`
- `flatsat/sim/basilisk_hil.py`
- `flatsat/sim/scenario.py`

#### ADCS control pipeline
The control loop consumes sensor state, applies an estimator and guidance/controller selection, then emits actuator commands. Available attitude-control implementations include B-dot detumble, momentum dumping, pointing, PID/rate damping, and an ML policy; these are selected through controller configuration rather than separate loops:
- `flatsat/control/attitude/controller.py`
- `flatsat/control/attitude/guidance.py`
- `flatsat/control/attitude/estimators/triad.py`
- `flatsat/control/attitude/controllers/bdot.py`
- `flatsat/control/attitude/controllers/ml_policy.py`

#### Modes, health, and fault containment
Mode management governs operational-state transitions and accepts requests from system actors. FDIR forms a sense-decide-act boundary: health rules evaluate valid/invalid telemetry, an arbiter groups/common-causes faults, and responses can restart, reconfigure, or request Safe mode. Safe behavior is intended to remain in the base flight release rather than be hot-swapped:
- `flatsat/mode/machine.py`
- `flatsat/mode/manager.py`
- `flatsat/control/health/rules.py`
- `flatsat/control/health/arbiter.py`
- `flatsat/core/health.py`

#### Communications, uplink, and telemetry lifecycle
The RF stack is store-and-forward and contact-scheduled rather than middleware tunneling. It layers slot scheduling, CCSDS framing/randomization/FEC, a swappable PHY/modem contract, and uplink handling; supported PHYs include loopback, KISS, and Pluto GMSK. Telemetry is recorded/exported with mission logs, providing the source material for analysis and ML retraining:
- `flatsat/comms/link.py`
- `flatsat/comms/slots.py`
- `flatsat/comms/framing/ccsds.py`
- `flatsat/comms/phy/pluto_gmsk.py`
- `flatsat/comms/uplink.py`
- `flatsat/telemetry/recorder.py`
- `flatsat/telemetry/mission_log.py`

Main entry points: [`flatsat/core/bus.py`](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/core/bus.py) (Typed runtime bus), [`units/generated/flatsat.target`](https://github.com/trevor16gordon/flatsat/blob/main/units/generated/flatsat.target) (systemd flight composition), [`flatsat/apps/control_loop.py`](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/control_loop.py) (ADCS control loop), [`flatsat/apps/fdir.py`](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/fdir.py) (FDIR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_systemd["systemd flight composition<br/>systemd units<br/>[flatsat.target]"]
end

subgraph group_runtime["Flight Runtime"]
  node_bus["Typed runtime bus<br/>protobuf bus<br/>[bus.py]"]
  node_messages["Vehicle message contracts<br/>protobuf schemas<br/>[adcs.proto]"]
  node_registry["Implementation registry<br/>runtime registry<br/>[registry.py]"]
  node_vehicle_config["Vehicle composition<br/>vehicle config<br/>[flatsat_v1.txtpb]"]
  node_sensor_daemon["Sensor daemon<br/>flight daemon<br/>[sensor_daemon.py]"]
  node_actuator_daemon["Actuator daemon<br/>flight daemon<br/>[actuator_daemon.py]"]
  node_hardware_interfaces["Sensor and actuator HAL<br/>hardware abstraction<br/>[sensor.py]"]
end

subgraph group_adcs["ADCS &amp; Safety"]
  node_control_loop["ADCS control loop<br/>flight daemon<br/>[control_loop.py]"]
  node_adcs_algorithms["Estimator, guidance &amp; controllers<br/>ADCS implementations<br/>[controller.py]"]
  node_fdir["FDIR<br/>flight daemon<br/>[fdir.py]"]
  node_health_logic["Health rules and arbiter<br/>fault policy<br/>[rules.py]"]
  node_mode_manager["Mode manager<br/>flight daemon<br/>[manager.py]"]
end

subgraph group_comms["Comms &amp; Telemetry"]
  node_link_service["Link service<br/>flight daemon<br/>[link_service.py]"]
  node_rf_stack["Scheduled CCSDS RF stack<br/>comms pipeline<br/>[link.py]"]
  node_uplink_service["Uplink service<br/>flight daemon<br/>[uplink_service.py]"]
  node_telemetry[("Telemetry recorder and logs<br/>telemetry lifecycle<br/>[recorder.py]")]
end

subgraph group_simulation["Simulation"]
  node_mission_simulator["Mission simulator<br/>simulation entry point<br/>[run_mission.py]"]
  node_sim_plant["Plant and scenario<br/>Basilisk simulation<br/>[plant.py]"]
end

node_systemd -->|"starts"| node_sensor_daemon
node_systemd -->|"starts"| node_control_loop
node_systemd -->|"starts"| node_actuator_daemon
node_systemd -->|"starts"| node_fdir
node_systemd -->|"starts"| node_link_service
node_systemd -->|"starts"| node_uplink_service
node_messages -->|"defines payloads"| node_bus
node_vehicle_config -->|"selects implementations"| node_registry
node_registry -->|"resolves devices"| node_hardware_interfaces
node_registry -->|"resolves algorithms"| node_adcs_algorithms
node_hardware_interfaces -->|"provides sensors"| node_sensor_daemon
node_sensor_daemon -->|"publishes sensor state"| node_bus
node_bus -->|"delivers state"| node_control_loop
node_control_loop -->|"uses"| node_adcs_algorithms
node_control_loop -->|"publishes commands"| node_bus
node_bus -->|"delivers commands"| node_actuator_daemon
node_actuator_daemon -->|"drives actuators"| node_hardware_interfaces
node_bus -->|"delivers health telemetry"| node_fdir
node_fdir -->|"evaluates"| node_health_logic
node_fdir -->|"requests Safe or recovery"| node_mode_manager
node_mode_manager -->|"publishes mode"| node_bus
node_bus -->|"records telemetry"| node_telemetry
node_link_service -->|"operates"| node_rf_stack
node_rf_stack -->|"delivers uplink frames"| node_uplink_service
node_uplink_service -->|"publishes commands"| node_bus
node_mission_simulator -->|"builds"| node_sim_plant
node_vehicle_config -->|"configures"| node_mission_simulator
node_sim_plant -.->|"substitutes synthetic devices"| node_hardware_interfaces
node_telemetry -.->|"supplies retraining data"| node_adcs_algorithms

click node_systemd "https://github.com/trevor16gordon/flatsat/blob/main/units/generated/flatsat.target"
click node_bus "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/core/bus.py"
click node_messages "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/msgs/adcs.proto"
click node_registry "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/core/registry.py"
click node_vehicle_config "https://github.com/trevor16gordon/flatsat/blob/main/config/vehicles/flatsat_v1.txtpb"
click node_sensor_daemon "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/sensor_daemon.py"
click node_actuator_daemon "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/actuator_daemon.py"
click node_hardware_interfaces "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/hardware/sensor.py"
click node_control_loop "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/control_loop.py"
click node_adcs_algorithms "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/control/attitude/controller.py"
click node_fdir "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/fdir.py"
click node_health_logic "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/control/health/rules.py"
click node_mode_manager "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/mode/manager.py"
click node_link_service "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/link_service.py"
click node_rf_stack "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/comms/link.py"
click node_uplink_service "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/uplink_service.py"
click node_telemetry "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/telemetry/recorder.py"
click node_mission_simulator "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/sim/run_mission.py"
click node_sim_plant "https://github.com/trevor16gordon/flatsat/blob/main/flatsat/sim/plant.py"

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_systemd toneBlue
class node_bus,node_messages,node_registry,node_vehicle_config,node_sensor_daemon,node_actuator_daemon,node_hardware_interfaces toneAmber
class node_control_loop,node_adcs_algorithms,node_fdir,node_health_logic,node_mode_manager toneMint
class node_link_service,node_rf_stack,node_uplink_service,node_telemetry toneRose
class node_mission_simulator,node_sim_plant toneIndigo
```

## Components

### Deployment

- [systemd flight composition](https://github.com/trevor16gordon/flatsat/blob/main/units/generated/flatsat.target): systemd units · Starts the independently runnable flight daemons. · `units/generated/flatsat.target`

### Flight Runtime

- [Typed runtime bus](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/core/bus.py): protobuf bus · Shared message boundary between flight processes. · `flatsat/core/bus.py`
- [Vehicle message contracts](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/msgs/adcs.proto): protobuf schemas · Typed contracts for ADCS, HAL, health, telemetry, link, mode, and uplink. · `flatsat/msgs/adcs.proto`
- [Implementation registry](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/core/registry.py): runtime registry · Resolves configuration-selected devices and algorithms. · `flatsat/core/registry.py`
- [Vehicle composition](https://github.com/trevor16gordon/flatsat/blob/main/config/vehicles/flatsat_v1.txtpb): vehicle config · Declares physical properties, devices, estimators, controllers, and objectives. · `config/vehicles/flatsat_v1.txtpb`
- [Sensor daemon](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/sensor_daemon.py): flight daemon · `flatsat/apps/sensor_daemon.py`
- [Actuator daemon](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/actuator_daemon.py): flight daemon · `flatsat/apps/actuator_daemon.py`
- [Sensor and actuator HAL](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/hardware/sensor.py): hardware abstraction · Isolates flight applications from physical and synthetic devices. · `flatsat/hardware/sensor.py`

### ADCS & Safety

- [ADCS control loop](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/control_loop.py): flight daemon · Estimates state, selects guidance/controller, and emits commands. · `flatsat/apps/control_loop.py`
- [Estimator, guidance & controllers](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/control/attitude/controller.py): ADCS implementations · Configuration selects TRIAD, B-dot, pointing, PID/rate damping, or ML policy. · `flatsat/control/attitude/controller.py`
- [FDIR](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/fdir.py): flight daemon · Evaluates health, groups faults, and triggers containment actions. · `flatsat/apps/fdir.py`
- [Health rules and arbiter](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/control/health/rules.py): fault policy · Turns telemetry validity and common-cause faults into responses. · `flatsat/control/health/rules.py`
- [Mode manager](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/mode/manager.py): flight daemon · Governs operational transitions including Safe mode. · `flatsat/mode/manager.py`

### Comms & Telemetry

- [Link service](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/link_service.py): flight daemon · Runs store-and-forward contact-scheduled RF transport. · `flatsat/apps/link_service.py`
- [Scheduled CCSDS RF stack](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/comms/link.py): comms pipeline · Slots, framing/FEC, and swappable loopback, KISS, or Pluto GMSK PHY. · `flatsat/comms/link.py`
- [Uplink service](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/apps/uplink_service.py): flight daemon · Receives and handles commands during RF contacts. · `flatsat/apps/uplink_service.py`
- [Telemetry recorder and logs](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/telemetry/recorder.py): telemetry lifecycle · Records and exports mission telemetry for analysis and ML retraining. · `flatsat/telemetry/recorder.py`

### Simulation

- [Mission simulator](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/sim/run_mission.py): simulation entry point · Runs ground physics scenarios against the shared vehicle boundary. · `flatsat/sim/run_mission.py`
- [Plant and scenario](https://github.com/trevor16gordon/flatsat/blob/main/flatsat/sim/plant.py): Basilisk simulation · Constructs synthetic or Basilisk-backed spacecraft dynamics and scenario. · `flatsat/sim/plant.py`

## Connections

- systemd flight composition → Sensor daemon: starts
- systemd flight composition → ADCS control loop: starts
- systemd flight composition → Actuator daemon: starts
- systemd flight composition → FDIR: starts
- systemd flight composition → Link service: starts
- systemd flight composition → Uplink service: starts
- Vehicle message contracts → Typed runtime bus: defines payloads
- Vehicle composition → Implementation registry: selects implementations
- Implementation registry → Sensor and actuator HAL: resolves devices
- Implementation registry → Estimator, guidance & controllers: resolves algorithms
- Sensor and actuator HAL → Sensor daemon: provides sensors
- Sensor daemon → Typed runtime bus: publishes sensor state
- Typed runtime bus → ADCS control loop: delivers state
- ADCS control loop → Estimator, guidance & controllers: uses
- ADCS control loop → Typed runtime bus: publishes commands
- Typed runtime bus → Actuator daemon: delivers commands
- Actuator daemon → Sensor and actuator HAL: drives actuators
- Typed runtime bus → FDIR: delivers health telemetry
- FDIR → Health rules and arbiter: evaluates
- FDIR → Mode manager: requests Safe or recovery
- Mode manager → Typed runtime bus: publishes mode
- Typed runtime bus → Telemetry recorder and logs: records telemetry
- Link service → Scheduled CCSDS RF stack: operates
- Scheduled CCSDS RF stack → Uplink service: delivers uplink frames
- Uplink service → Typed runtime bus: publishes commands
- Mission simulator → Plant and scenario: builds
- Vehicle composition → Mission simulator: configures
- Plant and scenario → Sensor and actuator HAL: substitutes synthetic devices
- Telemetry recorder and logs → Estimator, guidance & controllers: supplies retraining data