# How to Contribute to the God’s Eye View Project: A Complete Developer Guide

> Learn how to contribute to the Gods Eye View project. Clone the repo, set up Node.js, and submit pull requests for geospatial data visualization.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-05

---

**You can contribute to the God’s Eye View project by cloning the repository, setting up the Node.js 24.14.0 environment, and submitting pull requests that follow the standardized layer interface for geospatial data visualization.**

The **God’s Eye View** project is a vanilla-JavaScript web application that visualizes live public-source geospatial data on a 3-D globe using **CesiumJS**. According to the `bilawalsidhu/gods-eye-view` source code, the architecture is deliberately flat to help contributors quickly locate and modify specific components, from data layers to voice control interfaces.

## Understanding the God’s Eye View Architecture

The codebase follows a modular, flat structure that separates concerns into distinct directories. Each **data layer**—such as flights, satellites, or CCTV feeds—exists as a self-contained module under `src/data/`.

| Area | Responsibility | Primary Files |
|------|----------------|---------------|
| **Bootstrap & globals** | Initialize Cesium and register layers | [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) |
| **UI façade** | Panels, HUD, and control widgets | [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) |
| **Layer implementation** | Individual data source modules | `src/data/*.js` (e.g., [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js)) |
| **Voice tools** | Server-side definitions and client actions | [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js), [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) |
| **Post-processing shaders** | GLSL style presets (CRT, NVG, FLIR) | `src/styles/*.js` |
| **Cockpit context** | Camera interaction and HUD logic | `src/cockpit*` |

All API keys remain server-side; the client only accesses public keys added via the *POWER UP* panel. This design ensures the codebase is safe to fork and run locally without hidden credentials.

## Setting Up Your Development Environment

Getting started requires **Node.js 24.14.0** (or Node 26.x as specified in [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json)). The project uses **Vite** for build tooling and development.

1. **Clone and install dependencies:**

   ```bash
   git clone https://github.com/bilawalsidhu/gods-eye-view.git
   cd gods-eye-view
   nvm install 24.14.0
   nvm use 24.14.0
   npm install
   ```

2. **Run the development server:**

   ```bash
   npm run doctor        # Validates Node version and provider config

   ./scripts/dev-fresh.sh   # Optional: clears Vite cache

   npm run dev           # Starts the app on http://localhost:4173

   ```

   No API keys are required to start; the app automatically falls back to Esri World Imagery and OpenStreetMap.

3. **Validate your changes:**

   Before submitting a pull request, ensure all three checks pass:

   ```bash
   npm run build
   npm test
   npm run test:track   # Requires the dev server to be running

   ```

## Contribution Paths for God’s Eye View

### Adding or Improving Data Layers

To contribute a new geospatial layer, create a module in `src/data/` that implements the standardized **layer interface**: `init()`, `enable()`, `disable()`, `update()`, and `destroy()`. Use [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js) as your template. The `enable()` method should handle data fetching, while `disable()` must clean up all Cesium primitives to prevent memory leaks.

### Contributing CCTV Source Packs

Add new camera networks by creating JSON configuration files under `config/` (e.g., `cctv_sources.<city>.json`). These files must include camera coordinates, attribution strings, and server-registered frame URLs. Reference the existing [`config/cctv_sources.shinjuku.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/config/cctv_sources.shinjuku.json) for the required schema.

### Extending Voice Control Functionality

Voice commands are defined in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) under the `GEV_REALTIME_TOOLS` configuration object, with corresponding client-side handlers in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js). When adding new voice tools, ensure you register the tool definition server-side and implement the action handler client-side to maintain the real-time command pipeline.

### Creating Visual Styles

New visual post-processing effects require writing GLSL fragment shaders in `src/styles/` and exposing them via the `STYLES` map in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js). Examine [`src/styles/retro.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/styles/retro.js) to understand how to structure shader presets for effects like CRT scanlines or night-vision green tints.

## Step-by-Step Guide to Adding a New Data Layer

Below is a minimal implementation for a custom layer called `myLayer`. This module fetches JSON data and renders point primitives on the Cesium globe:

```javascript
// src/data/myLayer.js
import * as Cesium from 'cesium';
import { getCesiumScene } from '../cesiumHelpers.js';

let entityCollection = null;

export default {
  /** Called once at app start – set up any static resources. */
  init() {
    const scene = getCesiumScene();
    entityCollection = scene.primitives.add(new Cesium.PrimitiveCollection());
  },

  /** Enable the layer – start polling / subscribing. */
  async enable() {
    const data = await fetch('https://example.com/public-data.json').then(r => r.json());
    data.features.forEach(f => {
      const point = Cesium.Cartesian3.fromDegrees(f.geometry.coordinates[0], f.geometry.coordinates[1]);
      entityCollection.add(new Cesium.PointPrimitive({
        position: point,
        color: Cesium.Color.YELLOW,
        pixelSize: 6,
      }));
    });
  },

  /** Disable the layer – stop network activity & clean up. */
  disable() {
    if (entityCollection) {
      entityCollection.removeAll();
    }
  },

  /** Periodic update – called by the main loop (≈15 s). */
  async update() {
    // Re‑fetch and replace the primitives, or implement delta logic.
    this.disable();
    await this.enable();
  },

  /** Clean up when the app shuts down. */
  destroy() {
    this.disable();
    const scene = getCesiumScene();
    scene.primitives.remove(entityCollection);
    entityCollection = null;
  },

  /** Optional: expose stats for the UI. */
  getStats() {
    return { count: entityCollection?.length ?? 0 };
  },
};

```

To activate your layer, import it in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) and add it to the `aggregateLayerLoading` list near lines 59-75.

## Submitting Your Contribution to God’s Eye View

Follow the standardized workflow to ensure your contribution to the gods-eye-view project is accepted:

1. **Branch off** `main` with a descriptive feature branch name.
2. **Make incremental commits** using 2-space indentation, single quotes, and semicolons.
3. **Run the full test suite** (`npm test` and `npm run test:track`) to maintain CI compliance.
4. **Update documentation**: Modify [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) if you change runtime behavior, or update [`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md) when adding new data sources with proper license attribution.
5. **Submit your PR** for review by maintainers Bilawal Sidhu and Sameh Khamis.

All contributions are automatically licensed under the project’s MIT license as specified in the `LICENSE` file.

## Summary

- **God’s Eye View** uses a flat architecture with self-contained data layers in `src/data/*.js` that implement `init`, `enable`, `disable`, `update`, and `destroy` methods.
- Development requires **Node.js 24.14.0** and uses **Vite**; start with `npm run doctor` and `npm run dev`.
- Contributors can add **CCTV sources** via JSON configs, extend **voice control** through [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) and [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js), or create **GLSL shaders** in `src/styles/`.
- Always run `npm run build`, `npm test`, and `npm run test:track` before submitting pull requests.
- Update [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) or [`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md) when changing runtime behavior or adding data sources.

## Frequently Asked Questions

### Do I need API keys to contribute to God’s Eye View?

No. The application falls back to Esri World Imagery and OpenStreetMap when no API keys are present, allowing you to develop and test locally without credentials. Server-side secrets in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) proxy external API calls to keep keys out of the browser.

### What is the standardized layer interface in God’s Eye View?

The layer interface requires five core methods: `init()` for setup, `enable()` to start data fetching, `disable()` to clean up resources, `update()` for periodic refreshes (called every ~15 seconds), and `destroy()` for final teardown. Optional methods like `getStats()` can expose metrics to the UI.

### How do I add a new camera source to the CCTV layer?

Create a new JSON file in `config/` following the `cctv_sources.<city>.json` naming convention. Include camera coordinates, attribution text, and the server-registered frame URL. See [`config/cctv_sources.shinjuku.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/config/cctv_sources.shinjuku.json) for the exact schema and field requirements.

### Which file should I edit to change the visual appearance of the globe?

Visual styles are controlled in `src/styles/*.js` using GLSL fragment shaders. After creating your shader file, register it in the `STYLES` map within [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) to make it selectable from the UI. Reference [`src/styles/retro.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/styles/retro.js) for implementation details on post-processing effects like CRT or NVG modes.