# pfandzelter/optimal-leo-placement architecture

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

- Interactive diagram: https://gitdiagram.com/pfandzelter/optimal-leo-placement
- Repository: https://github.com/pfandzelter/optimal-leo-placement

## Overview

##### Project Type and Purpose
- This is an open-source research tool (Python 3.9+) for QoS-aware resource placement on Low Earth Orbit (LEO) satellite edge computing networks.
- It provides:
- A configurable simulation environment (simulation of satellite constellations and inter‐satellite link distances).
- A placement algorithm for deploying edge services to meet Service Level Objectives (SLOs).
- Post-processing modules for analysis, summarization, and visualization of results.

##### File-Structure Analysis
Top-level scripts & modules:
- config.py – central configuration of simulation parameters, shells, SLOs.
- distances.py – entry point to run constellation simulations and produce ISL distance data.
- placement.py – core placement algorithm (QoS-aware resource placement).
- shells.py – wrapper to execute placement.py over configured shells/SLOs.
- placement-distances.py – analysis script combining placement output with distances to evaluate SLO compliance.
- summarize.py – aggregates experimental results into a CSV.
- graphs.py – generates visualizations from summary CSV.
Subpackage:
- simulation/ – code based on SILLEO-SCNS, including animation.py, constellation.py, simulation.py; used by distances.py.
Other:
- requirements.txt, Dockerfile – environment definitions.
- LICENSE files – MIT for main code, GPL-v3 for simulation subpackage.

##### Key Insights from README
- Heavy use of standalone CLI scripts; no GUI or external service calls beyond Python libraries and optional Docker.

1. Configuration Manager (config.py)
2. Constellation Simulator (simulation/ + distances.py)
3. Placement Engine (placement.py + shells.py)
4. SLO Analysis Module (placement-distances.py)
5. Summarizer (summarize.py)
6. Visualizer (graphs.py)
7. Data Storage (CSV/JSON output files: distances.csv, placement results, results.csv, graph images)
8. Environment Layer (Python runtime + Docker container)
- Configuration → Simulator → distances.csv
- Configuration → Placement Engine + distances.csv → placement_output.json
- Placement Output + distances.csv → SLO Analysis → analysis_output.csv
- analysis_output.csv → Summarizer → results.csv
- results.csv → Visualizer → graph.png / HTML
c. Architectural Patterns:
- Pipeline pattern (discrete stages connected by data artifacts)
- Modular package structure (simulation submodule separated from core logic)
- CLI‐driven orchestration (each script is an entry point)
d. Technologies & Frameworks:
- Python 3.9+, standard libraries, NumPy/Matplotlib (in requirements.txt)
- SILLEO-SCNS codebase integrated under simulation/
- Docker (Dockerfile) for reproducible environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        Config["Configuration Manager"]:::config
    end

    subgraph "Simulation"
        DistScript["distances.py"]:::compute
        subgraph "Simulation Subpackage"
            Anim["animation.py"]:::compute
            Constell["constellation.py"]:::compute
            Sim["simulation.py"]:::compute
        end
    end

    subgraph "Placement Engine"
        Shells["shells.py"]:::compute
        Placement["placement.py"]:::compute
    end

    SLOAnalysis["SLO Analysis Module\n(placement-distances.py)"]:::compute
    Summarizer["Summarizer\n(summarize.py)"]:::compute
    Visualizer["Visualizer\n(graphs.py)"]:::compute

    subgraph "Data Artifacts"
        distancesCSV["distances.csv"]:::data
        placementJSON["placement_output.json"]:::data
        analysisCSV["analysis_output.csv"]:::data
        resultsCSV["results.csv"]:::data
        graphPNG["graph.png / HTML"]:::data
    end

    subgraph "Environment"
        Dock["Dockerfile"]:::env
        Req["requirements.txt"]:::env
    end

    Config -->|"run distances.py"| DistScript
    Config -->|"run shells.py"| Shells
    DistScript -->|"distances.csv"| distancesCSV
    DistScript -->|"imports"| Anim
    DistScript -->|"imports"| Constell
    DistScript -->|"imports"| Sim
    Shells -->|"calls placement.py"| Placement
    distancesCSV -->|"input"| Placement
    Placement -->|"placement_output.json"| placementJSON
    placementJSON -->|"input"| SLOAnalysis
    distancesCSV -->|"input"| SLOAnalysis
    SLOAnalysis -->|"analysis_output.csv"| analysisCSV
    analysisCSV -->|"input"| Summarizer
    Summarizer -->|"results.csv"| resultsCSV
    resultsCSV -->|"input"| Visualizer
    Visualizer -->|"graph.png / HTML"| graphPNG

    Env -.-> Config
    Env -.-> DistScript
    Env -.-> Shells
    Env -.-> Placement
    Env -.-> SLOAnalysis
    Env -.-> Summarizer
    Env -.-> Visualizer

    click Config "https://github.com/pfandzelter/optimal-leo-placement/blob/main/config.py"
    click DistScript "https://github.com/pfandzelter/optimal-leo-placement/blob/main/distances.py"
    click Anim "https://github.com/pfandzelter/optimal-leo-placement/blob/main/simulation/animation.py"
    click Constell "https://github.com/pfandzelter/optimal-leo-placement/blob/main/simulation/constellation.py"
    click Sim "https://github.com/pfandzelter/optimal-leo-placement/blob/main/simulation/simulation.py"
    click Shells "https://github.com/pfandzelter/optimal-leo-placement/blob/main/shells.py"
    click Placement "https://github.com/pfandzelter/optimal-leo-placement/blob/main/placement.py"
    click SLOAnalysis "https://github.com/pfandzelter/optimal-leo-placement/blob/main/placement-distances.py"
    click Summarizer "https://github.com/pfandzelter/optimal-leo-placement/blob/main/summarize.py"
    click Visualizer "https://github.com/pfandzelter/optimal-leo-placement/blob/main/graphs.py"
    click Dock "https://github.com/pfandzelter/optimal-leo-placement/tree/main/Dockerfile"
    click Req "https://github.com/pfandzelter/optimal-leo-placement/blob/main/requirements.txt"

    classDef compute fill:#add8e6,stroke:#333,stroke-width:1px
    classDef data fill:#90ee90,stroke:#333,stroke-width:1px
    classDef config fill:#ffa500,stroke:#333,stroke-width:1px
    classDef env fill:#ffa500,stroke:#333,stroke-width:1px

    class Config config
    class DistScript,Anim,Constell,Sim,Shells,Placement,SLOAnalysis,Summarizer,Visualizer compute
    class distancesCSV,placementJSON,analysisCSV,resultsCSV,graphPNG data
    class Dock,Req env
```
