# Where to Find Documentation for God's Eye View: Complete Guide to README, Docs Folder & Source Code

> Find Gods Eye View documentation in the README, docs folder, and source code comments. Get quick-start guides, runtime references, and security practices.

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

---

**God's Eye View documentation lives in the root [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md), a dedicated `docs/` folder, and inline comments throughout the source code in `src/`.** The project maintains comprehensive guides covering quick-start tutorials, runtime references, security practices, and API authentication.

This open-source geospatial visualization tool by Bilawal Sidhu organizes its knowledge base across multiple markdown files and self-documenting JavaScript modules. Whether you're deploying the app, contributing code, or troubleshooting data layers, the repository provides structured documentation at every level.

## Primary Documentation Locations

### Root README.md — The Main Entry Point

The **[`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)** at the repository root serves as the central hub for new users. It contains the **"Quick‑Start"** section with installation commands, an **"Under the Hood"** architectural diagram explaining the source layout, and direct links to all supplemental documentation.

Key sections in the README include:
- Project overview and feature list
- API key configuration guide
- Cost information for paid data providers
- Safety notice for production deployments

Access it directly: [github.com/bilawalsidhu/gods-eye-view/blob/main/README.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)

### docs/ Folder — Deep-Dive Reference Materials

The **`docs/`** directory houses specialized documentation for advanced topics:

| File | Purpose |
|------|---------|
| [`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md) | Full runtime reference describing the application's operational state |
| [`PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/PERFORMANCE.md) | Benchmark data and startup time analysis |
| [`KNOWN-ISSUES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/KNOWN-ISSUES.md) | Documented limitations and active bugs |
| [`opensky-auth.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/opensky-auth.md) | OpenSky Network authentication configuration options |

To browse these files locally after cloning:

```bash
git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
npx serve docs

# Navigate to http://localhost:5000/CURRENT-STATE.md

```

## Contributor and Security Documentation

### CONTRIBUTING.md — Development Workflow

The **[`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)** file defines the contribution workflow, code style conventions, and testing commands. Review this before submitting pull requests to ensure your changes align with project standards.

[github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)

### SECURITY.md — Threat Model and Key Handling

The **[`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md)** document details the security architecture, threat model analysis, and safe practices for storing and sharing API keys. It explains how secrets are handled in the **POWER UP** panel implementation.

[github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md)

### DATA_SOURCES.md — Data Provenance

The **[`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md)** file catalogs all external APIs and datasets powering the live layers: flights (OpenSky), maritime vessels, satellites, earthquakes, wildfires, and weather systems.

[github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md)

## Source Code as Documentation

The JavaScript modules in **`src/`** contain extensive inline comments that function as developer documentation. These files represent the architectural backbone of God's Eye View:

### Core Application Files

- **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)** — Bootstraps the Cesium JS scene, registers all data layers, and initializes the Vite development server
- **[`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)** — Implements UI panels, HUD overlays, and keyboard interaction shortcuts
- **[`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js)** — Powers the **POWER UP** authentication panel for provider API keys
- **[`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js)** — Manages basemap switching between Esri, Google 3D, OpenStreetMap, and Cesium Ion

### Specialized Modules

- **`src/voice/`** — Contains OpenAI Realtime voice integration with 28 voice-controlled tools
- **`src/data/`** — Individual modules for each live data layer (flights, vessels, satellites, wildfires, etc.)

### Build and Development Tools

- **[`scripts/dev-fresh.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh)** — Shell script that clears Vite caches and retrieves stored keys from macOS Keychain
- **[`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json)** — Defines runtime dependencies (`cesium`, `vite`) and npm scripts (`dev`, `doctor`)

## Programmatically Accessing Documentation

For automated documentation workflows, list and read markdown files programmatically:

```javascript
import { readdirSync, readFileSync } from 'fs';
import path from 'path';

// List all markdown files under docs/
const docsPath = path.resolve('docs');
const mdFiles = readdirSync(docsPath).filter(f => f.endsWith('.md'));

mdFiles.forEach(f => {
  const content = readFileSync(path.join(docsPath, f), 'utf8');
  console.log(`--- ${f} ---\n${content.slice(0, 200)}\n`);
});

```

## Summary

- **Start with [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)** for installation, architecture overview, and quick-start commands
- **Consult `docs/` folder** for runtime reference ([`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md)), performance benchmarks, and known issues
- **Review [`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)** and [`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md) before contributing code or handling API keys
- **Read [`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md)** to understand external data dependencies
- **Explore `src/` source files** for implementation details via inline comments in [`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js), [`ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/ui.js), [`keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/keySetup.js), and data layer modules

## Frequently Asked Questions

### Does God's Eye View have official API documentation?

No formal API reference exists. Documentation is distributed across markdown files and inline source comments. The `src/data/` modules expose their interfaces through JSDoc-style comments, and [`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md) in the `docs/` folder documents runtime behavior.

### How do I configure API keys for God's Eye View data providers?

Follow the **POWER UP** panel workflow implemented in [`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js), or read [`docs/opensky-auth.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/opensky-auth.md) for OpenSky-specific authentication options. The root [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) contains a complete API key guide covering all supported providers.

### Where are performance benchmarks documented for God's Eye View?

Startup times and runtime benchmarks are detailed in **[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md)**. This file includes measurements for Cesium initialization, data layer loading, and voice system warm-up times.

### Can I contribute documentation improvements to God's Eye View?

Yes. Submit documentation changes via pull request following the workflow in **[`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)**. The project accepts improvements to markdown files in `docs/`, README updates, and enhanced inline comments in `src/` modules.