The Problem

Visualizing global flight paths in a browser requires rendering thousands of animated objects on a textured 3D Earth with realistic lighting, while keeping interaction smooth. Naive per-object rendering fails at that scale; this repo solves it with GPU instanced rendering and custom shaders.

What This Does

A Three.js-based 3D flight path simulator. It renders a photorealistic Earth (src/space/Earth.ts, src/space/Atmosphere.ts, src/space/Stars.ts) with day/night cycles driven by real UTC time, and animates aircraft along parabolic curves between geographic points (src/flights/Flight.ts, src/flights/FlightUtils.ts). Aircraft are rendered as instanced planes with SVG or geometric styles (src/planes/PlanesShader.ts).

A GUI control panel (src/managers/Controls.ts) exposes flight count, speed, dash pattern, plane size, lighting, and time-of-day controls. The README documents a live demo and claims support for up to 30,000 simultaneous flights.

How It Is Wired

Execution starts in src/App.ts. The App class is the hub: it imports 15 modules and no module imports it, giving it instability 0.94—changing App.ts ripples everywhere, and it is already 652 lines. Its initializeFlights function (line 719) reaches 61 downstream functions, the widest blast radius in the repo. setupGlobalControls (line 278) reaches 37.

The dependency graph is healthy in one respect: src/common/Types.ts is imported by 10 modules and imports nothing (instability 0), so it is the stable contract everything builds on. There are zero circular dependencies across 19 modules and 49 import edges.

The only filesystem touch is a GUI folder: setupGlobalControls -> initialize -> setup -> setupFlightControls -> flightControlsFolder.open. That is one hop from a top-level entry point to the process boundary. No network or database access exists.

File-by-file ownership: src/common/Utils.ts provides math helpers (clamp is called from 8 places, the most in the repo); src/managers/Controls.ts owns the GUI; src/managers/FlightPathManager.ts owns dash styling; src/managers/EarthControlsManager.ts owns lighting toggles; src/curves/Curves.ts owns path geometry and gradient coloring; src/planes/PlanesShader.ts owns pane rendering. src/flights/Flight.ts carries 99 branch points over 300 lines—decision-heavy logic that would benefit from strategy dispatch.

How To Use It

git clone https://github.com/moses-y/flight-path
cd flight-path
npm install
npm run dev

Open http://localhost:5173. Build with npm run build; preview with npm run preview. No environment variables or API keys are required. The repo includes package.json, package-lock.json, tsconfig.json, and vite.config.js, so the toolchain is standard Vite + TypeScript.

Real-World Use

A logistics or aviation analytics team could embed this as a visualization layer: load real flight data (the repo supports both data-driven and procedurally generated flights), render routes with color-coded gradients by region, and let operators scrub through a 24-hour UTC timeline to see route density and aircraft positions. The FlightControlsManager and PlaneControlsManager APIs expose the parameters a host application would bind to its own data source.

Code Health & Issues

Static analysis (not opinion) found 5 medium findings across 3 kinds: high branching density in src/flights/Flight.ts (99 branch points over 300 lines); oversized files in src/flights/FlightUtils.ts (652 lines), src/App.ts, and src/managers/Controls.ts; and 9 duplicated 6-line blocks shared between src/App.ts and src/managers/FlightControlsManager.ts.

SDLC gaps visible from the file structure:

  • High - No tests exist across 20 source files; regressions ship undetected.
  • High - No CI workflow; nothing runs the build on push or pull request.
  • Medium - No Dependabot/Renovate config; dependency advisories go unpatched.
  • Medium - public/world.topo.jpg is a 17.4MB binary that every clone and CI checkout pays for; move it to LFS or object storage.

The Bottom Line

A solid, well-structured Three.js visualization with a clean module boundary via Types.ts and no circular dependencies. The architecture is sound for a demo-scale project, but the untested, CI-less state and the oversized App.ts hub make it risky to extend without first adding a test suite and splitting the core files. Suitable for a visualization prototype or as a reference for GPU-instanced Three.js rendering; not production-ready as-is.