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

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 and 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 – The bootstrap layer that loads Google 3D tiles and registers all data layers during application startup.
• 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) that expose a standardized interface: init, enable, disable, update, destroy, and getStats.
• src/voice/gevActions.js – Server-side handlers for the 28 voice tools declared in 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 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

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):

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:

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.

Finding Your First Contribution

The 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 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:

// 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 and add a toggle control in src/ui.js.

Adding CCTV Source Packs

Create JSON configuration files following this schema:

{
  "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, then register the pack in 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 by adding to the GEV_REALTIME_TOOLS array:

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 and add corresponding UI feedback mechanisms in 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).
• 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) for all authenticated requests.
• Documentation updates: Modify docs/CURRENT-STATE.md and CHANGELOG.md whenever you change runtime behavior.

Running Tests

Execute the full verification suite before submitting:

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 and CHANGELOG.md.

The maintainers review PRs against the threat model in 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), UI (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 and handlers in 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) and implement the six required lifecycle functions. Register your layer in src/main.js during the bootstrap phase, add a UI toggle in 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. 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 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.

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