# What Is the Purpose of the `src/data/localdata/` Directory in God’s Eye View?

> Discover the purpose of the src/data/localdata directory in God's Eye View. It holds static JSON and GeoJSON files for offline data access and faster performance.

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

---

**The `src/data/localdata/` directory contains static, bundled data assets—including JSON lookup tables, GeoJSON spatial files, and deterministic test fixtures—that enable offline functionality and instant data access without requiring external API calls.**

In the **bilawalsidhu/gods-eye-view** repository, the `src/data/localdata/` folder serves as the central location for reference data that ships with the application bundle. These files provide immediate access to geographic information and configuration defaults while ensuring the interface remains functional during network outages or remote API failures.

## Core Purpose of the `src/data/localdata/` Directory

### Static Data Assets for Offline-First Architecture

The primary role of `src/data/localdata/` is to house **static, local-only data** that is packaged at build time rather than fetched at runtime. This directory contains machine-readable files such as [`country-codes.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/country-codes.json) and `earthquakes-sample.geojson` that the application imports directly via ES6 module syntax. Bundling these assets ensures that critical reference information and fallback datasets remain available even when the user has no network connectivity.

### Zero-Network Fallback Mechanism

Files stored here function as **graceful degradation layers** when external services fail. For example, if the remote earthquake visualization API returns a 500 error or times out, the application immediately falls back to the pre-bundled `earthquakes-sample.geojson` to maintain a functional user interface. This pattern eliminates single points of failure for core visualizations.

## Key Data Categories in `src/data/localdata/`

### Geographic and Spatial Data

The directory stores compact GeoJSON files that provide map geometry without HTTP latency. The `earthquakes-sample.geojson` file supplies a static dataset of seismic events used as a fallback when live feeds are unreachable, ensuring the mapping visualization always renders meaningful spatial data.

### Reference Lookup Tables

Small, frequently accessed dictionaries live here to optimize performance. The [`country-codes.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/country-codes.json) file maps ISO country codes to human-readable names, allowing functions like `getCountryName(iso)` to execute synchronous lookups without awaiting API responses. Similar tables may include airport ICAO codes or vessel identification lists.

### Configuration Defaults and Test Fixtures

**Default view states** and deterministic **test data** also reside in this folder. The [`default-view.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/default-view.json) file defines initial camera positions and layer visibility settings loaded on first launch. Meanwhile, [`fixture-ais-sample.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/fixture-ais-sample.json) provides static AIS vessel data that the test suite imports directly, guaranteeing repeatable test runs without network dependencies or external service mocks.

## Implementation Patterns in God’s Eye View

The codebase leverages direct ES6 imports to consume these static assets, enabling webpack or Vite to bundle the JSON into the application JavaScript. When remote data is unavailable, functions catch errors and return the local fallback.

```javascript
// Synchronous lookup against bundled data
import countryCodes from './localdata/country-codes.json';

export function getCountryName(iso) {
  return countryCodes[iso] ?? 'Unknown';
}

// Async fetch with local fallback for spatial data
import earthquakeSample from './localdata/earthquakes-sample.geojson';

export async function loadEarthquakeOverlay() {
  try {
    const remote = await fetch('/api/earthquakes');
    return await remote.json();
  } catch (_) {
    // Return bundled static version when network fails
    return earthquakeSample;
  }
}

```

## Architectural Benefits of the Local Data Pattern

- **Self-contained deployment**: All files in `src/data/localdata/` are packaged with the production build, allowing the application to start instantly in sandboxed or offline environments without external dependencies.

- **Performance optimization**: Reading a local JSON object from the bundle executes orders of magnitude faster than HTTP requests, eliminating latency for reference data lookups like country code resolution.

- **Operational reliability**: When remote APIs fail or the user lacks connectivity, the application degrades gracefully to local data, ensuring the UI never presents empty states for critical features.

- **Deterministic testing**: By importing fixtures such as [`fixture-ais-sample.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/fixture-ais-sample.json) directly from the source tree, the test harness runs with predictable data sets, removing flakiness associated with live service availability.

## Summary

- The `src/data/localdata/` directory stores **static, bundled data assets**—including GeoJSON, JSON lookup tables, and configuration files—that ship with the God’s Eye View application.
- Files like [`country-codes.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/country-codes.json) and `earthquakes-sample.geojson` provide **instant synchronous access** to reference data and fallback spatial information.
- The architecture enables **offline-first functionality** through patterns like the `loadEarthquakeOverlay()` function, which returns local data when remote APIs are unavailable.
- Test fixtures such as [`fixture-ais-sample.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/fixture-ais-sample.json) ensure **deterministic, network-independent testing** by supplying static datasets directly from the source tree.

## Frequently Asked Questions

### What types of files belong in `src/data/localdata/`?

This directory contains static JSON configurations, GeoJSON spatial datasets, lookup tables like ISO country codes, and deterministic test fixtures. These assets are bundled at build time and imported directly into the application code using ES6 module syntax.

### How does God’s Eye View handle missing external APIs?

The codebase implements fallback patterns where functions catch network errors and return locally bundled data instead. For example, if the earthquake API fails, `loadEarthquakeOverlay()` returns the pre-packaged `earthquakes-sample.geojson` to maintain visualization continuity.

### Can I modify files in `src/data/localdata/` without rebuilding?

No. Because these files are imported directly into the JavaScript bundle using statements like `import countryCodes from './localdata/country-codes.json'`, any modifications require a rebuild to compile the changes into the deployed application assets.

### Why are test fixtures stored in `src/data/localdata/` instead of a separate tests folder?

Placing [`fixture-ais-sample.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/fixture-ais-sample.json) alongside production data ensures the test suite uses identical import patterns and data structures as the production code. This co-location guarantees deterministic test execution without requiring complex network mocking or external service dependencies.