🛰️ ACM-Orbital

Autonomous Constellation Manager

J2-Perturbed Orbital Propagation · KDTree Conjunction Assessment · Real-Time Canvas Visualization

---

A high-performance backend system acting as the centralized brain for 50+ satellites navigating 10,000+ debris objects. Real-time collision prediction, autonomous evasion maneuvers, fuel-optimal trajectory planning, and a 60FPS Canvas visualization dashboard — all in a single Docker container.

---

🏗️ Architecture

graph TD
    subgraph "Layer 3 — Frontend"
        A[React + Three.js Dashboard]
    end

    subgraph "Layer 2 — API"
        B[FastAPI + Uvicorn]
    end

    subgraph "Layer 1 — Physics Engine"
        C[SimulationEngine]
        D[OrbitalPropagator]
        E[ConjunctionAssessor]
        F[ManeuverPlanner]
        G[FuelTracker]
    end

    A -- "HTTP/JSON (polling)" --> B
    B -- "Python calls" --> C
    C --> D
    C --> E
    C --> F
    C --> G

Loading

Layer	Technology	Responsibility
Physics Engine	Python + NumPy + SciPy (DOP853)	Orbital propagation, KDTree conjunction detection, RTN maneuver planning, Tsiolkovsky fuel tracking
API Layer	FastAPI + Pydantic + orjson	REST endpoints, request validation, schema translation, structured logging
Frontend	React 18 + Canvas API + Zustand	60FPS 2D ground track, bullseye plot, fuel heatmap, delta-v chart, maneuver timeline

---

🚀 Quick Start

Docker (Production — Recommended)

# Build and run the container
docker build -t acm-orbital .
docker run -p 8000:8000 acm-orbital

# Verify
curl http://localhost:8000/health

Docker Compose (Development)

docker compose up --build

Manual (Development)

# Backend
cd backend
python -m pip install -r requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Frontend (separate terminal)
cd frontend
npm ci
npm run dev

---

📡 API Reference

Method	Endpoint	Description
POST	/api/telemetry	Ingest satellite & debris state vectors
POST	/api/maneuver/schedule	Schedule evasion/recovery burn sequences
POST	/api/simulate/step	Advance simulation clock by N seconds
GET	/api/visualization/snapshot	Current state snapshot for frontend rendering
GET	/health	Container health check

💻 cURL Examples

1. Ingest Telemetry

curl -X POST "http://localhost:8000/api/telemetry" \
     -H "Content-Type: application/json" \
     -d '{"timestamp": "2026-03-01T12:00:00Z", "objects": [{"id": "SAT-01", "type": "SATELLITE", "mass_kg": 500, "r": {"x": 7000, "y": 0, "z": 0}, "v": {"x": 0, "y": 7.5, "z": 0}}]}'

2. Advance Simulation by 1 Hour

curl -X POST "http://localhost:8000/api/simulate/step" \
     -H "Content-Type: application/json" \
     -d '{"step_seconds": 3600}'

3. Get Dashboard Snapshot

curl -X GET "http://localhost:8000/api/visualization/snapshot"

---

📂 Project Structure

acm-orbital/
├── Dockerfile                  ← Single-container build (ubuntu:22.04)
├── docker-compose.yml          ← Local dev convenience
├── backend/
│   ├── main.py                 ← FastAPI app factory + lifespan
│   ├── config.py               ← Physical constants (FROZEN)
│   ├── schemas.py              ← Pydantic API contracts (FROZEN)
│   ├── api/                    ← REST route handlers
│   ├── engine/                 ← Pure-math physics engine
│   ├── data/                   ← Ground station CSV
│   └── tests/                  ← Pytest suite
├── frontend/
│   ├── src/
│   │   ├── components/         ← 5 visualization modules
│   │   ├── workers/            ← SGP4 Web Worker
│   │   └── utils/              ← Coordinate transforms, API wrapper
│   └── public/                 ← Earth textures
└── docs/                       ← Technical report (LaTeX)

---

🔬 Core Algorithms

• Orbital Propagation: J2-perturbed two-body dynamics via scipy.integrate.solve_ivp (DOP853, 8th-order adaptive)
• Conjunction Assessment: 4-stage filter cascade — Altitude Band → KDTree Spatial Index → Brent TCA Refinement → CDM Emission
• Maneuver Planning: RTN-frame evasion burns (T-axis priority for fuel efficiency) with automatic recovery scheduling
• Fuel Tracking: Tsiolkovsky rocket equation with mass-aware depletion and EOL graveyard orbit trigger at 5% threshold

---

🏆 Scoring Alignment

Criteria	Weight	Strategy
Safety	25%	Zero collisions via 24h CDM forecast, 200m safety margin (2× threshold), autonomous COLA
Fuel Efficiency	20%	Minimum-energy T-axis phasing burns, 36-point burn-time optimizer, mass-aware Tsiolkovsky, fleet health handshake
Uptime	15%	Dynamic recovery timing (recover when debris >50km), 10km station-keeping box, exponential uptime scoring
Speed	15%	4-stage KDTree O(S log D), vectorized DOP853 batch propagation, adaptive sub-stepping, NumPy broadcast
UI/UX	15%	60FPS Canvas rendering, 5 dashboard modules, 10K+ debris batched
Code Quality	10%	Modular 3-layer architecture, type hints, structured logging, pytest

---

👥 Team

Built with ❤️ at IIT Delhi for Hackathon 2026.

---

_{Licensed under MIT · Port 8000 · ubuntu:22.04 · Single Container}