Skip to content

Architecture & Tech Stack

Jump to bottom
SpaceEngineerSS edited this page Dec 29, 2025 · 2 revisions

Architecture & Tech Stack 🏗️

OrbitView is designed for high performance and scientific accuracy. Here is an overview of the technical components and architecture.

🛠️ Technology Stack

Layer Technology Purpose
Core Framework Next.js 16 Modern React framework with Turbopack for performance.
Graphics Engine CesiumJS World-class 3D geospatial engine for planetary visualization.
React Components Resium React bindings for CesiumJS.
Physics Engine satellite.js SGP4/SDP4 implementations for orbital propagation.
Spatial Hashing Web Workers O(N) collision/link detection with 1000km³ grid cells.
State Management Zustand High-performance atomic state for UI sync.
Styling Tailwind CSS 4 Utility-first CSS for the modern HUD (Heads-Up Display).
Animations Framer Motion Fluid transitions and micro-interactions.

🛰️ System Architecture

1. Data Ingestion (TLE Hub)

OrbitView fetches Two-Line Element (TLE) data from multiple sources to ensure reliability:

  • Primary: Space-Track.org (via API)
  • Secondary: CelesTrak (CSV/JSON fallbacks)
  • Tertiary: Local static cache for offline/dev modes.

2. Propagation Layer

To maintain a responsive UI with thousands of objects, propagation (calculating position vs. time) is handled via Web Workers. This prevents the main UI thread from locking up during complex math.

3. Rendering Pipeline

  • LOD (Level of Detail): Satellites are rendered as simple points when zoomed out and transition to high-detail models/paths when approached.
  • Dynamic Layers: Specialized sub-components handle Ground Tracks, Footprints, and Orbit Paths separately to optimize React re-renders.

🚄 Performance Optimization (v2.0)

State Management Architecture

React Context API created performance bottlenecks when managing high-frequency time data (clock sync). To solve this, Zustand was adopted for atomic state management:

┌─────────────────────────────────────────────────────────────┐
│                    CESIUM CLOCK (Master)                     │
│                    60fps Animation Loop                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ 100ms throttle
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    ZUSTAND STORE (UI Sync)                   │
│     currentTime | isPlaying | multiplier | timelinePos      │
└──────────────────────────┬──────────────────────────────────┘
                           │ React renders
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    UI COMPONENTS                             │
│   MissionControl | TimeScrubber | TelemetryDeck | InfoPanel │
└─────────────────────────────────────────────────────────────┘

Spatial Hashing Physics Engine

To prevent O(N²) complexity when checking satellite links/conjunctions, a Spatial Hash Grid was implemented in satellite.worker.ts:

  • Cell Size: 1000km × 1000km × 1000km
  • Algorithm: Assign each satellite to a bucket, only check 27 neighboring cells for links
  • Complexity: Reduced from O(N²) to O(N × k) where k = average neighbors per cell
/**
 * Spatial Hash Grid Implementation
 * @scientific_reference Teschner, M. et al. "Optimized Spatial Hashing for Collision Detection"
 * 
 * Cell size of 1000km chosen to exceed maximum inter-satellite link range (2500km)
 * ensuring all potential links are captured in adjacent cell checks.
 */

Render Loop Decoupling

The React render cycle and Cesium render loop are explicitly decoupled:

  • Cesium: Runs at native 60fps via requestAnimationFrame
  • React: UI updates throttled to 100ms intervals
  • Result: Smooth animations without React re-render overhead

📊 Performance Benchmarks

Metric v1.0 v2.0 Improvement
Link calculation (25k sats) 312ms 18ms 17× faster
UI update frequency Every frame 100ms throttle 6× fewer renders
Memory usage (heap) 245MB 198MB 19% reduction

Clone this wiki locally