# Gods Eye View Documentation: A Complete Guide Beyond the README

> Explore gods-eye-view documentation beyond the README. Discover detailed guides on architecture, performance, security, and testing within the docs directory.

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

---

**Yes, the gods-eye-view repository ships with extensive documentation beyond the README, including nine specialized Markdown files covering architecture, performance baselines, security models, and testing procedures stored in the `docs/` directory.**

The gods eye view documentation extends far beyond the initial [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md), providing developers with detailed technical specifications and operational guides. According to the bilawalsidhu/gods-eye-view source code, these supplemental materials are version-controlled alongside the implementation in the `docs/` folder to ensure accuracy and traceability.

## Core Documentation Files in the `docs/` Directory

The repository maintains eight critical documentation files that address specific operational domains:

- **[`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md)** – Detailed snapshot of the runtime architecture, including layer handling, first-run mission logic, ESC arbitration, render governor mechanics, and scene-playback policies.
- **[`PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/PERFORMANCE.md)** – Baseline performance measurements for startup times, cold-layer activation, and frame rates across various visual styles.
- **[`KNOWN-ISSUES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/KNOWN-ISSUES.md)** – Active runtime issues with documented mitigations and workarounds for traffic loading, CCTV panel persistence, and height-datum residuals.
- **[`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md)** – Comprehensive list of external and bundled data feeds, including OpenSky, AISStream, NASA FIRMS, and telegeography cables.
- **[`TESTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/TESTING.md)** – Procedures for running the unit-test suite, executing CI gate scripts, and validation expectations.
- **[`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md)** – Threat model documentation, proxy hardening guidelines, and secure token handling procedures.
- **[`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md)** – Guidelines for code contributions, testing requirements, and documentation standards.
- **[`CHANGELOG.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CHANGELOG.md)** – Chronological record of changes, releases, and migration notes.

## Architectural Specifications in CURRENT-STATE.md

The [`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md) file provides granular insight into the application’s runtime behavior, directly referencing implementation files.

### First-Run Mission Launcher

The launcher presents a UI card offering live contacts, space missions, and environmental layers during the initial visit. This component respects a persistent "don't show again" flag stored in both `localStorage` and `sessionStorage`.

### Render Governor System

Central throttling occurs in [`src/renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js), which manages per-frame animation via the `governorRequestRender` mechanism. This ensures that new visual updates request renders efficiently without overwhelming the browser’s event loop.

### Layer State Coordination

Durable layer enablement is managed by `LayerStateCoordinator._commitExplicit` in [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js). Layers toggle exclusively through user actions, voice commands, or tool interactions, preserving reproducible state across sessions.

### ESC Arbitration Rules

Three distinct rules govern how the Escape key dismisses the launcher or fullscreen surfaces, preventing accidental closure of critical UI components.

### Scene Playback Policy

The files [`src/scenes/director.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scenes/director.js) and [`src/scenes/scenePolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scenes/scenePolicy.js) enforce that shots apply only declared layers, preserve camera ownership, and avoid unintended tracking reinstatement.

### AIS Feed Health Monitoring

[`src/data/aisWatchdog.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/aisWatchdog.js) classifies AIS feed status into four states—loading, stale, down, and auth-failed—driving corresponding UI chips to indicate data health.

## Security, Performance, and Data Sources

Beyond architectural overviews, the gods eye view documentation includes operational-critical references.

**Security** documentation in [`SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/SECURITY.md) defines the threat model and proxy hardening strategies used in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) to secure OpenSky API communications. **Performance** baselines in [`PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/PERFORMANCE.md) establish measurable expectations for startup latency and rendering frame rates. **Data source** documentation details integration requirements for real-time feeds like AISStream and NASA FIRMS, including authentication and fallback behaviors.

## Developer Workflows and Testing

The [`TESTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/TESTING.md) and [`CONTRIBUTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CONTRIBUTING.md) files define the development lifecycle.

### Repository Setup

```bash

# Clone & install

git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
npm ci

# Configure optional OpenSky token

cp .env.example .env

# Edit .env to set OPENSKY_TOKEN=your_token

# Start development server

npm run dev

```

### QA Gate Execution

Run automated validation suites defined in [`TESTING.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/TESTING.md):

```bash
node scripts/qa-perf.mjs --url http://localhost:5173

```

These scripts exercise the performance gates and layer integrity checks required for CI acceptance.

## Programmatic Layer Control and Render Management

The documentation references specific APIs for runtime manipulation.

### Enabling Layers Programmatically

```javascript
import { setLayerVisibility } from './src/worldFocus.js';

// Activate the CCTV city layer
setLayerVisibility('cctv-city', true);

// Verify state through LayerStateCoordinator
const state = LayerStateCoordinator.getState();
console.log(state.enabledLayers); // ['cctv-city', …]

```

Source: [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) – layer-visibility helper utilized throughout the UI components.

### Requesting Renders via the Governor

```javascript
import { requestRender } from './src/renderGovernor.js';

// Trigger render after custom animation completion
myCustomAnimator.onComplete(() => requestRender());

```

Source: [`src/renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js) – central throttling point for all per-frame updates.

## Summary

- The gods eye view documentation encompasses nine specialized files in the `docs/` directory, covering architecture, performance, security, and testing.
- **CURRENT-STATE.md** provides implementation-aware architectural details, referencing [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js), [`src/renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js), and [`src/scenes/director.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/scenes/director.js).
- Programmatic control APIs like `setLayerVisibility` and `requestRender` are documented with precise source file attribution.
- Security, performance, and data source documentation provides operational guidelines for production deployments.
- Testing procedures include automated QA gate scripts (`scripts/qa-*.mjs`) for continuous integration validation.

## Frequently Asked Questions

### Where is the gods eye view documentation located beyond the README?

All supplemental documentation resides in the repository's `docs/` folder at the root level. These Markdown files are version-controlled alongside the source code, ensuring that any implementation change in `src/` is reflected in the corresponding architectural or operational documentation.

### How do I programmatically toggle layers using the documented API?

Import `setLayerVisibility` from [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) to control layer state programmatically. This function interacts with `LayerStateCoordinator._commitExplicit` to ensure durable state persistence across sessions, respecting the architectural constraints documented in [`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md).

### What performance benchmarks are documented for gods-eye-view?

[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md) establishes baseline measurements for startup latency, cold-layer activation times, and sustained frame rates across different visual styles. These metrics are validated through the `scripts/qa-perf.mjs` gate script, which CI pipelines execute against local development servers.

### How does the repository document security considerations?

[`docs/SECURITY.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/SECURITY.md) contains the complete threat model, including proxy hardening configurations found in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) and secure token handling procedures for external APIs like OpenSky. This documentation specifies how to configure `.env` files and manage authentication credentials without exposing secrets in client-side bundles.