# ltstrange/satellite-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/ltstrange/satellite-simulator
- Repository: https://github.com/ltstrange/satellite-simulator

## Overview

##### Project Type and Purpose
- This is a Rust-based satellite simulator application built on the Bevy game/graphics engine.
- It is organized as a Cargo workspace with three crates:
- brp_packages: a library crate (likely shared utilities or data packages)
- orbiter: a library crate handling orbital mechanics calculations and tests
- simulator: the main executable crate that ties together configuration, data I/O, the simulation core, networking, and 3D visualization

##### High-Level Architectural Components
a. Configuration & Data Input
- Reads `config.toml` for simulation parameters (dataset paths, network port, display toggles, simulation speed, link thresholds).
- Loads JSON constellation files (e.g. `starlink.json`, `Iridium.json`) into in-memory data structures.
b. Core Simulation Engine
- Core modules under `simulator/src/core/`:
- orbit.rs: propagates satellite positions using orbital mechanics
- satellite.rs: holds satellite state (position, velocity, energy, tasks)
- communication.rs: models link establishment & tear-down based on distance
- manager.rs: orchestrates update loop, invokes orbit and communication each tick
- Uses utilities from orbiter and brp_packages crates for calculations.
c. I/O & Network Interface
- `simulator/src/io/`: abstracts reading/writing data, exposing a network interface (listening on configured port) for external clients (e.g., Python bindings).
- Allows real-time retrieval of simulation state.
d. Visualization Layer (UI)
- Built with Bevy ECS under `simulator/src/ui/`:
- display_toggle.rs & fps.rs: UI controls & status overlays
- widgets/*: interactive buttons and toggles for orbit paths and link display
- Renders satellites, orbits, and dynamic communication lines in 3D.
- Camera controls in `camera.rs`.
e. Entry Point
- `simulator/src/main.rs` initializes Bevy app, loads config & data, registers systems for core simulation, I/O server, and UI rendering.

##### Relationships & Data Flow
- On startup: main → config module → read config.toml → load JSON data → pass to core manager
- Per frame (64 Hz):
- Core manager updates all satellite orbits (calls orbital library)
- Communication module checks/updates ISLs
- Simulation state is stored/updated in ECS resources
- UI systems query ECS resources to render satellites, orbits, and link lines
- I/O/server system packages state snapshots and sends over TCP/UDP to external clients
- External: JSON files and config toml supply initial data; Python client (future) connects to network port.

##### Architectural Patterns & Design Principles
- Modular library crates (orbiter, brp_packages) for reusability and separation of concerns
- Bevy’s ECS (Entity-Component-System) pattern for simulation state and rendering decoupling
- Clear separation: Configuration → Core Simulation → Visualization → Networking
- Data-driven: JSON and TOML files define orbits and simulation parameters
- Single executable orchestrator (simulator) with pluggable modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Data & Clients"
        direction TB
        ConfigTOML["config.toml"]:::external
        Iridium["Iridium.json"]:::external
        IridiumNext["IridiumNext.json"]:::external
        FENGYUN["FENGYUN.json"]:::external
        Starlink["starlink.json"]:::external
        Client["External Python Client"]:::external
    end

    subgraph "Libraries"
        direction TB
        BRP["brp_packages"]:::lib
        ORB["orbiter"]:::lib
    end

    subgraph "Simulator Executable"
        direction TB
        Cargo["Cargo.toml"]:::app
        Entry["main.rs\n(Bevy App Init)"]:::app
        Config["Configuration Loader"]:::app
        JSONStore["JSON Data Store"]:::app
        subgraph "Core Simulation Engine"
            direction TB
            CoreMod["mod.rs"]:::app
            Orbit["orbit.rs"]:::app
            Satellite["satellite.rs"]:::app
            Comm["communication.rs"]:::app
            Manager["manager.rs"]:::app
        end
        IO["I/O & Network Server"]:::app
        subgraph "Visualization & UI"
            direction TB
            UIMod["ui/mod.rs"]:::app
            Camera["camera.rs"]:::app
            Display["display_toggle.rs"]:::app
            FPS["fps.rs"]:::app
            subgraph "Widgets"
                direction TB
                WidgetsMod["widgets/mod.rs"]:::app
                Button["button.rs"]:::app
                Toggle["toggle.rs"]:::app
            end
        end
        Utils["utils.rs"]:::app
    end

    %% Data & Control Flows
    ConfigTOML -->|reads config| Config
    Iridium -->|loads JSON| JSONStore
    IridiumNext -->|loads JSON| JSONStore
    FENGYUN -->|loads JSON| JSONStore
    Starlink -->|loads JSON| JSONStore

    Config -->|initializes| Entry
    JSONStore -->|provides data| Manager
    Config -->|passes params| Manager

    Entry -->|uses| BRP
    Entry -->|uses| ORB

    Entry -->|starts| Manager
    Manager -->|calls| Orbit
    Manager -->|updates| Satellite
    Manager -->|manages links| Comm
    Manager -->|writes| Utils

    Orbit -->|uses| ORB
    Comm -->|uses| BRP

    Manager -->|updates ECS| Display
    Manager -->|updates ECS| Camera
    Manager -->|updates ECS| FPS
    Manager -->|updates ECS| WidgetsMod

    Manager -->|packages state| IO
    IO -->|sends snapshots| Client

    %% Click Events
    click BRP "https://github.com/ltstrange/satellite-simulator/blob/main/brp_packages/src/lib.rs"
    click ORB "https://github.com/ltstrange/satellite-simulator/blob/main/orbiter/src/lib.rs"
    click Cargo "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/Cargo.toml"
    click Entry "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/main.rs"
    click Config "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/config.rs"
    click ConfigTOML "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/config.toml"
    click Iridium "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/Iridium.json"
    click IridiumNext "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/IridiumNext.json"
    click FENGYUN "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/FENGYUN.json"
    click Starlink "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/starlink.json"
    click CoreMod "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/core/mod.rs"
    click Orbit "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/core/orbit.rs"
    click Satellite "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/core/satellite.rs"
    click Comm "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/core/communication.rs"
    click Manager "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/core/manager.rs"
    click IO "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/io/mod.rs"
    click UIMod "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/mod.rs"
    click Camera "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/camera.rs"
    click Display "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/display_toggle.rs"
    click FPS "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/fps.rs"
    click WidgetsMod "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/widgets/mod.rs"
    click Button "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/widgets/button.rs"
    click Toggle "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/ui/widgets/toggle.rs"
    click Utils "https://github.com/ltstrange/satellite-simulator/blob/main/simulator/src/utils.rs"

    %% Styles
    classDef lib fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef app fill:#AED6F1,stroke:#1B4F72,stroke-width:1px
    classDef external fill:#ABEBC6,stroke:#196F3D,stroke-width:1px
    class BRP,ORB lib
    class Cargo,Entry,Config,JSONStore,CoreMod,Orbit,Satellite,Comm,Manager,IO,UIMod,Camera,Display,FPS,WidgetsMod,Button,Toggle,Utils app
    class ConfigTOML,Iridium,IridiumNext,FENGYUN,Starlink,Client external
```
