# mwasifanwar/spacesense architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/spacesense
- Repository: https://github.com/mwasifanwar/spacesense

## Overview

##### Project type and purpose
- This is an AI-driven backend service named “spacesense” that processes telescope images to detect and track space debris, predicts potential collisions via orbital mechanics, and optimizes satellite trajectories using reinforcement learning. It exposes a server/API entry point (main.py → src/api/server.py) and organizes processing into modular subpackages.

##### File structure
- Top-level:
- main.py and config.yaml: application entrypoint and global configuration
- requirements.txt: Python dependencies
- src/api: HTTP or RPC server layer
- src/data_processing: ingestion and pre-processing (loading raw imagery, basic transforms)
- src/computer_vision: specialized CV stages (debris_detector.py → tracker.py)
- src/orbital_mechanics: physics-based collision predictor and propagator
- src/reinforcement_learning: agent/environment definitions and training loop
- src/utils/config.py: central config loader
- tests: unit tests for detector and orbital modules

##### README
- Confirms the multi-stage pipeline: ingest images → detect & track debris → predict collisions → optimize trajectories. No front-end; entirely backend/API with AI/ML & physics components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "API Layer"
        A_main["main.py"]:::api-layer
        A_server["server.py"]:::api-layer
    end
    click A_main "https://github.com/mwasifanwar/spacesense/blob/main/main.py"
    click A_server "https://github.com/mwasifanwar/spacesense/blob/main/src/api/server.py"

    subgraph "Configuration Manager"
        Config_yaml["config.yaml"]:::config-storage
        Config_py["config.py"]:::config-storage
    end
    click Config_yaml "https://github.com/mwasifanwar/spacesense/blob/main/config.yaml"
    click Config_py "https://github.com/mwasifanwar/spacesense/blob/main/src/utils/config.py"

    subgraph "Data Ingestion & Pre-Processing"
        Data_loader["data_loader.py"]:::data-cv
        Image_processor["image_processor.py"]:::data-cv
    end
    click Data_loader "https://github.com/mwasifanwar/spacesense/blob/main/src/data_processing/data_loader.py"
    click Image_processor "https://github.com/mwasifanwar/spacesense/blob/main/src/data_processing/image_processor.py"

    subgraph "Computer Vision Engine"
        Debris_detector["debris_detector.py"]:::data-cv
        Tracker["tracker.py"]:::data-cv
    end
    click Debris_detector "https://github.com/mwasifanwar/spacesense/blob/main/src/computer_vision/debris_detector.py"
    click Tracker "https://github.com/mwasifanwar/spacesense/blob/main/src/computer_vision/tracker.py"

    subgraph "Orbital Mechanics Engine"
        Collision_predictor["collision_predictor.py"]:::physics
        Propagator["propagator.py"]:::physics
    end
    click Collision_predictor "https://github.com/mwasifanwar/spacesense/blob/main/src/orbital_mechanics/collision_predictor.py"
    click Propagator "https://github.com/mwasifanwar/spacesense/blob/main/src/orbital_mechanics/propagator.py"

    subgraph "Reinforcement Learning Module"
        Environment["environment.py"]:::rl
        Agent["agent.py"]:::rl
        Trainer["trainer.py"]:::rl
    end
    click Environment "https://github.com/mwasifanwar/spacesense/blob/main/src/reinforcement_learning/environment.py"
    click Agent "https://github.com/mwasifanwar/spacesense/blob/main/src/reinforcement_learning/agent.py"
    click Trainer "https://github.com/mwasifanwar/spacesense/blob/main/src/reinforcement_learning/trainer.py"

    Storage["Message Queue / Database"]:::config-storage
    External["Telescope Imagery Source"]:::external

    %% Data Flow - Inference Pipeline
    External -->|"raw images"| Data_loader
    Data_loader -->|"raw frames"| Image_processor
    Image_processor -->|"processed frames"| Debris_detector
    Debris_detector -->|"detections"| Tracker
    Tracker -->|"tracked objects"| Collision_predictor
    Collision_predictor -->|"collision data"| Propagator
    Propagator -->|"collision risk"| A_server
    A_server -->|"response"| Storage

    %% Training Pipeline
    A_server -->|"train request"| Trainer
    Trainer -->|"simulation episodes"| Environment
    Environment -->|"state data"| Collision_predictor
    Collision_predictor -->|"orbit feedback"| Agent
    Agent -->|"actions"| Environment
    Trainer -->|"optimized policy"| Storage

    %% Control & Configuration
    A_main --> A_server
    Config_py --> Data_loader
    Config_py --> Image_processor
    Config_py --> Debris_detector
    Config_py --> Tracker
    Config_py --> Collision_predictor
    Config_py --> Propagator
    Config_py --> Environment
    Config_py --> Agent
    Config_py --> Trainer

    %% API to Pipeline
    A_server -->|"process image"| Data_loader

    classDef api-layer fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef data-cv fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef physics fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef rl fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef config-storage fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
```
