# Main Directories in the Gods-Eye-View Repository: Complete Structure Guide

> Explore the gods-eye-view repository structure. Understand the main directories src, tools, public, config, and docs for effective project navigation and development.

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

---

**The gods-eye-view repository is organized into five primary directories—`src/`, `tools/`, `public/`, `config/`, and `docs/`—each handling distinct responsibilities from runtime JavaScript modules to offline processing scripts and static assets.**

The gods-eye-view project follows a clean architectural separation where runtime logic, auxiliary tooling, and configuration data live in distinct top-level folders. Understanding the main directories in the gods-eye-view repository helps developers navigate the codebase efficiently, whether they are modifying the core UI, adding new CCTV data sources, or troubleshooting documented issues. This guide breaks down each directory's purpose with specific file references and practical code examples drawn from the source.

## src/ Directory: Core Application Source

The **`src/`** directory contains the JavaScript/ES-module implementation of the application's runtime logic. This folder houses the UI components, map handling modules, policy enforcement, utilities, and test suites that power the gods-eye-view interface.

Key files in this directory define the application's entry point and core functionality:

- **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)** – Boots the application and wires together the UI, map engine, and policy systems
- **[`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js)** – Implements camera movement, handoff logic, and smooth view transitions
- **[`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js)** – Manages the heads-up display for altitude, location telemetry, and real-time data overlays

To import functionality from the core source, reference the module path relative to your file:

```javascript
import { hud } from './src/hud.js';
hud.initialize();

```

## tools/ Directory: Offline Processing Utilities

The **`tools/`** directory stores helper scripts and standalone HTML pages designed for offline data processing tasks. These utilities operate outside the main application runtime to generate assets like street-view panoramas or render Cesium scenes to static images.

The **`tools/cesium-render.mjs`** script exemplifies this directory's purpose, rendering Cesium 3D scenes to PNG files without requiring a browser environment. Execute these scripts directly via Node.js:

```bash
node tools/cesium-render.mjs --input data/scene.json --output render.png

```

Scripts in this folder typically process raw geographic data or generate pre-rendered tiles for later consumption by the main application.

## public/ Directory: Static Assets

The **`public/`** directory serves static assets directly to the browser without modification. This folder contains SVG icons, the entry-point HTML file, and other public resources that the application serves as-is.

Reference these assets in your markup using standard relative paths:

```html
<img src="public/logo.svg" alt="Gods-Eye-View Logo" />

```

Keeping static assets isolated ensures build tools and web servers handle caching and delivery separately from compiled JavaScript logic.

## config/ Directory: External Data Sources

The **`config/`** directory holds JSON configuration files that define external data integrations, particularly CCTV feeds for different metropolitan areas. Each city typically maintains its own configuration file specifying camera endpoints, coordinates, and metadata.

The **[`config/cctv_sources.shinjuku.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/config/cctv_sources.shinjuku.json)** file demonstrates the schema used for Tokyo's Shinjuku district camera network. Import these configurations in ES modules using JSON assertions:

```javascript
import cctvConfig from './config/cctv_sources.shinjuku.json' assert { type: 'json' };
console.log(cctvConfig);

```

Separating configuration from source code allows operators to update camera feeds or add new city datasets without redeploying the application logic.

## docs/ Directory: Project Documentation

The **`docs/`** directory aggregates non-code documentation including performance notes, authentication guides, and current project state summaries. This folder tracks known limitations, architectural decisions, and operational procedures separate from inline code comments.

The **[`docs/KNOWN-ISSUES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/KNOWN-ISSUES.md)** file catalogs current bugs and limitations, serving as the primary reference for troubleshooting and roadmap planning.

## Summary

- The **`src/`** directory contains the core JavaScript/ES modules for UI, maps, and camera logic, with [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) serving as the application entry point.
- The **`tools/`** directory provides offline processing scripts like `cesium-render.mjs` for generating static assets without browser runtime.
- The **`public/`** directory hosts static files including SVG icons and the entry-point HTML served directly to clients.
- The **`config/`** directory stores JSON configurations for external data sources such as CCTV feeds, exemplified by [`cctv_sources.shinjuku.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctv_sources.shinjuku.json).
- The **`docs/`** directory maintains project documentation including [`KNOWN-ISSUES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/KNOWN-ISSUES.md) and performance guides.

## Frequently Asked Questions

### Where is the application entry point in the gods-eye-view repository?

The application entry point resides at **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)**, which initializes the UI components, map engine, and policy systems when the application boots according to the repository source code.

### How do I add a new city’s CCTV data to the repository?

Create a new JSON file in the **`config/`** directory following the schema established in [`cctv_sources.shinjuku.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cctv_sources.shinjuku.json), specifying camera endpoints, geographic coordinates, and metadata for the city.

### What is the purpose of the tools/ directory?

The **`tools/`** directory contains helper scripts and HTML pages for offline data processing, such as generating street-view panoramas or rendering Cesium scenes to PNG files via command-line utilities like `cesium-render.mjs`.

### Where should static assets like logos and icons be stored?

Store static assets in the **`public/`** directory, which serves these files directly to the browser without build-time processing, ensuring efficient caching and delivery of resources like the `logo.svg` file.