How the God's Eye View Project Is Structured: A Complete Architecture Guide

The God's Eye View codebase is organized as a feature-oriented vanilla JavaScript application that uses CesiumJS for 3D globe rendering, with a modular src/ directory separating concerns into bootstrap initialization, UI management, camera navigation, and self-contained data layers.

The bilawalsidhu/gods-eye-view repository implements a real-time intelligence visualization platform using a lightweight, framework-free stack of vanilla JavaScript, CesiumJS, and Vite. Understanding how the God's Eye View project is structured reveals a deliberate architectural choice favoring horizontal modularity over deep hierarchy, making it trivial to add new data feeds or visual overlays without touching core bootstrapping logic.

Top-Level Directory Layout

The repository root follows a conventional separation of concerns with five primary directories and configuration files at the top level:

• src/ – Core application code including bootstrapping, UI components, data-layer management, and rendering pipelines.
• tools/ – Standalone utility scripts for asset generation, such as panorama stitching and offline Cesium scene rendering (e.g., tools/cesium-render.mjs).
• scripts/ – Development and CI helpers including unit-test runners and key importers.
• docs/ – Markdown documentation covering performance characteristics, known issues, and data source references (e.g., docs/CURRENT-STATE.md).
• package.json and vite.config.js – Dependency management and build configuration for the Vite-based toolchain.
• style.css – Global stylesheet for UI components.

Core src/ Architecture

The heart of the application lives inside src/, organized by feature rather than by layer type. This flat structure ensures that camera logic, data providers, and visual effects remain decoupled.

Bootstrap and Initialization

The entry point src/main.js orchestrates the entire application lifecycle. It initializes the CesiumJS viewer, constructs the UI, and registers all data layers through a centralized manager.

// src/main.js
import { initCesium } from './mapStackController.js';
import { initUI } from './ui.js';
import { registerAllLayers } from './data/manager.js';

async function startApp() {
  await initCesium();            // loads Google 3-D tiles & creates Cesium Viewer
  initUI();                      // builds UI panels, HUD, and keyboard shortcuts
  registerAllLayers();           // registers flights, vessels, satellites, etc.
}
startApp();

UI and HUD Layer

The user interface is split between panel management and heads-up display logic. src/ui.js handles keyboard shortcuts, toggle buttons, and voice command facades, while src/hud.js and src/hudLocality.js render the intelligence overlays and AI summaries that float above the 3D globe.

Camera and Navigation System

Camera control is implemented through a verb-based architecture in src/cameraVerbs.js, which exposes discrete actions like flyTo, orbit, and cockpit view. These verbs are consumed by src/camera.js and regulated by src/navigationPolicy.js to enforce constraints during user interaction.

// src/cameraVerbs.js
export function flyTo(lat, lon, altitude = 5000) {
  const destination = Cesium.Cartesian3.fromDegrees(lon, lat, altitude);
  viewer.camera.flyTo({ destination });
}

// Example: voice command "Take me to Tokyo"
flyTo(35.6895, 139.6917);

Data Layer Management

Live feeds are self-contained modules inside src/data/. Each file (e.g., src/data/flights.js, src/data/traffic.js, src/data/aisLiveVessels.js) manages its own subscription logic, interpolation, and cleanup. The src/data/manager.js registry enables or disables these layers based on UI state.

// src/ui.js – snippet handling a toggle button
import { trafficLayer } from './data/traffic.js';

function onTrafficToggle(checked) {
  if (checked) {
    trafficLayer.enable();   // subscribes to TomTom feed, adds visual flow tiles
  } else {
    trafficLayer.disable();  // unsubscribes and removes the overlay
  }
}

Rendering and Visual Effects

Post-processing and world overlays live in src/overlays/ and dedicated effect files. src/bloom.js handles glow post-processing, src/cockpitCloudEffects.js manages atmospheric rendering, and flow tiles for traffic visualization are computed in src/flowTiles.js.

Policy and State Management

Business logic dictating what the UI displays is encapsulated in policy files. src/cockpitVisionPolicy.js, src/contactsDetectionPolicy.js, and src/contextModePolicy.js act as state machines that determine when to activate tracking modes or highlight detected contacts.

Utilities and Annotations

Geographic calculations reside in src/iconOrientation.js and src/weatherEffectsMath.js. The src/annotations/ directory contains the voice-driven whiteboard system (src/annotations/annotationEngine.js), allowing users to draw polygons and measure distances via speech commands.

Summary

• Framework-free architecture: The project uses only vanilla JavaScript, CesiumJS, and Vite, avoiding heavy frontend frameworks to maintain a small bundle size and fast iteration.
• src/main.js entry point: Centralized bootstrap sequence initializes the map stack, UI, and data layers in strict order.
• Feature-oriented src/ layout: Files are grouped by domain (camera, data, UI) rather than by type, making it easy to locate and modify specific functionality.
• Self-contained data modules: Each live feed in src/data/ manages its own lifecycle, enabling hot-swapping of traffic, flight, or satellite sources without system-wide refactors.
• Verb-based camera system: Navigation commands are abstracted into reusable functions in src/cameraVerbs.js, supporting both manual controls and voice-driven interactions.

Frequently Asked Questions

What build tool does God's Eye View use?

According to the source code, the project uses Vite as its build tool and development server, configured in vite.config.js at the repository root. This provides fast hot-module replacement and optimized production builds for the vanilla JavaScript codebase without requiring a heavy bundler setup.

How are new data layers added to the project?

New data feeds are implemented as self-contained modules inside src/data/ (following the pattern of src/data/flights.js or src/data/traffic.js), then registered in src/data/manager.js. Each module exports enable() and disable() methods that the UI calls via src/ui.js when users toggle layers from the control panel.

Is God's Eye View built with React, Vue, or another frontend framework?

No. The codebase is deliberately framework-free, relying solely on vanilla JavaScript modules, CesiumJS for 3D rendering, and native browser APIs. This design choice, documented in the repository's "Under the Hood" section, keeps the application lightweight and eliminates framework-specific boilerplate.

Where is the entry point for the application?

The browser entry point is src/main.js, which is referenced by index.html in the project root. This file initializes the Cesium viewer, mounts the UI via initUI(), and registers all data layers through registerAllLayers() before handing control to the user.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}