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

> Explore the gods-eye-view repository's layered architecture. Discover how code is organized into separate directories for runtime, build, CI, config, and docs.

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

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json), [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js), `.env.example`, [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md), and [`CHANGELOG.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/worldFocus.js)** module orchestrates high-level camera movements and world-focus animations. It coordinates with **[`camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/camera.js)**, which provides low-level camera verbs and hand-off logic, and **[`cameraVerbs.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cameraVerbs.js)**, which implements specific movement primitives.

```javascript
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/hud.js)** module renders on-screen status panels and icons. Complementary mathematical operations for weather visualization reside in **[`weatherEffectsMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/weatherEffectsMath.js)**, which calculates rain and fog effects, while **[`cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusRequest.js)** module accepts user requests, but **[`cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctvFocusPolicy.js)** determines which stream to display based on priority and availability rules.

```javascript
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cesium-render.html)** for visualization testing.

```bash
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctv_sources.shinjuku.json)** and **[`cctv_sources.austin.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/index.html)** entry point that bootstraps the application.

### Project Documentation (`docs/`)

Technical debt and performance constraints are documented in markdown files:
- **[`PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/PERFORMANCE.md)** – Optimization guidelines and rendering budgets.
- **[`KNOWN-ISSUES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/KNOWN-ISSUES.md)** – Documented bugs and workarounds.
- **[`CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/CURRENT-STATE.md)** – Snapshot of active development priorities.

## Build Configuration

The [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js)** and **[`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js)**, while policy decisions are handled by **[`src/cctvFocusPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctv_sources.shinjuku.json)**. The runtime code in [`src/cctvFocusRequest.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/worldFocus.js) and [`camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.