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

> Discover if gods-eye-view supports real-time data. Learn about its multi-layered architecture combining polling, WebSockets, and interpolation for live global tracking.

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

---

**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](https://github.com/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/liveFlights.js) module exemplifies this pattern. It polls the OpenSky Network API and pushes new records into the client's state store:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/aisWatchdog.js) monitors actual telemetry flow, not socket state.

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

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/flightInterpolation.js) computes intermediate positions between successive fixes:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/deadReckoning.js) extrapolates from the last known velocity and heading:

```javascript
// 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:

```javascript
// 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:

```javascript
// 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:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/aisStreamAdapter.js) eliminates race conditions and resource leaks during reconnection storms.

- **Per-frame interpolation** ([`flightInterpolation.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/flightInterpolation.js)) and **dead reckoning** ([`deadReckoning.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/deadReckoning.js)) convert sparse telemetry into fluid visual motion.

- **SGP4 propagation** ([`satellites.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/satellites.js)) enables unlimited satellite tracking without network overhead.

- **Server-side proxying** ([`src/server/proxy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/satellite.js) library in [`src/data/satellites.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/server/proxy.js) environment variables.