🌌 AstroDex — Space Objects & Debris Explorer

An interactive, open-source 3D space situational awareness (SSA) dashboard and command center. Visualize asteroids, track orbital debris, and monitor conjunction threats with active satellites — all in real-time.

---

🔗 Live Demo

👉 https://astrodex-nine.vercel.app

Open in a Chromium-based browser (Chrome, Edge, Brave) for the best WebGL experience. A dedicated GPU is recommended for smooth 60 fps rendering of 600+ orbital objects.

---

📸 Screenshots

Mission Control Dashboard

The full HUD overlay with 3D Earth, asteroid field, satellite orbits, and real-time conjunction alerts.

Asteroid Filter & Conjunction Alerter

Filter the orbital catalog by object type. The Conjunction Alerter panel displays live close-approach events with miss distance and risk classification.

Agent Terminal (Expanded)

The expandable Agent Terminal logs real-time sensor sweeps, conjunction screenings, maneuver burns, and orbital tracking data.

[!TIP]

---

🛠️ Tech Stack

Layer	Technology	Purpose
Framework	Next.js 16 (App Router)	Server/client rendering, routing, and build tooling
UI Library	React 19	Component-based UI architecture
3D Engine	Three.js	WebGL rendering, geometries, and materials
React ↔ 3D	React Three Fiber (R3F)	Declarative Three.js in React
3D Helpers	@react-three/drei	Stars, camera controls, and instanced mesh utilities
Post-Processing	@react-three/postprocessing	Bloom, vignette, and cinematic effects
Shaders	Custom GLSL	Earth day/night rendering, atmosphere scattering, cloud layers
Language	TypeScript	Type-safe development with strict mode
Styling	Vanilla CSS + CSS Variables	Glassmorphic design system with custom properties
Fonts	Geist + JetBrains Mono	UI typography + monospace terminal
Linting	ESLint	Code quality and consistency
Deployment	Vercel	Zero-config hosting for Next.js

---

🌌 Core Features

• Multi-Object Catalog Tracking

  • 400 Rocky Asteroids (Natural): rendered in grey-brown rock textures, each on its own random elliptical orbit (e ∈ [0, 0.28)).
  • 200 Space Debris Pieces (Man-made): spent rocket stages, dead satellites, and metallic fragments orbiting closer to Earth, rendered in high-visibility neon colors (orange, cyan, magenta).

• True Keplerian Orbital Mechanics

  • Every object (asteroids, debris, and the 3 satellites) is propagated by solving Kepler's Equation with a Newton-Raphson solver in src/lib/kepler.ts.
  • Per-frame Vis-Viva velocity — objects accelerate at perigee and decelerate at apogee.
  • Orbit-line geometries are drawn as true ellipses sweeping eccentric anomaly, not circles.
  • 📖 Full equations and derivations: see ARCHITECTURE.md.

• LEO Orbital Decay & Boost Burn

  • The ISS altitude continuously drops from simulated atmospheric drag.
  • The Right Sidebar's LEO Decay Monitor shows a green → amber → red health bar plus current altitude and drag rate.
  • Clicking Boost Burn injects Δv that restores the orbit; the maneuver is logged to the Agent Terminal.
  • As the ISS decays, the orbit ring visibly shrinks and conjunction risks with debris rise.
  • 📖 Exact decay rates and altitude thresholds: see ARCHITECTURE.md.

• Interactive Satellite System

  • Renders 3D orbital planes for active satellites: ISS (ZARYA), Envisat (Polar), and Hubble Space Telescope.
  • Satellites move along realistic inclined Keplerian trajectories.

• Real-Time Conjunction Alerting

  • Performs live 3D collision detection between satellites and the orbital catalog.
  • Triggers alerts inside the Conjunction Alerter panel and log notifications in the Agent Terminal when a space object approaches within critical distance.
  • Highlights at-risk objects in the 3D viewport by flashing their colors to a pulsing red indicator.

• Dynamic Orbital Telemetry Controls

  • The Right Sidebar's Manual Satellite (3D Orbit) panel is fully functional. Update parameters (Altitude, Inclination, RAAN, Eccentricity) and click Apply Trajectory to watch the ISS satellite and its elliptical orbit trail dynamically recalculate and warp in 3D in real-time.

• Cinematic Earth Shader

  • Custom GLSL material blending Earth day/night textures dynamically based on sun angle, highlighting glowing cities, ocean specular reflections, a twilight terminator ring, and atmospheric Rayleigh scattering effects.

• Agent Terminal

  • Expandable bottom terminal dock generating monospace logs of sensor sweeps, conjunction alerts, and maneuver sequences (including boost burns).

---

🚀 Getting Started

Prerequisites

Tool	Version	Notes
Node.js	18+	LTS recommended (includes npm)
npm	9+	Bundled with Node.js
Git	Any recent	For cloning and version control

Tip

Run node -v and npm -v to verify your installed versions.

Installation

# 1. Fork the repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/Astrodex.git
cd Astrodex

# 2. Add the upstream remote (to stay in sync)
git remote add upstream https://github.com/Omnikon-Org/Astrodex.git

# 3. Install dependencies
npm install

Running Locally

# Start the development server with hot-reload
npm run dev

Open http://localhost:3000 in your browser. Changes are reflected instantly via hot-reload.

Note

The 3D scene may take a few seconds to initialize on first load while WebGL compiles the GLSL shaders and generates procedural textures.

---

🏗️ Build & Deployment

Production Build

# Compile TypeScript and build the optimized production bundle
npm run build

# Start the production server locally
npm run start

The production server runs on http://localhost:3000 by default.

Available Scripts

Script	Command	Description
dev	npm run dev	Start the development server with hot-reload
build	npm run build	Create an optimized production build
start	npm run start	Serve the production build locally
lint	npm run lint	Run ESLint to check for code quality issues

Deploying to Vercel

AstroDex is designed for zero-config deployment on Vercel:

1. Import your fork on vercel.com/new
2. Vercel auto-detects the Next.js framework — no configuration needed
3. Click Deploy and your app goes live with HTTPS, CDN, and serverless functions

---

🧪 Testing & Validation

Type Checking

# Run the TypeScript compiler in check-only mode (no output emitted)
npx tsc --noEmit

Linting

# Run ESLint across the entire project
npm run lint

Build Validation

# Verify the project compiles successfully for production
npm run build

Pre-PR Checklist

Before opening a pull request, ensure all of the following pass:

npm run lint          # ✅ No new lint errors
npx tsc --noEmit      # ✅ No type errors
npm run build         # ✅ Build completes successfully

Important

All three checks must pass with zero new errors before submitting a PR. Existing lint warnings in src/components/earth/CloudLayer.tsx and src/components/earth/Earth.tsx are known issues related to React compiler/ref lint rules and are not blockers.

---

📂 Project Structure

Astrodex/
├── public/                     # Static assets
├── src/
│   ├── app/
│   │   ├── globals.css         # Mission Control theme tokens, glassmorphism, animations
│   │   ├── layout.tsx          # Font loading (Geist & JetBrains Mono), SEO metadata
│   │   └── page.tsx            # HUD overlay layout assembly
│   ├── components/
│   │   ├── earth/
│   │   │   ├── Earth.tsx       # Earth day/night custom GLSL shader
│   │   │   ├── CloudLayer.tsx  # Procedural cloud layer
│   │   │   ├── Atmosphere.tsx  # Atmosphere scattering shader glow
│   │   │   └── textures.ts     # Canvas 2D texture generators (zero external assets)
│   │   ├── AsteroidField.tsx   # Dual InstancedMesh (Asteroids & Space Debris) — Keplerian
│   │   ├── SatelliteSystem.tsx # ISS/Envisat/Hubble + LEO decay
│   │   ├── CameraController.tsx # Tracking camera controller
│   │   ├── Effects.tsx         # Post-processing composer (Bloom, Vignette)
│   │   ├── Scene.tsx           # Orchestrator canvas
│   │   ├── Header.tsx          # Simulation top navigation bar
│   │   ├── LeftSidebar.tsx     # Target tracking, load by ID, conjunction feed
│   │   ├── RightSidebar.tsx    # Orbital constraints + manual satellite + LEO decay monitor
│   │   ├── AgentTerminal.tsx   # Expandable log dock (auto-scrolls, color-coded)
│   │   └── AsteroidCard.tsx    # Inspector overlay panel
│   └── lib/
│       ├── kepler.ts           # Newton-Raphson solver, Vis-Viva, mean motion, decay
│       ├── store.tsx           # React state manager (filters, simulation, orbits, alerts)
│       └── types.ts            # TypeScript definitions
├── ARCHITECTURE.md             # Detailed rendering pipeline & component tree docs
├── CONTRIBUTING.md             # Contribution workflow, code style, and PR process
├── CODE_OF_CONDUCT.md          # Community guidelines
├── CHANGELOG.md                # Version history
├── LICENSE                     # MIT License
├── next.config.ts              # Next.js configuration
├── eslint.config.mjs           # ESLint configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies and scripts

---

🤝 Contributing

AstroDex is a GSSoC 2026 (GirlScript Summer of Code) project and welcomes first-time open-source contributors. For the full process and guidelines, see CONTRIBUTING.md. In short: comment on an issue to claim it, open a focused branch for your work, and submit a PR with a clear description and testing steps.

• New to open source? Check GOOD_FIRST_ISSUES.md for beginner-friendly tasks.
• Comment on the issue expressing interest so maintainers can assign it.
• Create a focused branch with a descriptive name (e.g., feat/…, fix/…, docs/…).
• Keep PRs small and include steps to reproduce or test.
• Have a question or idea? Use GitHub Discussions rather than opening an issue.
• Found a security issue? See SECURITY.md for responsible disclosure — please don't file it as a public issue.

Coding Style / Linting / Formatting

AstroDex uses TypeScript (strict mode), ESLint, and Tailwind. Follow the conventions in CONTRIBUTING.md#code-style (use @/ path alias, add "use client" for client components, avoid any, remove unused imports). Run these commands before opening a PR:

npm run lint
npx tsc --noEmit
npm run build

---

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ by the AstroDex contributors