# How to Contribute to Gods-Eye-View: A Developer's Guide to the 3D Globe Project

> Learn how to contribute to the gods-eye-view 3D globe project. Clone the repo, implement features in src/data/, and submit pull requests with updated documentation and changelog.

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

---

**Contribute to gods-eye-view by cloning the repository at `bilawalsidhu/gods-eye-view`, implementing features following the modular layer architecture in `src/data/`, and submitting pull requests that update both [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) and [`CHANGELOG.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CHANGELOG.md).**

Gods-eye-view is a vanilla-JavaScript, CesiumJS-based web application that visualizes dozens of live public-data layers on a photorealistic 3D globe. The repository maintains a deliberately simple architecture that allows contributors to add new data sources, extend voice control capabilities, or enhance visual styles without navigating complex framework abstractions.

## Understanding the Architecture

Before you contribute, familiarize yourself with the five core components that define the runtime structure:

- **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)** – The bootstrap layer that loads Google 3D tiles and registers all data layers during application startup.
- **[`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)** – The UI façade handling panels, HUD elements, and keyboard shortcuts that interface with the globe visualization.
- **`src/data/<layer>.js`** – Modular layer implementations (e.g., [`src/data/liveFlights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/liveFlights.js)) that expose a standardized interface: `init`, `enable`, `disable`, `update`, `destroy`, and `getStats`.
- **[`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js)** – Server-side handlers for the 28 voice tools declared in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js), managing natural language interactions.
- **`src/styles/`** – GLSL post-process shaders for visual effects applied to the CesiumJS viewport.

> **Critical:** Read [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) before writing code. This file serves as the authoritative runtime reference for the current implementation state.

## Setting Up the Development Environment

The project requires **Node.js 24.x** (specifically tested on 24.14.0) and uses Vite for the build system with a proxy that conceals all API secrets.

### Installation Steps

```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

```

### Configuration

Copy the environment template and insert your Google Maps API key (restricted to your domains):

```bash
cp .env.example .env

# Edit .env to add your GOOGLE_MAPS_API_KEY

```

### Starting the Dev Server

Launch the development server on localhost port 4173:

```bash
npm run dev -- --host localhost --port 4173

```

The server will proxy requests to hide secrets from the client side, consistent with the security model defined in [`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md).

## Finding Your First Contribution

The [`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md) file lists four high-leverage entry points for new contributors:

1. **Add a CCTV source pack** – Create JSON configuration files under `config/` and register them in the proxy configuration.
2. **Add or improve a data layer** – Clone an existing module in `src/data/` and implement the required layer interface.
3. **Extend voice control** – Define new tools in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) and implement handlers in `src/voice/`.
4. **Add visual styles** – Create GLSL shaders in `src/styles/` and register them through the UI façade.

## Implementing Common Contribution Types

### Adding a New Data Layer

Each layer module follows a strict contract. Create a new file in `src/data/` implementing these six exported functions:

```javascript
// src/data/exampleLayer.js
export const init = (store) => {
  // Called once during app initialization
  store.state = { enabled: false };
};

export const enable = (store) => {
  store.state.enabled = true;
  // Start polling or subscribe to WebSocket feeds
};

export const disable = (store) => {
  store.state.enabled = false;
  // Stop network activity
};

export const update = (store, delta) => {
  if (!store.state.enabled) return;
  // Refresh entities, interpolate positions, process updates
};

export const destroy = (store) => {
  // Clean up timers, event listeners, and Cesium entities
};

export const getStats = (store) => ({
  enabled: store.state.enabled,
  // Return layer-specific metrics for the HUD
});

```

After implementation, register the layer in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) and add a toggle control in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js).

### Adding CCTV Source Packs

Create JSON configuration files following this schema:

```json
{
  "city": "New City",
  "source": "public-cctv-api.example.com",
  "cameras": [
    {
      "id": "cam-001",
      "lat": 37.7749,
      "lon": -122.4194,
      "heading": 90,
      "fov": 60,
      "url": "/proxy/cctv/newcity/cam-001.m3u8"
    }
  ]
}

```

Save this as [`config/cctv_sources.newcity.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/config/cctv_sources.newcity.json), then register the pack in [`scripts/dev-fresh.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh) or the Vite proxy configuration so the server can route requests securely.

### Extending Voice Control

Voice tools require changes in two locations. First, declare the tool in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) by adding to the `GEV_REALTIME_TOOLS` array:

```javascript
GEV_REALTIME_TOOLS: [
  {
    name: 'showWeather',
    description: 'Display current weather for a location',
    schema: {
      type: 'object',
      properties: {
        location: { 
          type: 'string', 
          description: 'Place name or coordinates' 
        }
      },
      required: ['location']
    },
    exec: async ({ location }) => {
      return await showWeather(location);
    }
  }
]

```

Then implement the handler function in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) and add corresponding UI feedback mechanisms in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) to display results on the globe.

## Coding Standards and Testing

The repository enforces strict code quality requirements:

- **Style:** Use 2-space indentation, single quotes, and semicolons (see the **Coding style** section in [`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)).
- **Documentation:** Write JSDoc for every exported function.
- **Security:** Never expose API keys in client-side code; use the Vite proxy (configured in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js)) for all authenticated requests.
- **Documentation updates:** Modify [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) and [`CHANGELOG.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CHANGELOG.md) whenever you change runtime behavior.

### Running Tests

Execute the full verification suite before submitting:

```bash
npm run build
npm test
npm run test:track   # Requires the dev server running on localhost:4173

```

The `test:track` command validates layer lifecycle management and entity tracking accuracy.

## Submitting Your Pull Request

When you contribute to gods-eye-view through a pull request:

1. **Target the `main` branch** with a feature branch based on the latest commit.
2. **Describe changes** clearly in the PR description, referencing any related issues.
3. **Attach screenshots** for visual modifications to the globe or UI panels.
4. **Update documentation** in both [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) and [`CHANGELOG.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CHANGELOG.md).

The maintainers review PRs against the threat model in [`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md) to ensure all secrets remain server-side.

## Summary

- **Architecture:** Gods-eye-view uses a modular design with clear separation between bootstrap ([`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)), UI ([`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)), and data layers (`src/data/`).
- **Setup:** Requires Node 24.14.0, uses Vite with a secret-hiding proxy, and runs on port 4173.
- **Layer Interface:** New data sources must implement `init`, `enable`, `disable`, `update`, `destroy`, and `getStats` functions.
- **Voice Tools:** Require declarations in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) and handlers in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js).
- **Quality:** All contributions need JSDoc, passing tests (`npm test`), and updated documentation files.

## Frequently Asked Questions

### What prerequisites do I need to contribute to gods-eye-view?

You need Node.js version 24.14.0 (managed via `nvm`), a Google Maps API key for the 3D tiles, and familiarity with vanilla JavaScript and CesiumJS concepts. The project uses Vite for building and testing, so basic knowledge of modern ES modules is essential.

### How do I add a new live data feed to the 3D globe?

Clone an existing module in `src/data/` (such as [`liveFlights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/liveFlights.js)) and implement the six required lifecycle functions. Register your layer in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) during the bootstrap phase, add a UI toggle in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js), and ensure you handle cleanup in the `destroy` function to prevent memory leaks.

### Where are API secrets stored in the gods-eye-view project?

All secrets—including Google Maps, OpenAI, and data provider keys—remain server-side through the Vite proxy configuration in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js). The client application only receives the Google Maps key (which you should domain-restrict), and all authenticated data requests route through the development server to prevent exposure.

### Why must I update [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md) when submitting a PR?

This file serves as the authoritative runtime reference for the project architecture and feature set. Updating it ensures that subsequent contributors understand the current implementation state, maintain consistency with existing patterns, and can trace when specific capabilities were introduced or modified.