Does God's Eye View Support Real-Time Data? Architecture and Implementation Guide

Yes, God's Eye View fully supports real-time data through a multi-layered architecture that combines polling transports, WebSocket streaming, satellite propagation, and per-frame interpolation to deliver live aircraft, ships, satellites, and traffic on a 3-D globe.

God's Eye View is an open-source visualization platform that transforms periodic telemetry streams into fluid, real-time experiences. According to the bilawalsidhu/gods-eye-view source code, the application handles real-time data across seven distinct live feed categories, each with specialized transport and resilience mechanisms.

How Real-Time Data Works in God's Eye View

The real-time capability rests on three architectural pillars: transport adapters that fetch live data, watchdog state machines that ensure feed health, and render-layer interpolation that smooths intermittent updates into continuous motion.

Live Feed Transports and Polling Strategy

Most real-time layers in God's Eye View use scheduled polling rather than persistent connections. This design balances freshness against API rate limits and provider stability.

Data Source	Transport Type	Refresh Interval
Aircraft (OpenSky)	HTTP polling	15–30 seconds
Ships (AISStream)	WebSocket with watchdog	Event-driven, monitored for 120s silence
Satellites	Local SGP4 propagation	Computed per frame (60+ Hz)
Traffic (TomTom)	HTTP polling	Configured per provider
Earthquakes, CCTV	HTTP polling	Provider-dependent

The liveFlights.js module exemplifies this pattern. It polls the OpenSky Network API and pushes new records into the client's state store:

// src/data/liveFlights.js — live aircraft polling layer
const POLL_INTERVAL_MS = 15000;

export async function pollLiveFlights() {
  const response = await fetch('https://opensky-network.org/api/states/all');
  const states = await response.json();
  updateGlobalStore('liveFlights', states);
}

WebSocket Resilience: The AIS Watchdog Pattern

For streaming sources like AISStream (maritime vessel tracking), God's Eye View implements a data-centric liveness detector. Unlike naive heartbeat checks, the watchdog declared in aisWatchdog.js monitors actual telemetry flow, not socket state.

The state machine returns discrete actions that the transport layer executes:

// src/data/aisWatchdog.js — core state machine
export function createAisWatchdog() {
  let lastDataTimestamp = 0;
  let generation = 0;

  return {
    tick() {
      const now = Date.now();
      const silence = now - lastDataTimestamp;
      const actions = [];

      if (silence > 120000) actions.push({ type: 'stale' });
      if (silence > 300000) actions.push({ type: 'terminate', reason: 'timeout', generation });
      
      return actions;
    },
    onDataReceived() {
      lastDataTimestamp = Date.now();
      generation += 1;
      return { type: 'connect', generation };
    }
  };
}

This pattern ensures that transient network blips don't false-positive as feed failures, while genuine outages trigger controlled reconnection with monotonically increasing generation IDs.

Generation-ID Socket Management

The aisStreamAdapter.js file enforces a critical invariant: only the current generation's socket may affect the UI. This prevents race conditions where a slow, dying socket overwrite fresher data:

// src/data/aisStreamAdapter.js — generation-guarded WebSocket
const generationToSocket = new Map();

export function openAisWebSocket(generation) {
  const socket = new WebSocket(AIS_STREAM_URL);
  generationToSocket.set(generation, socket);
  
  socket.onmessage = (event) => {
    if (getCurrentGeneration() !== generation) {
      // Stale socket: ignore and terminate
      socket.close();
      generationToSocket.delete(generation);
      return;
    }
    processAisMessage(event.data);
  };
}

Orphaned sockets are automatically terminated, eliminating resource leaks from rapid reconnect cycles.

Real-Time Rendering: From Jerky Updates to Smooth Motion

Raw telemetry arrives too infrequently for fluid visualization. God's Eye View solves this through client-side interpolation and dead reckoning.

Per-Frame Position Interpolation

The render loop in flightInterpolation.js computes intermediate positions between successive fixes:

// src/scenes/flightInterpolation.js — smooth motion between updates
export function interpolatePosition(entity, currentTime) {
  const { lastFix, nextFix, lastTimestamp, nextTimestamp } = entity;
  const t = (currentTime - lastTimestamp) / (nextTimestamp - lastTimestamp);
  
  return {
    latitude: lerp(lastFix.lat, nextFix.lat, t),
    longitude: lerp(lastFix.lon, nextFix.lon, t),
    altitude: lerp(lastFix.alt, nextFix.alt, t)
  };
}

This runs at display refresh rate (typically 60 Hz), making 15-second polling intervals appear as continuous motion.

Dead Reckoning During Feed Gaps

When a feed temporarily stalls, deadReckoning.js extrapolates from the last known velocity and heading:

// src/scenes/deadReckoning.js — extrapolation fallback
export function deadReckon(entity, elapsedSinceLastFix) {
  const { lastVelocity, lastHeading } = entity;
  
  const distance = lastVelocity * elapsedSinceLastFix;
  const newPosition = geodesicOffset(
    entity.lastPosition,
    distance,
    lastHeading
  );
  
  return { ...newPosition, estimated: true };
}

Objects remain on-screen and roughly accurate until the feed recovers or the watchdog declares the layer stale.

Satellite Real-Time: Zero-Network Propagation

Satellite positions in God's Eye View are computed entirely client-side using SGP4 orbital propagation from Two-Line Elements (TLEs). This eliminates network dependency for the most numerous object category:

// src/data/satellites.js — local real-time orbit computation
import * as satellite from 'satellite.js';

export function getSatellitePosition(satrec, currentDate) {
  const positionAndVelocity = satellite.propagate(satrec, currentDate);
  const gmst = satellite.gstime(currentDate);
  const position = satellite.eciToGeodetic(positionAndVelocity.position, gmst);
  
  return {
    latitude: satellite.degreesLat(position.latitude),
    longitude: satellite.degreesLong(position.longitude),
    altitude: position.height
  };
}

Each animation frame calls this function for every tracked satellite, yielding sub-meter position accuracy without any API calls.

Security: Server-Side Proxy for Authenticated Feeds

Real-time access to commercial providers (OpenAI, Google Maps, TomTom live traffic) requires API keys. God's Eye View keeps these exclusively server-side through a Node.js proxy:

// src/server/proxy.js — secure credential management
app.get('/api/tomtom/traffic', async (req, res) => {
  const url = `https://api.tomtom.com/traffic/services/4/flowSegmentData/...?key=${TOMTOM_API_KEY}`;
  const response = await fetch(url);
  res.json(await response.json());
});

Clients receive live data without ever exposing credentials.

Enabling Real-Time Layers in Your Instance

To activate real-time visualization, enable the corresponding layers through the UI module:

// Enable live flights (15s polling begins automatically)
import { enableLayer } from './ui.js';
enableLayer('liveFlights');

// Enable AIS ship tracking (WebSocket with watchdog)
enableLayer('aisShips');

// Enable satellite propagation (client-side computation)
enableLayer('satellites');

Summary

• God's Eye View supports real-time data through polling transports, WebSocket streaming, and client-side orbital propagation.

• The aisWatchdog.js state machine distinguishes data liveness from connection state, preventing false failure detection.

• Generation-ID tracking in aisStreamAdapter.js eliminates race conditions and resource leaks during reconnection storms.

• Per-frame interpolation (flightInterpolation.js) and dead reckoning (deadReckoning.js) convert sparse telemetry into fluid visual motion.

• SGP4 propagation (satellites.js) enables unlimited satellite tracking without network overhead.

• Server-side proxying (src/server/proxy.js) secures API credentials while delivering live commercial data.

Frequently Asked Questions

What types of real-time data does God's Eye View support?

God's Eye View supports aircraft positions via OpenSky polling, maritime vessels via AISStream WebSocket, satellite orbits via SGP4 propagation, traffic flow via TomTom API, and various event feeds including earthquakes and CCTV streams. Each source uses a transport adapter matched to its update characteristics and reliability requirements.

How does God's Eye View handle temporary feed outages?

The application uses dead reckoning to extrapolate positions from last-known velocity and heading, keeping objects visible during gaps. Simultaneously, the watchdog monitors for extended silence—declaring feeds stale after 120 seconds and triggering reconnection after 300 seconds. This dual approach maintains visual continuity while ensuring eventual consistency.

Can satellite positions update in real-time without network calls?

Yes. Satellites use SGP4 orbital mechanics computed locally from TLEs (Two-Line Elements). The satellite.js library in src/data/satellites.js calculates precise geodetic coordinates every animation frame, typically 60 times per second, with zero network dependency after the initial TLE download.

Is real-time data available in self-hosted deployments?

All real-time capabilities function in self-hosted deployments, though some sources require API keys configured in the server proxy. OpenSky and SGP4-based satellite tracking work without credentials. Commercial feeds (TomTom, AISStream authenticated tiers) need key provisioning in src/server/proxy.js environment variables.

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