🛰️ 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

---

🧪 Testing

252 test methods across 19 test files — see TESTING.md for the full report.

$ python -m pytest tests/ -q
160 passed, 2 xfailed in 174s

Category	Tests	Coverage
Core physics engine	76	Propagation, collision, fuel, maneuvers, tick loop
Stress & flood	51	100K ingest, KDTree, ground stations, Tsiolkovsky
Integration (E2E)	31	API + engine end-to-end flows
Judge attack vectors	20	Burn timing, GMST, fast-path drift, evasion physics
Extreme edge cases	16	Boundary conditions, numerical landmines
System destroyers	15	Fleet wipeout, race conditions, 50K snapshot
Unit tests	43	Individual module validation

12 critical physics bugs identified by external review, all fixed and regression-tested. Verlet symplectic integrator replaced Euler/Taylor (258,000 km drift reduced to 0.8 km). Full timeline and benchmark results in TESTING.md.

---

👥 Team

Built with ❤️ at IIT Delhi for Hackathon 2026.

---

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