The Problem Operators and analysts spend most of their time stitching together dozens of web‑pages, APIs, and ad‑hoc visualisers to get a situational picture of live air, sea and ground activity. The UI is fragmented, the data pipelines are hidden, and any customisation requires digging through a maze of loosely‑connected scripts. The result is high cognitive load and brittle workflows.

What This Does God’s Eye View delivers a single, browser‑based 3‑D globe that streams real‑time public feeds (ADS‑B, AIS, OpenSky, public CCTV, seismic data) and renders them with photorealistic aircraft models and sensor‑style visual filters. Core logic lives under src/ – e.g. src/data/flights.js, src/data/aisLiveVessels.js, and src/data/cctv.js fetch and normalise each feed. Rendering orchestration lives in src/renderGovernor.js, while annotation handling is in src/annotations/annotationEngine.js. The public assets (models, SVG icons, GIF demos) are in public/ and docs/media/.

How It Is Wired

  1. Bootstrap – index.html loads the Vite bundle generated from src/main.js.
  2. Application start – src/main.js creates the Three.js scene, camera (src/camera.js) and registers the render loop via src/renderGovernor.js.
  3. Data ingestion – the render loop calls the data manager (e.g. src/data/flights.js, src/data/aisLiveVessels.js) which each import their respective adapters (src/data/aisStreamAdapter.js, src/data/adsbLolFallback.js). These modules poll public endpoints defined in config/ JSON files and expose a normalized stream of contacts.
  4. Rendering – renderGovernor is the hub (26 inbound imports, 0 outbound) and decides which overlay to draw. It pulls in src/overlays/worldOverlay.js (the most‑connected overlay, 17 dependents) and dispatches to specialised renderers (src/cockpitTracking.js, src/cockpitVisionPolicy.js).
  5. Interaction – UI actions funnel through src/annotations/* which resolve GeoJSON, screen‑space, or hybrid annotations and feed back to the render loop. Voice control is wired via src/cctvFocusPolicy.js and related request modules.
  6. Export / share – URL serialisation is performed in src/annotations/worldAnnotationRenderer.js, allowing a full state (camera, layers, target) to be bookmarked.

The import graph shows no circular dependencies and 348 internal modules, but renderGovernor and several data files (flights, militaryFlights) have the highest instability scores, meaning changes there propagate widely.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/gods-eye-view.git
cd gods-eye-view

# 2. Install dependencies (npm is declared in package.json)
npm ci

# 3. Provide required API keys – copy the template and fill values
cp .env.example .env   # keys for OpenSky, Google Maps, etc. are documented in the file

# 4. Start the development server (Vite)
npm run dev            # serves index.html on http://localhost:5173

The scripts/run-unit-tests.mjs script runs the 156 test files; invoke it with node scripts/run-unit-tests.mjs. Documentation for each data source lives in DATA_SOURCES.md.

Real‑World Use A security‑operations centre could embed the globe in an internal portal, replace the default OpenSky key in .env with a privileged feed, and add a custom overlay that highlights aircraft within a no‑fly zone. The centre would import src/data/groundFloor.js to pull live ground‑traffic data, then call renderGovernor.toggleOverlay('militaryHud') to activate the tactical HUD for analysts.

Code Health & Issues

  • High – No CI/CD – 349 source files, no GitHub Actions or other pipeline. Add a workflow that runs npm run build and the unit‑test script on every push/PR.
  • Medium – Dependabot missing – Only one manifest (package.json). Add .github/dependabot.yml to keep dependencies current.
  • Medium – Large binaries in repo – Files such as docs/media/start‑here/military-cockpit-dense-google-3d.gif (8.2 MB) and other GIFs >5 MB inflate clone size. Move them to Git LFS or external storage.

Additional static‑analysis findings (high cognitive load in src/overlays/worldOverlay.js, deep nesting in src/data/flights.js, duplicated shell snippets in scripts/*.sh) indicate refactoring opportunities but are not part of the formal health audit.

The Bottom Line God’s Eye View provides a functional, data‑rich 3‑D globe with a clear separation between data ingestion, rendering, and annotation. It is usable out‑of‑the‑box, but the codebase suffers from oversized hub modules and lacks automated testing pipelines, which raises maintenance risk for teams planning extensive customisation. It is a solid foundation for visual intelligence work, provided the consumer invests in CI, dependency automation, and modest refactoring.