How Is the Code Organized Within the gods-eye-view Repository?

The gods-eye-view repository follows a strict layered architecture that separates runtime browser code, build-time asset generation, CI automation, configuration data, and documentation into distinct top-level directories.

The bilawalsidhu/gods-eye-view project is a modular web application for city-scale 3-D visualization and CCTV feed management. Understanding how the code is organized within the gods-eye-view repository reveals a clear separation of concerns: runtime modules live in src/, data-processing scripts reside in tools/, and configuration is externalized into JSON files under config/. This structure enables independent development of visualization features, asset pipelines, and city-specific deployment settings.

Top-Level Directory Layout

The repository root contains seven primary directories and standard Node.js scaffolding files. Each directory serves a specific phase of the application lifecycle, from development to runtime execution.

• src/ – Contains all ESM modules that execute in the browser, including camera controllers, HUD renderers, and weather mathematics.
• tools/ – Houses Node.js scripts for preprocessing data, such as stitching panoramic images and generating Cesium 3-D tiles.
• scripts/ – Holds QA and CI automation modules for regression testing and performance benchmarking.
• public/ – Stores static assets served unchanged, including SVG icons and the index.html entry point.
• config/ – Provides JSON configuration files that define CCTV sources per city without code modification.
• docs/ – Contains markdown documentation covering performance constraints, known issues, and project state.
• Root files – Standard metadata including package.json, vite.config.js, .env.example, README.md, and CHANGELOG.md.

Core Application Modules (src/)

The src/ directory contains the heart of the application. Modules here handle real-time camera manipulation, heads-up display rendering, and CCTV feed selection logic.

World Focus and Camera Control

The worldFocus.js module orchestrates high-level camera movements and world-focus animations. It coordinates with camera.js, which provides low-level camera verbs and hand-off logic, and cameraVerbs.js, which implements specific movement primitives.

import { initWorldFocus } from "./src/worldFocus.js";
import { initCamera } from "./src/camera.js";

await initWorldFocus({ target: "shinjuku" });
await initCamera({ position: [0, 100, 200] });

HUD and Visual Effects

The hud.js module renders on-screen status panels and icons. Complementary mathematical operations for weather visualization reside in weatherEffectsMath.js, which calculates rain and fog effects, while cockpitMath.js handles geometric calculations for the cockpit view markup.

CCTV Policy and Focus Requests

CCTV feed selection follows a strict policy engine. The cctvFocusRequest.js module accepts user requests, but cctvFocusPolicy.js determines which stream to display based on priority and availability rules.

import { getCCTVForTarget } from "./src/cctvFocusRequest.js";

const feed = await getCCTVForTarget({
  city: "shinjuku",
  priority: "high",
});

Testing Infrastructure

Unit tests are co-located with implementation files using the *.test.mjs naming convention. This Jest-style organization ensures that src/worldFocus.js has a corresponding test module alongside it, guaranteeing functional correctness for core visualization modules.

Asset-Generation Tools (tools/)

The tools/ directory contains standalone ESM scripts that run outside the browser to prepare data consumed at runtime. These are invoked manually or via CI pipelines.

• streetview-panorama.mjs – Stitches Google Street View tiles into single panoramic images.
• streetview-headings.mjs – Extracts heading metadata from street-view data.
• sat-ortho.mjs – Generates orthophotos from satellite imagery.
• cesium-render.mjs – Produces Cesium 3-D tiles from raw geospatial data, accompanied by cesium-render.html for visualization testing.

node tools/streetview-panorama.mjs \
  --location "35.6895,139.6917" \
  --output ./public/panorama.jpg

Automation and QA (scripts/)

Development workflows rely on the scripts/ directory for automation. These modules handle regression testing, performance QA pipelines, and data import routines (such as opensky-import-client.sh). Unlike the runtime code in src/, these scripts are development dependencies that support continuous integration but are excluded from the production bundle.

Configuration and Static Assets

Data-Driven Configuration (config/)

City-specific CCTV endpoints are externalized into JSON files, allowing the application to support new locations without code changes. Examples include cctv_sources.shinjuku.json and cctv_sources.austin.json, which define feed URLs and metadata for their respective cities.

Static Web Assets (public/)

The public/ directory contains immutable assets copied directly to the build output by Vite. This includes SVG icons (logo.svg, pin.svg, mic.svg, location.svg) and the index.html entry point that bootstraps the application.

Project Documentation (docs/)

Technical debt and performance constraints are documented in markdown files:

• PERFORMANCE.md – Optimization guidelines and rendering budgets.
• KNOWN-ISSUES.md – Documented bugs and workarounds.
• CURRENT-STATE.md – Snapshot of active development priorities.

Build Configuration

The vite.config.js file orchestrates the build process, handling module aliasing and asset optimization. Environment variables are templated via .env.example, providing placeholders for API keys and CCTV endpoints without hardcoding credentials.

Summary

• The gods-eye-view repository separates runtime code (src/), build tools (tools/), and automation (scripts/) into distinct directories.
• Core visualization logic resides in src/worldFocus.js and src/camera.js, while policy decisions are handled by src/cctvFocusPolicy.js.
• Configuration is data-driven via JSON files in config/, enabling city-specific deployments without code modifications.
• Static assets live in public/ and are served unchanged, while documentation in docs/ tracks performance constraints and known issues.
• Tests are co-located with source files using the *.test.mjs pattern to maintain module-level quality assurance.

Frequently Asked Questions

What is the purpose of the tools/ directory in gods-eye-view?

The tools/ directory contains Node.js scripts that run during the build phase to preprocess geospatial data. These include streetview-panorama.mjs for stitching panoramic images and cesium-render.mjs for generating 3-D tiles. These scripts prepare assets that the runtime code in src/ consumes, keeping heavy computation out of the browser.

How does the repository handle city-specific CCTV configurations?

City-specific settings are stored as JSON files in the config/ directory, such as cctv_sources.shinjuku.json. The runtime code in src/cctvFocusRequest.js loads these files dynamically, allowing operators to add new cities by creating new JSON configurations without modifying the JavaScript source code.

Where is the entry point for the gods-eye-view web application?

The browser entry point is public/index.html, which is copied unchanged to the build output by Vite. This HTML file bootstraps the ESM application by loading the bundled JavaScript from src/, starting with modules like worldFocus.js and camera.js.

How is testing organized within the repository?

Tests use a co-location pattern within src/, where each module has a corresponding *.test.mjs file. The scripts/ directory contains execution wrappers like run-unit-tests.mjs that invoke these tests, typically using a Jest-style runner to verify camera logic, HUD rendering, and CCTV policy decisions.

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