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

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 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 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 file defines initial camera positions and layer visibility settings loaded on first launch. Meanwhile, 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.

// 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 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 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 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 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.

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