Gods Eye View Documentation: A Complete Guide Beyond the README

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, 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 – Detailed snapshot of the runtime architecture, including layer handling, first-run mission logic, ESC arbitration, render governor mechanics, and scene-playback policies.
• PERFORMANCE.md – Baseline performance measurements for startup times, cold-layer activation, and frame rates across various visual styles.
• KNOWN-ISSUES.md – Active runtime issues with documented mitigations and workarounds for traffic loading, CCTV panel persistence, and height-datum residuals.
• DATA_SOURCES.md – Comprehensive list of external and bundled data feeds, including OpenSky, AISStream, NASA FIRMS, and telegeography cables.
• TESTING.md – Procedures for running the unit-test suite, executing CI gate scripts, and validation expectations.
• SECURITY.md – Threat model documentation, proxy hardening guidelines, and secure token handling procedures.
• CONTRIBUTING.md – Guidelines for code contributions, testing requirements, and documentation standards.
• CHANGELOG.md – Chronological record of changes, releases, and migration notes.

Architectural Specifications in CURRENT-STATE.md

The 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, 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. 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 and 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 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 defines the threat model and proxy hardening strategies used in vite.config.js to secure OpenSky API communications. Performance baselines in 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 and CONTRIBUTING.md files define the development lifecycle.

Repository Setup

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

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

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 – layer-visibility helper utilized throughout the UI components.

Requesting Renders via the Governor

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

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

Source: 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, src/renderGovernor.js, and 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 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.

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

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 contains the complete threat model, including proxy hardening configurations found in 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.

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