Where to Find Design Documentation for Gods Eye View: Complete File Guide

The design documentation for Gods Eye View is located in the docs/superpowers/specs/ directory, with high-level architectural overviews maintained in docs/CURRENT-STATE.md and detailed component specifications stored in dated markdown files.

The open-source Gods Eye View project (available at bilawalsidhu/gods-eye-view) maintains its design documentation directly within the repository's documentation hierarchy. All specifications for gizmos, data-height handling, and system architecture are written in markdown and version-controlled alongside the source code, ensuring the design documentation for Gods Eye View remains accessible and synchronized with implementation changes.

Location of Design Documentation in the Repository

The design documentation for Gods Eye View follows a structured hierarchy under the docs/ folder at the repository root. According to the source code analysis, the main entry point for understanding the current system architecture is docs/CURRENT-STATE.md, which provides a high-level map of runtime components and their relationships to the source tree.

For detailed specifications of individual features and components, navigate to docs/superpowers/specs/. This directory contains timestamped markdown files that document specific gizmos, datum handlers, and rendering systems implemented in the codebase.

Component Specification Files in docs/superpowers/specs/

The docs/superpowers/specs/ directory contains granular design documents for specific system capabilities. Each file follows a dated naming convention and targets a distinct subsystem.

CCTV Viewshed Gizmo Design

The file docs/superpowers/specs/2026-07-05-cctv-viewshed-gizmo-design.md details the calibration gizmo used for CCTV camera viewshed analysis. This specification defines the interaction patterns and geometric calculations used by the viewshed visualization system.

You can view this document directly at:
https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/superpowers/specs/2026-07-05-cctv-viewshed-gizmo-design.md

Entity Height Datum Design

Located at docs/superpowers/specs/2026-07-05-entity-height-datum-design.md, this document specifies height-datum handling algorithms and terrain alignment strategies for entities rendered in the 3D viewport.

Direct link:
https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/superpowers/specs/2026-07-05-entity-height-datum-design.md

CCTV Ambient Cards Design

The docs/superpowers/specs/2026-07-29-cctv-ambient-cards-design.md file outlines the Level-of-Detail (LOD) architecture for static ambient cards in CCTV visualizations, including tier selection logic and rendering optimizations.

Access it here:
https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/superpowers/specs/2026-07-29-cctv-ambient-cards-design.md

Vessel Datum Design

For AIS data handling and coordinate conversion, refer to docs/superpowers/specs/2026-07-27-vessel-datum-design.md. This specification covers datum conversion pipelines and vessel tracking data structures.

View the specification:
https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/superpowers/specs/2026-07-27-vessel-datum-design.md

High-Level Architecture Overview

Before diving into individual specs, review docs/CURRENT-STATE.md for the comprehensive architectural overview. As implemented in bilawalsidhu/gods-eye-view, this document maps runtime components to their physical locations in the source tree and explains how the superpower modules integrate with the core engine.

Access the overview:
https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md

Accessing Design Documentation Programmatically

You can fetch design specifications directly from the repository to display within custom UI panels or internal tools. The following JavaScript function loads a spec file from the raw GitHub content URL and parses the markdown:

// Example: load a design spec markdown file and render it as HTML
async function loadDesignSpec(specPath) {
  const response = await fetch(`https://raw.githubusercontent.com/bilawalsidhu/gods-eye-view/main/${specPath}`);
  if (!response.ok) throw new Error('Failed to load spec');
  const markdown = await response.text();
  // Convert markdown → HTML (you might use a library like marked)
  const html = marked.parse(markdown);
  document.getElementById('design-spec').innerHTML = html;
}

// Load the CCTV Viewshed Gizmo design spec
loadDesignSpec('docs/superpowers/specs/2026-07-05-cctv-viewshed-gizmo-design.md');

This approach is particularly useful when building documentation browsers or in-app help systems that need to reference the latest design decisions from the repository.

Source Code References to Design Docs

The codebase maintains explicit links between implementation and documentation. For example, src/data/cctvViewshed.js contains comments that reference the CCTV-viewshed-gizmo design spec path, ensuring developers can trace runtime logic back to its architectural specification. These cross-references validate that the design documentation for Gods Eye View remains synchronized with the actual implementation.

Summary

• The primary design documentation for Gods Eye View resides in docs/CURRENT-STATE.md (architectural overview) and docs/superpowers/specs/ (component specifications).
• Individual specifications use dated filenames (e.g., 2026-07-05-cctv-viewshed-gizmo-design.md) to track the evolution of specific gizmos and datum handlers.
• Source files like src/data/cctvViewshed.js include comments linking directly to relevant design documents in the docs/superpowers/specs/ directory.
• You can programmatically access specs using raw GitHub content URLs for integration into custom tooling or documentation browsers.

Frequently Asked Questions

Where is the main architecture document for Gods Eye View?

The high-level architecture is documented in docs/CURRENT-STATE.md at the repository root. This file provides the comprehensive component map and explains how superpower modules integrate with the core system according to the bilawalsidhu/gods-eye-view source structure.

How do I find the specification for a specific gizmo like CCTV viewshed?

Navigate to docs/superpowers/specs/2026-07-05-cctv-viewshed-gizmo-design.md in the repository. This markdown file contains the detailed design for the CCTV viewshed calibration gizmo, including geometric calculations and interaction patterns referenced by src/data/cctvViewshed.js.

Can I fetch design documentation programmatically inside my application?

Yes. Use a standard fetch request to https://raw.githubusercontent.com/bilawalsidhu/gods-eye-view/main/ followed by the relative path to the spec file (e.g., docs/superpowers/specs/2026-07-05-entity-height-datum-design.md). Parse the returned markdown using a library like marked to render it as HTML in your UI.

Are the design documents version controlled with the code?

Yes. All design documentation lives in the docs/ directory of the bilawalsidhu/gods-eye-view repository and is version-controlled alongside the source code, ensuring documentation stays synchronized with implementation changes.

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