# kevtoe/worldview architecture

> Architecture diagram of the GitHub repository kevtoe/worldview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevtoe/worldview
- Repository: https://github.com/kevtoe/worldview

## Overview

Worldview is a live situational-awareness dashboard: users open a 3D globe, enable data layers, inspect tracked entities and CCTV, and adjust tactical display modes. The frontend polls or propagates public-source data, renders it as globe overlays, and presents status and event feeds; an Express proxy caches and serves several feeds. The README documents additional integrations and capabilities beyond the sampled excerpts, so those are shown as documented relationships rather than claims of source inspection.

Main entry points: [`src/App.tsx`](https://github.com/kevtoe/worldview/blob/main/src/App.tsx) (App Orchestrator), [`server/index.js`](https://github.com/kevtoe/worldview/blob/main/server/index.js) (API Proxy), [`src/components/globe/GlobeViewer.tsx`](https://github.com/kevtoe/worldview/blob/main/src/components/globe/GlobeViewer.tsx) (3D Globe), [`src/hooks/useFlights.ts`](https://github.com/kevtoe/worldview/blob/main/src/hooks/useFlights.ts) (Flight Feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Dashboard"]
  node_app["App Orchestrator<br/>[App.tsx]"]
  node_globe["3D Globe<br/>[GlobeViewer.tsx]"]
  node_entitypick["Entity Selection"]
  node_shader["Postprocessing Shaders<br/>[postprocess.ts]"]
end

subgraph group_layers["Globe Layers"]
  node_flightlayer["Flight Overlay<br/>[FlightLayer.tsx]"]
  node_satlayer["Satellite Overlay<br/>[SatelliteLayer.tsx]"]
  node_quake_layer["Earthquake Overlay"]
  node_traffic_layer["Traffic Overlay<br/>[TrafficLayer.tsx]"]
  node_ship_layer["Ship Overlay<br/>[ShipLayer.tsx]"]
  node_cctv_layer["CCTV Overlay<br/>[CCTVLayer.tsx]"]
end

subgraph group_data["Data Acquisition"]
  node_flightdata["Flight Feed<br/>[useFlights.ts]"]
  node_satdata["Satellite Propagation<br/>[useSatellites.ts]"]
  node_quakedata["Earthquake Feed<br/>[useEarthquakes.ts]"]
  node_trafficdata["Traffic Simulation<br/>[useTraffic.ts]"]
  node_shipdata["AIS Vessel Feed<br/>[useShips.ts]"]
  node_cctvdata["Camera Feed<br/>[useCameras.ts]"]
  node_roads["Sydney Road Data<br/>[sydneyRoads.js]"]
  node_visibility["Page Visibility<br/>[usePageVisible.ts]"]
  node_camera_types["Camera Data Types<br/>[camera.ts]"]
end

subgraph group_backend["API Backend"]
  node_api["API Proxy<br/>[index.js]"]
  node_api_entry["API Entry<br/>[index.js]"]
end

subgraph group_interface["Operator Interface"]
  node_ops["Operations Controls"]
  node_intel["Intel Feed<br/>[IntelFeed.tsx]"]
  node_cctvpanel["CCTV Panel<br/>[CCTVPanel.tsx]"]
  node_status["Status Bar<br/>[StatusBar.tsx]"]
  node_audio["Tactical Audio<br/>[audio.ts]"]
end

node_operator(("Operator"))
node_earth_data(("Public Data Sources"))
node_ais(("AISStream.io"))

node_operator -->|"opens dashboard"| node_app
node_app -->|"mounts"| node_globe
node_app -->|"renders"| node_flightlayer
node_app -->|"renders"| node_satlayer
node_app -->|"renders"| node_quake_layer
node_app -->|"renders"| node_traffic_layer
node_app -->|"renders"| node_ship_layer
node_app -->|"renders"| node_cctv_layer
node_globe -->|"handles picks"| node_entitypick
node_globe -->|"applies effects"| node_shader
node_flightlayer -->|"renders data"| node_flightdata
node_satlayer -->|"renders data"| node_satdata
node_quake_layer -->|"renders data"| node_quakedata
node_traffic_layer -->|"renders data"| node_trafficdata
node_ship_layer -->|"renders data"| node_shipdata
node_cctv_layer -->|"renders data"| node_cctvdata
node_flightdata -->|"checks visibility"| node_visibility
node_shipdata -->|"checks visibility"| node_visibility
node_flightdata -->|"fetches feed"| node_api
node_trafficdata -->|"requests roads"| node_api
node_shipdata -->|"fetches vessels"| node_api
node_cctvdata -->|"fetches cameras"| node_api
node_satdata -->|"loads TLEs"| node_earth_data
node_quakedata -->|"loads events"| node_earth_data
node_api -->|"collects vessel data"| node_ais
node_api -->|"proxies feeds"| node_earth_data
node_api_entry -->|"delegates to"| node_api
node_api -->|"uses road data"| node_roads
node_app -->|"renders controls"| node_ops
node_app -->|"renders feed"| node_intel
node_app -->|"renders panel"| node_cctvpanel
node_app -->|"renders status"| node_status
node_ops -->|"selects mode"| node_shader
node_operator -->|"selects entity"| node_entitypick
node_cctvdata -->|"normalizes as"| node_camera_types
node_cctvpanel -->|"displays feeds"| node_camera_types
node_app -->|"plays interface cues"| node_audio

click node_app "https://github.com/kevtoe/worldview/blob/main/src/App.tsx"
click node_globe "https://github.com/kevtoe/worldview/blob/main/src/components/globe/GlobeViewer.tsx"
click node_entitypick "https://github.com/kevtoe/worldview/blob/main/src/components/globe/EntityClickHandler.tsx"
click node_flightlayer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/FlightLayer.tsx"
click node_satlayer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/SatelliteLayer.tsx"
click node_quake_layer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/EarthquakeLayer.tsx"
click node_traffic_layer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/TrafficLayer.tsx"
click node_ship_layer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/ShipLayer.tsx"
click node_cctv_layer "https://github.com/kevtoe/worldview/blob/main/src/components/layers/CCTVLayer.tsx"
click node_flightdata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useFlights.ts"
click node_satdata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useSatellites.ts"
click node_quakedata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useEarthquakes.ts"
click node_trafficdata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useTraffic.ts"
click node_shipdata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useShips.ts"
click node_cctvdata "https://github.com/kevtoe/worldview/blob/main/src/hooks/useCameras.ts"
click node_roads "https://github.com/kevtoe/worldview/blob/main/server/data/sydneyRoads.js"
click node_api "https://github.com/kevtoe/worldview/blob/main/server/index.js"
click node_api_entry "https://github.com/kevtoe/worldview/blob/main/api/index.js"
click node_ops "https://github.com/kevtoe/worldview/blob/main/src/components/ui/OperationsPanel.tsx"
click node_intel "https://github.com/kevtoe/worldview/blob/main/src/components/ui/IntelFeed.tsx"
click node_cctvpanel "https://github.com/kevtoe/worldview/blob/main/src/components/ui/CCTVPanel.tsx"
click node_status "https://github.com/kevtoe/worldview/blob/main/src/components/ui/StatusBar.tsx"
click node_shader "https://github.com/kevtoe/worldview/blob/main/src/shaders/postprocess.ts"
click node_audio "https://github.com/kevtoe/worldview/blob/main/src/lib/audio.ts"
click node_visibility "https://github.com/kevtoe/worldview/blob/main/src/hooks/usePageVisible.ts"
click node_camera_types "https://github.com/kevtoe/worldview/blob/main/src/types/camera.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_globe,node_entitypick,node_shader toneBlue
class node_flightlayer,node_satlayer,node_quake_layer,node_traffic_layer,node_ship_layer,node_cctv_layer toneAmber
class node_flightdata,node_satdata,node_quakedata,node_trafficdata,node_shipdata,node_cctvdata,node_roads,node_visibility,node_camera_types toneMint
class node_api,node_api_entry toneRose
class node_ops,node_intel,node_cctvpanel,node_status,node_audio,node_operator,node_earth_data,node_ais toneIndigo
```

## Components

### Dashboard

- [App Orchestrator](https://github.com/kevtoe/worldview/blob/main/src/App.tsx): `src/App.tsx`
- [3D Globe](https://github.com/kevtoe/worldview/blob/main/src/components/globe/GlobeViewer.tsx): `src/components/globe/GlobeViewer.tsx`
- [Entity Selection](https://github.com/kevtoe/worldview/blob/main/src/components/globe/EntityClickHandler.tsx): `src/components/globe/EntityClickHandler.tsx`
- [Postprocessing Shaders](https://github.com/kevtoe/worldview/blob/main/src/shaders/postprocess.ts): `src/shaders/postprocess.ts`

### Globe Layers

- [Flight Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/FlightLayer.tsx): `src/components/layers/FlightLayer.tsx`
- [Satellite Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/SatelliteLayer.tsx): `src/components/layers/SatelliteLayer.tsx`
- [Earthquake Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/EarthquakeLayer.tsx): `src/components/layers/EarthquakeLayer.tsx`
- [Traffic Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/TrafficLayer.tsx): `src/components/layers/TrafficLayer.tsx`
- [Ship Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/ShipLayer.tsx): `src/components/layers/ShipLayer.tsx`
- [CCTV Overlay](https://github.com/kevtoe/worldview/blob/main/src/components/layers/CCTVLayer.tsx): `src/components/layers/CCTVLayer.tsx`

### Data Acquisition

- [Flight Feed](https://github.com/kevtoe/worldview/blob/main/src/hooks/useFlights.ts): `src/hooks/useFlights.ts`
- [Satellite Propagation](https://github.com/kevtoe/worldview/blob/main/src/hooks/useSatellites.ts): `src/hooks/useSatellites.ts`
- [Earthquake Feed](https://github.com/kevtoe/worldview/blob/main/src/hooks/useEarthquakes.ts): `src/hooks/useEarthquakes.ts`
- [Traffic Simulation](https://github.com/kevtoe/worldview/blob/main/src/hooks/useTraffic.ts): `src/hooks/useTraffic.ts`
- [AIS Vessel Feed](https://github.com/kevtoe/worldview/blob/main/src/hooks/useShips.ts): `src/hooks/useShips.ts`
- [Camera Feed](https://github.com/kevtoe/worldview/blob/main/src/hooks/useCameras.ts): `src/hooks/useCameras.ts`
- [Sydney Road Data](https://github.com/kevtoe/worldview/blob/main/server/data/sydneyRoads.js): `server/data/sydneyRoads.js`
- [Page Visibility](https://github.com/kevtoe/worldview/blob/main/src/hooks/usePageVisible.ts): `src/hooks/usePageVisible.ts`
- [Camera Data Types](https://github.com/kevtoe/worldview/blob/main/src/types/camera.ts): `src/types/camera.ts`

### API Backend

- [API Proxy](https://github.com/kevtoe/worldview/blob/main/server/index.js): `server/index.js`
- [API Entry](https://github.com/kevtoe/worldview/blob/main/api/index.js): `api/index.js`

### Operator Interface

- [Operations Controls](https://github.com/kevtoe/worldview/blob/main/src/components/ui/OperationsPanel.tsx): `src/components/ui/OperationsPanel.tsx`
- [Intel Feed](https://github.com/kevtoe/worldview/blob/main/src/components/ui/IntelFeed.tsx): `src/components/ui/IntelFeed.tsx`
- [CCTV Panel](https://github.com/kevtoe/worldview/blob/main/src/components/ui/CCTVPanel.tsx): `src/components/ui/CCTVPanel.tsx`
- [Status Bar](https://github.com/kevtoe/worldview/blob/main/src/components/ui/StatusBar.tsx): `src/components/ui/StatusBar.tsx`
- [Tactical Audio](https://github.com/kevtoe/worldview/blob/main/src/lib/audio.ts): `src/lib/audio.ts`

### Other components

- **Operator**
- **Public Data Sources**
- **AISStream.io**

## Connections

- Operator → App Orchestrator: opens dashboard
- App Orchestrator → 3D Globe: mounts (evidence: `src/App.tsx`)
- App Orchestrator → Flight Overlay: renders (evidence: `src/App.tsx`)
- App Orchestrator → Satellite Overlay: renders (evidence: `src/App.tsx`)
- App Orchestrator → Earthquake Overlay: renders (evidence: `src/App.tsx`)
- App Orchestrator → Traffic Overlay: renders (evidence: `src/App.tsx`)
- App Orchestrator → Ship Overlay: renders (evidence: `src/App.tsx`)
- App Orchestrator → CCTV Overlay: renders (evidence: `src/App.tsx`)
- 3D Globe → Entity Selection: handles picks (evidence: `src/components/globe/GlobeViewer.tsx`)
- 3D Globe → Postprocessing Shaders: applies effects (evidence: `src/components/globe/GlobeViewer.tsx`)
- Flight Overlay → Flight Feed: renders data (evidence: `src/components/layers/FlightLayer.tsx`)
- Satellite Overlay → Satellite Propagation: renders data (evidence: `src/components/layers/SatelliteLayer.tsx`)
- Earthquake Overlay → Earthquake Feed: renders data (evidence: `src/components/layers/EarthquakeLayer.tsx`)
- Traffic Overlay → Traffic Simulation: renders data (evidence: `src/components/layers/TrafficLayer.tsx`)
- Ship Overlay → AIS Vessel Feed: renders data (evidence: `src/components/layers/ShipLayer.tsx`)
- CCTV Overlay → Camera Feed: renders data (evidence: `src/components/layers/CCTVLayer.tsx`)
- Flight Feed → Page Visibility: checks visibility (evidence: `src/hooks/useFlights.ts`)
- AIS Vessel Feed → Page Visibility: checks visibility (evidence: `src/hooks/useShips.ts`)
- Flight Feed → API Proxy: fetches feed
- Traffic Simulation → API Proxy: requests roads (evidence: `src/hooks/useTraffic.ts`)
- AIS Vessel Feed → API Proxy: fetches vessels (evidence: `src/hooks/useShips.ts`)
- Camera Feed → API Proxy: fetches cameras
- Satellite Propagation → Public Data Sources: loads TLEs
- Earthquake Feed → Public Data Sources: loads events
- API Proxy → AISStream.io: collects vessel data (evidence: `server/index.js`)
- API Proxy → Public Data Sources: proxies feeds
- API Entry → API Proxy: delegates to (evidence: `api/index.js`)
- API Proxy → Sydney Road Data: uses road data (evidence: `server/index.js`)
- App Orchestrator → Operations Controls: renders controls (evidence: `src/App.tsx`)
- App Orchestrator → Intel Feed: renders feed (evidence: `src/App.tsx`)
- App Orchestrator → CCTV Panel: renders panel (evidence: `src/App.tsx`)
- App Orchestrator → Status Bar: renders status (evidence: `src/App.tsx`)
- Operations Controls → Postprocessing Shaders: selects mode (evidence: `src/components/ui/OperationsPanel.tsx`)
- Operator → Entity Selection: selects entity
- Camera Feed → Camera Data Types: normalizes as (evidence: `src/hooks/useCameras.ts`)
- CCTV Panel → Camera Data Types: displays feeds (evidence: `src/components/ui/CCTVPanel.tsx`)
- App Orchestrator → Tactical Audio: plays interface cues
