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

> Explore the gods-eye-view project structure. Learn about its vanilla JavaScript architecture, CesiumJS integration, and modular src directory for UI, camera, and data layers.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: architecture
- Published: 2026-08-30

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md)).
- **[`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json)** and **[`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js)** – Dependency management and build configuration for the Vite-based toolchain.
- **[`style.css`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)** handles keyboard shortcuts, toggle buttons, and voice command facades, while **[`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js)** and **[`src/hudLocality.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cameraVerbs.js)**, which exposes discrete actions like `flyTo`, orbit, and cockpit view. These verbs are consumed by **[`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js)** and regulated by **[`src/navigationPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/navigationPolicy.js)** to enforce constraints during user interaction.

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js)**, **[`src/data/traffic.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/traffic.js)**, **[`src/data/aisLiveVessels.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/aisLiveVessels.js)**) manages its own subscription logic, interpolation, and cleanup. The **[`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js)** registry enables or disables these layers based on UI state.

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/bloom.js)** handles glow post-processing, **[`src/cockpitCloudEffects.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitCloudEffects.js)** manages atmospheric rendering, and flow tiles for traffic visualization are computed in **[`src/flowTiles.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/flowTiles.js)**.

### Policy and State Management

Business logic dictating what the UI displays is encapsulated in policy files. **[`src/cockpitVisionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitVisionPolicy.js)**, **[`src/contactsDetectionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/contactsDetectionPolicy.js)**, and **[`src/contextModePolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/iconOrientation.js)** and **[`src/weatherEffectsMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/weatherEffectsMath.js)**. The **`src/annotations/`** directory contains the voice-driven whiteboard system (**[`src/annotations/annotationEngine.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js) or [`src/data/traffic.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/traffic.js)), then registered in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js). Each module exports `enable()` and `disable()` methods that the UI calls via [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)**, which is referenced by [`index.html`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.