# shenmian/tracker architecture

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

- Interactive diagram: https://gitdiagram.com/shenmian/tracker
- Repository: https://github.com/shenmian/tracker

## Overview

##### Project type and purpose
- This is a Rust-based, terminal UI (TUI) open-source tool called “tracker” for real-time satellite tracking and orbit prediction.
- It fetches Two-Line Element (TLE) data automatically from the internet, propagates orbits using the SGP4 model, and renders a live world-map view plus object details in your terminal.

##### File structure
- Top-level Cargo manifest (Cargo.toml, Cargo.lock) and CI/CD workflows (.github/workflows).
- `src/` is subdivided by responsibility:
- `main.rs` + `app.rs` – application entry point & orchestration
- `config.rs` – read/parse configuration (keymap, data sources, update interval)
- `event.rs` – keyboard/mouse input & event loop (Controller)
- `object.rs`, `satellite_group.rs` – domain models for tracked objects & collections (Model)
- `utils.rs` – shared helpers (parsers, date/time conversions)
- `tui.rs` – core TUI setup (terminal backend, layout)
- `widgets/` – individual UI widgets: world_map, object_information, satellite_groups (View)
- `docs/` holds supplementary architecture and configuration guides.

##### README for additional insights
- Confirms use-cases: display positions/trajectories, detailed info, auto-updating via internet.
- Mentions dependencies (SGP4 model, HTTP update).

##### Main components and relationships
a. Components:
1. Terminal UI Layer (tui.rs + widgets/*)
2. Event Loop / Controller (event.rs + app.rs)
3. Configuration Loader (config.rs)
4. Network Fetcher (part of utils.rs or a submodule)
5. Orbit Propagation Engine (object.rs + satellite_group.rs + SGP4 crate)
6. In-Memory Data Store (Rust structs for TLE and positions)
7. External Services (TLE provider via HTTP)
8. Filesystem (optional config file on disk)
b. Interactions & data flow:
- On launch: Configuration Loader reads defaults + `~/.tracker.toml`.
- Controller schedules periodic “fetch TLE” events → Network Fetcher requests TLE data.
- Parser (utils) transforms raw TLE into Rust domain models.
- Orbit Engine computes current positions & trajectories.
- In-Memory store updated → Event Loop signals UI layer.
- UI Renderer (tui + widgets) reads the store and redraws the terminal.
- User input (keybindings) flows into Controller → may change focus, toggle groups, exit.
c. Architectural patterns:
- MVC-like separation:
- Model = domain modules (`object.rs`, `satellite_group.rs`)
- View = `widgets/` + `tui.rs`
- Controller = `event.rs` + `app.rs`
- Event-driven update loop: decouples data updates from rendering.
- Modular utilities (parsing, config) extracted to `utils.rs` for reuse.
d. Key technologies:
- Rust & Cargo
- TUI library (e.g., tui-rs or crossterm)
- HTTP client crate (reqwest or similar)
- SGP4 crate for orbit propagation
- serde/toml for config parsing

##### Diagramming recommendations
- Controller / Event Loop
- Config Loader
- Network Fetcher
- Orbit Engine
- Data Store
- External TLE Service
- Config Loader → Controller (initialization)
- Controller → Network Fetcher (periodic fetch)
- Network Fetcher → Parser → Data Store
- Data Store → Orbit Engine → Data Store (compute & update)
- Data Store → UI Renderer (on each tick)
- User → Controller (input events)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Main["Main (Entry Point)"]:::compute
    click Main "https://github.com/shenmian/tracker/blob/main/src/main.rs"

    %% Config & Initialization
    subgraph "Config & Initialization"
        ConfigFile[(Config File)]:::persistence
        ConfigLoader["Configuration Loader"]:::io
        click ConfigLoader "https://github.com/shenmian/tracker/blob/main/src/config.rs"
    end

    %% Controller / Event Loop
    subgraph "Controller"
        App["App Orchestration"]:::compute
        click App "https://github.com/shenmian/tracker/blob/main/src/app.rs"
        EventLoop["Event Loop / Input Handler"]:::compute
        click EventLoop "https://github.com/shenmian/tracker/blob/main/src/event.rs"
    end

    %% Network & Parsing
    subgraph "Network & Parsing"
        NetFetcher["Network Fetcher"]:::io
        click NetFetcher "https://github.com/shenmian/tracker/blob/main/src/utils.rs"
        Parser["Parser (TLE → Models)"]:::compute
        click Parser "https://github.com/shenmian/tracker/blob/main/src/utils.rs"
    end

    %% Orbit Engine & Data Store
    subgraph "Orbit Engine & Data Store"
        OrbitEngine["Orbit Propagation Engine"]:::compute
        click OrbitEngine "https://github.com/shenmian/tracker/blob/main/src/object.rs"
        SatelliteGroupModel["Satellite Group Model"]:::compute
        click SatelliteGroupModel "https://github.com/shenmian/tracker/blob/main/src/satellite_group.rs"
        DataStore["In-Memory Data Store"]:::compute
    end

    %% UI Layer
    subgraph "UI Layer"
        TUI["TUI Setup"]:::ui
        click TUI "https://github.com/shenmian/tracker/blob/main/src/tui.rs"
        WorldMap["World Map Widget"]:::ui
        click WorldMap "https://github.com/shenmian/tracker/blob/main/src/widgets/world_map.rs"
        InfoWidget["Object Information Widget"]:::ui
        click InfoWidget "https://github.com/shenmian/tracker/blob/main/src/widgets/object_information.rs"
        GroupWidget["Satellite Groups Widget"]:::ui
        click GroupWidget "https://github.com/shenmian/tracker/blob/main/src/widgets/satellite_groups.rs"
    end

    %% External Entities
    External["External TLE Service"]:::external
    User["User"]:::external

    %% Data Flow
    Main --> ConfigFile
    Main --> ConfigLoader --> App
    Main --> App --> EventLoop
    User --> EventLoop
    EventLoop -->|periodic fetch| NetFetcher
    External -->|HTTP TLE data| NetFetcher
    NetFetcher --> Parser --> DataStore
    DataStore --> OrbitEngine --> DataStore
    DataStore --> SatelliteGroupModel --> OrbitEngine
    EventLoop -->|tick| DataStore --> TUI
    TUI --> WorldMap
    TUI --> InfoWidget
    TUI --> GroupWidget

    %% Styling
    classDef compute fill:#B3CDE3,stroke:#333,stroke-width:1px
    classDef io fill:#CCEBC5,stroke:#333,stroke-width:1px
    classDef ui fill:#FBB4AE,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef persistence fill:#DECBE4,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
