# Gods-Eye-View Modules and Components: Complete Architecture Guide

> Explore the complete architecture of the gods-eye-view project. Discover its ten specialized modules, from Cockpit Core to UI Rendering, and understand their distinct roles.

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

---

**The gods-eye-view project consists of ten specialized modules—including Cockpit Core, CCTV Sensors, World Navigation, and UI Rendering—that encapsulate distinct responsibilities from flight-deck mathematics to frame-rate throttling.**

Gods-eye-view is a web-based tactical visualization platform that simulates an aircraft cockpit environment with external CCTV feeds, weather effects, and real-time navigation data. According to the `bilawalsidhu/gods-eye-view` source code, the codebase follows a strict modular architecture where individual JavaScript files handle isolated domain concerns. Understanding these gods-eye-view modules is essential for developers extending the simulation or integrating additional sensor streams.

## Cockpit Core: Flight-Deck Mathematics and Tracking

The **Cockpit Core** module handles all flight-deck display logic, including heading calculations, altitude tape rendering, and camera grounding safety. This foundational layer ensures the primary flight display remains synchronized with live data sources.

Key source files include:

- [`src/cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitMath.js) – Contains core flight mathematics including `normalizeHeading()`, `slewHeading()`, and `altitudeRulerTicks()` for HUD rendering
- [`src/cockpitTracking.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitTracking.js) – Synchronizes cockpit displays with live flight data streams
- [`src/cockpitVisionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitVisionPolicy.js) – Determines camera visibility constraints and safety limits
- [`src/cockpitUtilityLayout.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitUtilityLayout.js) – Manages utility panel positioning within the cockpit view
- [`src/cockpitCloudEffects.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitCloudEffects.js) – Handles atmospheric rendering specific to the cockpit viewport

The mathematical utilities in [`cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitMath.js) provide essential transformations for aviation displays:

```javascript
import {
  normalizeHeading,
  slewHeading,
  cockpitUiUpdateDue,
} from './cockpitMath.js';

// Normalise a raw heading value (e.g., from a sensor)
const heading = normalizeHeading(rawHeading);   // 0 – 359°

/* Smoothly slew the displayed heading toward a target
   without exceeding a max step size (deg per frame) */
const displayed = slewHeading(currentHeading, targetHeading, 2.5);

/* Determine whether the cockpit UI should repaint */
const shouldUpdate = cockpitUiUpdateDue(Date.now(), lastUpdateMs, 100);

```

For aircraft identification across different data layers, the `resolveTrackedAircraftInfo()` function merges civilian and military tracking data:

```javascript
import { resolveTrackedAircraftInfo } from './cockpitMath.js';

const info = resolveTrackedAircraftInfo({
  civilian: civilianLayerInfo,
  military: militaryLayerInfo,
  trackedId: 'military:ABCD12',
});
// `info` now contains the owning layer's data and a `layerId` field.

```

Altitude visualization uses `altitudeRulerTicks()` to generate HUD tick marks:

```javascript
import { altitudeRulerTicks } from './cockpitMath.js';

const ticks = altitudeRulerTicks(12000); // altitude in feet
// `ticks` is an array of objects describing each tick value and its visual slot.

```

## CCTV and External Sensor Integration

The **CCTV and External Sensors** module manages auxiliary video feeds that supplement the primary cockpit view. These components handle asynchronous camera requests and policy-based feed activation.

Key implementations include:

- [`src/cctvFocusRequest.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cctvFocusRequest.js) – API for requesting external camera streams via `requestCCTVFocus()`
- [`src/cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cctvFocusPolicy.js) – Policy engine determining when CCTV feeds should overlay the primary display

Requesting a CCTV feed follows this pattern:

```javascript
import { requestCCTVFocus } from './cctvFocusRequest.js';

const feed = await requestCCTVFocus({ cameraId: 'cam-42', bounds: myBounds });
if (feed) {
  // Render the CCTV video overlay
}

```

The policy layer in [`cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusPolicy.js) evaluates contextual rules—such as aircraft proximity or alert status—to determine feed visibility without cluttering the primary tactical view.

## World Focus and Navigation Systems

The **World Focus and Navigation** modules determine the geographic center of attention and compute great-circle bearings for route planning. These components bridge the gap between raw coordinate data and the visual map representation.

Primary source files:

- [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) – Calculates the viewer's geographic focus point and viewport bounds
- [`src/navigationPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/navigationPolicy.js) – Implements routing logic and bearing calculations
- [`src/orbit.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/orbit.js) – Handles orbital camera movements around points of interest

These modules feed directly into the map controller, ensuring the tactical view remains centered on relevant operational areas while maintaining proper navigation context.

## Weather Effects and Atmospheric Rendering

The **Weather Effects** module provides mathematical models for visualizing atmospheric phenomena. Rather than simple overlays, these utilities calculate realistic cloud positioning and precipitation patterns based on altitude and geographic data.

Key file:

- [`src/weatherEffectsMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/weatherEffectsMath.js) – Mathematical models for cloud density, precipitation probability, and atmospheric scattering
- [`src/cockpitCloudEffects.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitCloudEffects.js) – Viewport-specific weather rendering for the cockpit display

These modules enable dynamic weather visualization that responds to the aircraft's current altitude and location, enhancing situational awareness during tactical operations.

## UI Components and Layout Management

The **UI and Rendering** layer encompasses the heads-up display (HUD), panel layouts, and interactive controls that present data to the operator. This module ensures consistent frame rates and responsive interactions under heavy data loads.

Critical components include:

- [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) – Low-level HUD drawing primitives and display elements
- [`src/panelStackLayout.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/panelStackLayout.js) – Manages z-indexing and positioning of stacked UI panels
- [`src/hudLocality.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hudLocality.js) – Handles HUD element positioning relative to viewport edges
- [`src/rightRailPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/rightRailPolicy.js) – Controls the contextual right-hand information panel
- [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) – Orchestrates map layers and interaction chips
- [`src/mapStackChips.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackChips.js) – Renders interactive map markers and selection chips

The **Render Governor** ([`src/renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js)) acts as a performance safeguard, throttling rendering operations to maintain consistent frame rates when processing high-frequency data updates. This prevents UI lag during intensive flight tracking scenarios.

General UI utilities in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) provide reusable widgets—such as tooltips, buttons, and split-flap displays ([`src/splitFlap.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/splitFlap.js))—used across multiple panels.

## Entry Points and System Integration

The **Entry Point and Misc** module bootstraps the application and wires all components together. This top-level orchestration layer initializes the global application context and manages the module lifecycle.

Key files:

- [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) – Application bootstrap, configuration loading, and top-level orchestration
- [`src/logoGaze.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/logoGaze.js) – Handles logo visibility and gaze-based interactions
- [`src/loadingFeedback.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/loadingFeedback.js) – Provides visual feedback during data initialization
- [`src/locations.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/locations.js) and [`src/locationStatus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/locationStatus.js) – Manage geographic data sources and status indicators
- [`src/sharelink.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/sharelink.js) – Generates shareable URLs for specific tactical views
- [`src/scopeMask.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scopeMask.js) – Applies visual masks to limit the operational scope display

The initialization sequence in [`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js) creates the global application context, instantiates the render governor for frame pacing, and loads the initial world focus before mounting the cockpit interface.

## Summary

- **Cockpit Core** ([`cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitMath.js), [`cockpitTracking.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitTracking.js)) handles flight-deck mathematics, heading normalization, and live data synchronization
- **CCTV Modules** ([`cctvFocusRequest.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusRequest.js), [`cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusPolicy.js)) manage external video feeds through request APIs and visibility policies
- **Navigation Systems** ([`worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/worldFocus.js), [`navigationPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/navigationPolicy.js), [`orbit.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/orbit.js)) determine geographic focus and calculate flight bearings
- **Weather Effects** ([`weatherEffectsMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/weatherEffectsMath.js), [`cockpitCloudEffects.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitCloudEffects.js)) provide atmospheric visualization algorithms
- **UI Layer** ([`hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/hud.js), [`panelStackLayout.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/panelStackLayout.js), [`rightRailPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/rightRailPolicy.js)) renders tactical displays with the **Render Governor** ([`renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/renderGovernor.js)) ensuring consistent performance
- **Entry Point** ([`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js)) bootstraps the application and coordinates all module interactions

## Frequently Asked Questions

### What is the primary role of cockpitMath.js in the gods-eye-view architecture?

The [`cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitMath.js) module serves as the mathematical foundation for the flight deck, providing functions like `normalizeHeading()`, `slewHeading()`, and `altitudeRulerTicks()` to transform raw sensor data into aviation-standard displays. It handles critical calculations for heading normalization, smooth gauge transitions, and altitude tape generation used throughout the HUD rendering pipeline.

### How does the render governor maintain performance during heavy data loads?

The [`renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/renderGovernor.js) module implements frame-rate throttling by scheduling render cycles and skipping unnecessary repaints when the data update rate exceeds the display refresh capacity. This prevents UI lockup when processing high-frequency flight tracking updates or multiple simultaneous CCTV feeds.

### How do CCTV modules integrate with the main cockpit display?

The CCTV integration uses a two-stage process where [`cctvFocusRequest.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusRequest.js) handles asynchronous camera feed acquisition via `requestCCTVFocus()`, while [`cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusPolicy.js) applies contextual rules to determine when external video should overlay the primary tactical view. This policy-based approach prevents display clutter while ensuring critical external feeds appear during specific operational contexts.

### What determines the initial geographic focus when the application loads?

The [`worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/worldFocus.js) module calculates the initial viewport center based on configuration parameters or default geographic boundaries, while [`navigationPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/navigationPolicy.js) establishes the initial bearing and route context. During bootstrap, [`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js) coordinates these modules to set the starting location before the map stack controller renders the initial tactical view.