🛰️ ORBITAL GUARDIAN

Real-Time Satellite Collision Risk Dashboard

A production-grade web application for tracking satellites and space debris, monitoring collision risks, and visualizing orbital data using real data from Space-Track.org.

---

🌟 Features

Real-Time Satellite Tracking

• Live Position Updates: SGP4 orbital propagation updates satellite positions every 5 seconds
• TLE Data Processing: Uses Two-Line Element sets from Space-Track.org
• Multi-Orbit Support: Tracks LEO, MEO, GEO, and HEO satellites

Interactive Map Visualization

• Dark Aerospace Theme: Professional mission control aesthetic
• Orbit Path Rendering: Dynamic orbit trajectory visualization
• Color-Coded Objects: Active satellites (green), debris (red), rocket bodies (orange)
• Area Selection: Shift+drag to select geographic regions

Collision Risk Assessment

• Close Approach Detection: Distance-threshold based conjunction screening
• Risk Classification: CRITICAL, HIGH, MEDIUM, LOW levels
• Probability Estimation: Simplified collision probability model
• Alert Timeline: Time-to-closest-approach countdowns

Search & Filtering

• Name/NORAD ID Search: Find specific satellites
• Orbit Type Filter: LEO/MEO/GEO/HEO selection
• Object Type Filter: Payloads, Debris, Rocket Bodies
• Country Filter: Filter by launching country
• Geographic Filtering: Select satellites over specific regions

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           ORBITAL GUARDIAN SYSTEM                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────┐    ┌──────────────────┐    ┌────────────────────┐    │
│  │   SPACE-TRACK    │───▶│     BACKEND      │───▶│      FRONTEND      │    │
│  │   .ORG API       │    │  (Python FastAPI)│    │  (React + TypeScript│    │
│  └──────────────────┘    └──────────────────┘    └────────────────────┘    │
│          │                       │                         │                │
│          ▼                       ▼                         ▼                │
│  ┌──────────────────┐    ┌──────────────────┐    ┌────────────────────┐    │
│  │ • TLE Data       │    │ • Auth Proxy     │    │ • Leaflet Map      │    │
│  │ • Satellite Cat  │    │ • SGP4 (Python)  │    │ • SGP4 (JS)        │    │
│  │ • CDM Public     │    │ • Caching        │    │ • React Components │    │
│  │ • Decay Data     │    │ • Rate Limiting  │    │ • Real-time Updates│    │
│  └──────────────────┘    └──────────────────┘    └────────────────────┘    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Data Flow

1. Space-Track.org provides authoritative satellite catalog and TLE data
2. Backend (FastAPI) handles authentication, caching, and rate limiting
3. Frontend (React) performs client-side SGP4 propagation for real-time updates
4. satellite.js library computes positions from TLE data every 5 seconds

---

🚀 Quick Start

Prerequisites

• Node.js 18+ (for frontend)
• Python 3.9+ (for backend)
• Space-Track.org Account (free registration)

1. Clone and Install

# Install frontend dependencies
npm install

# Install backend dependencies
cd backend
pip install -r requirements.txt
cd ..

2. Configure Space-Track Credentials

# Copy the example environment file
cp backend/.env.example backend/.env

# Edit with your credentials
# Get credentials at: https://www.space-track.org/auth/createAccount

3. Start the Backend

cd backend
uvicorn main:app --reload --port 8000

4. Start the Frontend

# In a new terminal
npm run dev

5. Open the Dashboard

Navigate to http://localhost:5173

---

📁 Project Structure

orbital-guardian/
├── src/
│   ├── components/
│   │   ├── AlertsPanel.tsx      # Collision alerts display
│   │   ├── Globe.tsx            # Map visualization (Leaflet)
│   │   ├── SatellitePanel.tsx   # Satellite list & filters
│   │   └── StatsHeader.tsx      # Dashboard statistics
│   ├── hooks/
│   │   └── useSatelliteData.ts  # Data fetching & state
│   ├── services/
│   │   ├── demoData.ts          # Demo TLE data (fallback)
│   │   ├── orbitalMechanics.ts  # SGP4 propagation
│   │   └── spaceTrackApi.ts     # API client
│   ├── types/
│   │   └── satellite.ts         # TypeScript definitions
│   └── App.tsx                  # Main application
├── backend/
│   ├── main.py                  # FastAPI server
│   ├── requirements.txt         # Python dependencies
│   └── .env.example             # Environment template
└── README.md

---

🔧 Configuration

Environment Variables

Backend (.env)

Variable	Description	Required
SPACETRACK_USERNAME	Space-Track.org username	Yes
SPACETRACK_PASSWORD	Space-Track.org password	Yes
HOST	Server host (default: 0.0.0.0)	No
PORT	Server port (default: 8000)	No

Frontend (.env)

Variable	Description	Default
VITE_API_BASE_URL	Backend API URL	/api

---

🛸 Space-Track.org API

Endpoints Used

Endpoint	Purpose
/basicspacedata/query/class/satcat	Satellite catalog
/basicspacedata/query/class/gp	TLE (GP) data
/basicspacedata/query/class/cdm_public	Conjunction Data Messages

Rate Limits

Space-Track enforces rate limits:

• 20 requests/minute for authenticated users
• The backend implements caching to minimize requests

Data Freshness

• TLE data is typically updated every 1-3 days
• CDM (Conjunction Data) is updated as events occur
• Catalog data updates reflect new launches and decays

---

🌍 Orbital Mechanics

SGP4/SDP4 Propagation

The system uses the SGP4 (Simplified General Perturbations 4) algorithm:

• SGP4: For near-Earth objects (period < 225 minutes)
• SDP4: For deep-space objects (period ≥ 225 minutes)

Coordinate Transformations

1. TLE → Satrec: Parse Two-Line Elements
2. Satrec → ECI: Propagate to Earth-Centered Inertial
3. ECI → ECEF: Rotate by GMST
4. ECEF → Geodetic: Convert to lat/lon/alt

Orbit Classification

Type	Altitude Range	Period
LEO	160 - 2,000 km	~90 min
MEO	2,000 - 35,000 km	2-24 hrs
GEO	~35,786 km	24 hrs
HEO	Variable	Variable

---

⚠️ Collision Risk Assessment

Methodology

1. Screening: Identify pairs with potential close approaches
2. Propagation: Compute positions over 24-hour window
3. Distance Calculation: Find minimum miss distance
4. Risk Classification: Based on miss distance thresholds

Risk Levels

Level	Miss Distance	Action
CRITICAL	< 100 m	Immediate review required
HIGH	< 500 m	Close monitoring
MEDIUM	< 2 km	Standard tracking
LOW	< 50 km	Logged for reference

Probability Estimation

⚠️ IMPORTANT: Without covariance data, probability estimates are approximations.

For operational decisions, use official Conjunction Data Messages (CDM) from:

• 18th Space Defense Squadron (US Space Force)
• ESA Space Debris Office

---

🔒 Security Considerations

1. Credentials: Never expose Space-Track credentials in frontend code
2. CORS: Configure allowed origins for production
3. Rate Limiting: Implement to prevent API abuse
4. HTTPS: Use TLS in production

---

📊 Demo Mode

When the backend is not connected, the frontend uses:

• Cached TLE Data: Real satellite TLEs (may be outdated)
• SGP4 Propagation: Positions computed client-side
• Demo Alerts: Example conjunction events

Note: Demo mode is for visualization only. Data may not reflect current orbital positions.

---

🧪 Testing

# Frontend tests
npm test

# Backend tests
cd backend
pytest

---

📚 References

Technical Resources

• Space-Track.org API Documentation
• SGP4 Algorithm
• satellite.js Library

Orbital Mechanics

• Vallado, D.A. "Fundamentals of Astrodynamics and Applications"
• Kelso, T.S. "Satellite Orbital Calculations" (CelesTrak)

Space Debris

• ESA Space Debris Office Annual Reports
• NASA Orbital Debris Quarterly News

---

📄 License

MIT License - See LICENSE file for details.

---

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

---

⚡ Acknowledgments

• Space-Track.org for providing authoritative orbital data
• CelesTrak for TLE format documentation
• 18th Space Defense Squadron for space situational awareness

---

Built with 🛰️ by aerospace enthusiasts

For educational and research purposes. Not for operational collision avoidance without official CDM data.