# hhaider3/live-sat-location architecture

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

- Interactive diagram: https://gitdiagram.com/hhaider3/live-sat-location
- Repository: https://github.com/hhaider3/live-sat-location

## Overview

Earth Orbit Live is a browser-based 3D satellite explorer backed by a small Cloudflare Worker API. The main workflow loads observed orbital catalogs, parses them into satellite state, propagates positions for the interactive globe, and lets users search/select satellites or plan city passes. The Worker validates upstream CSV/OMM data and serves cached observations with snapshot fallbacks. The README documents additional UI and resilience capabilities beyond the sampled excerpts; edges for unsampled wiring are omitted or marked unverified.

Main entry points: [`src/App.tsx`](https://github.com/hhaider3/live-sat-location/blob/main/src/App.tsx) (Explorer interface), [`worker/proxy.js`](https://github.com/hhaider3/live-sat-location/blob/main/worker/proxy.js) (Catalog proxy), [`src/engine.ts`](https://github.com/hhaider3/live-sat-location/blob/main/src/engine.ts) (3D globe and controls), [`src/satellites.ts`](https://github.com/hhaider3/live-sat-location/blob/main/src/satellites.ts) (Catalog loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_app["Explorer interface<br/>[App.tsx]"]
  node_pass_planner["Pass planner<br/>[PassPlanner.tsx]"]
  node_catalog_client["Catalog loading<br/>[satellites.ts]"]
  node_catalog_batches["Batch scheduler<br/>[catalog.ts]"]
  node_catalog_parser["Catalog parser<br/>[catalogParser.ts]"]
  node_catalog_worker["Parse worker<br/>[catalog.worker.ts]"]
end

subgraph group_orbit["Orbit calculations"]
  node_scene["3D globe and controls<br/>[engine.ts]"]
  node_propagator["Orbit propagation<br/>[propagation.ts]"]
  node_prop_worker["Propagation worker"]
  node_pass_calculator["Pass prediction<br/>[passes.ts]"]
  node_pass_worker["Pass worker<br/>[passes.worker.ts]"]
  node_satellite_model["Satellite model<br/>[satellites.ts]"]
  node_time_control["Simulation clock<br/>[time.ts]"]
  node_selection["Satellite picking<br/>[picking.ts]"]
end

subgraph group_api["Catalog API"]
  node_worker_entry["API router<br/>[index.js]"]
  node_proxy["Catalog proxy<br/>[proxy.js]"]
end

subgraph group_data["Catalog validation and storage"]
  node_csv_parser["OMM CSV parser<br/>[csv.ts]"]
  node_omm_validation["OMM validation<br/>[omm.ts]"]
  node_snapshot["Snapshot validation<br/>[snapshot.ts]"]
  node_snapshot_service["Snapshot service<br/>[snapshot.js]"]
  node_catalog_store[("Catalog storage<br/>[store.js]")]
end

node_visitor(("Explorer"))
node_upstream["CelesTrak"]
node_site_snapshot["Hosted snapshot<br/>[active.json]"]

node_visitor -->|"uses"| node_app
node_app -->|"loads groups"| node_catalog_client
node_app -->|"schedules loads"| node_catalog_batches
node_app -->|"configures parsing"| node_catalog_parser
node_catalog_parser -.->|"parses off-thread"| node_catalog_worker
node_catalog_client -->|"requests catalog"| node_worker_entry
node_app -->|"controls display"| node_scene
node_app -->|"renders planner"| node_pass_planner
node_pass_planner -->|"requests predictions"| node_pass_calculator
node_pass_calculator -->|"uses orbit data"| node_satellite_model
node_pass_calculator -.->|"runs in worker"| node_pass_worker
node_scene -->|"requests snapshots"| node_propagator
node_scene -->|"samples orbits"| node_satellite_model
node_scene -->|"advances time"| node_time_control
node_scene -->|"picks satellites"| node_selection
node_prop_worker -->|"builds snapshots"| node_propagator
node_propagator -->|"propagates records"| node_satellite_model
node_worker_entry -->|"routes requests"| node_proxy
node_proxy -->|"parses feed"| node_csv_parser
node_proxy -->|"validates records"| node_omm_validation
node_proxy -->|"loads snapshots"| node_snapshot_service
node_proxy -->|"reads and writes"| node_catalog_store
node_proxy -->|"fetches feed"| node_upstream
node_snapshot_service -->|"validates snapshot"| node_snapshot
node_snapshot_service -->|"reads asset"| node_site_snapshot
node_catalog_client -->|"fallback fetch"| node_site_snapshot

click node_app "https://github.com/hhaider3/live-sat-location/blob/main/src/App.tsx"
click node_pass_planner "https://github.com/hhaider3/live-sat-location/blob/main/src/PassPlanner.tsx"
click node_catalog_client "https://github.com/hhaider3/live-sat-location/blob/main/src/satellites.ts"
click node_catalog_batches "https://github.com/hhaider3/live-sat-location/blob/main/src/catalog.ts"
click node_catalog_parser "https://github.com/hhaider3/live-sat-location/blob/main/src/catalogParser.ts"
click node_catalog_worker "https://github.com/hhaider3/live-sat-location/blob/main/src/catalog.worker.ts"
click node_scene "https://github.com/hhaider3/live-sat-location/blob/main/src/engine.ts"
click node_propagator "https://github.com/hhaider3/live-sat-location/blob/main/src/propagation.ts"
click node_prop_worker "https://github.com/hhaider3/live-sat-location/blob/main/src/propagation.worker.ts"
click node_pass_calculator "https://github.com/hhaider3/live-sat-location/blob/main/src/passes.ts"
click node_pass_worker "https://github.com/hhaider3/live-sat-location/blob/main/src/passes.worker.ts"
click node_satellite_model "https://github.com/hhaider3/live-sat-location/blob/main/src/satellites.ts"
click node_time_control "https://github.com/hhaider3/live-sat-location/blob/main/src/time.ts"
click node_selection "https://github.com/hhaider3/live-sat-location/blob/main/src/picking.ts"
click node_worker_entry "https://github.com/hhaider3/live-sat-location/blob/main/worker/index.js"
click node_proxy "https://github.com/hhaider3/live-sat-location/blob/main/worker/proxy.js"
click node_csv_parser "https://github.com/hhaider3/live-sat-location/blob/main/shared/csv.ts"
click node_omm_validation "https://github.com/hhaider3/live-sat-location/blob/main/shared/omm.ts"
click node_snapshot "https://github.com/hhaider3/live-sat-location/blob/main/shared/snapshot.ts"
click node_snapshot_service "https://github.com/hhaider3/live-sat-location/blob/main/worker/snapshot.js"
click node_catalog_store "https://github.com/hhaider3/live-sat-location/blob/main/worker/store.js"
click node_site_snapshot "https://github.com/hhaider3/live-sat-location/blob/main/public/data/active.json"

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_pass_planner,node_catalog_client,node_catalog_batches,node_catalog_parser,node_catalog_worker toneBlue
class node_scene,node_propagator,node_prop_worker,node_pass_calculator,node_pass_worker,node_satellite_model,node_time_control,node_selection toneAmber
class node_worker_entry,node_proxy toneMint
class node_csv_parser,node_omm_validation,node_snapshot,node_snapshot_service,node_catalog_store toneRose
class node_visitor,node_upstream toneIndigo
class node_site_snapshot toneTeal
```

## Components

### Browser experience

- [Explorer interface](https://github.com/hhaider3/live-sat-location/blob/main/src/App.tsx): `src/App.tsx`
- [Pass planner](https://github.com/hhaider3/live-sat-location/blob/main/src/PassPlanner.tsx): `src/PassPlanner.tsx`
- [Catalog loading](https://github.com/hhaider3/live-sat-location/blob/main/src/satellites.ts): `src/satellites.ts`
- [Batch scheduler](https://github.com/hhaider3/live-sat-location/blob/main/src/catalog.ts): `src/catalog.ts`
- [Catalog parser](https://github.com/hhaider3/live-sat-location/blob/main/src/catalogParser.ts): `src/catalogParser.ts`
- [Parse worker](https://github.com/hhaider3/live-sat-location/blob/main/src/catalog.worker.ts): `src/catalog.worker.ts`

### Orbit calculations

- [3D globe and controls](https://github.com/hhaider3/live-sat-location/blob/main/src/engine.ts): `src/engine.ts`
- [Orbit propagation](https://github.com/hhaider3/live-sat-location/blob/main/src/propagation.ts): `src/propagation.ts`
- [Propagation worker](https://github.com/hhaider3/live-sat-location/blob/main/src/propagation.worker.ts): `src/propagation.worker.ts`
- [Pass prediction](https://github.com/hhaider3/live-sat-location/blob/main/src/passes.ts): `src/passes.ts`
- [Pass worker](https://github.com/hhaider3/live-sat-location/blob/main/src/passes.worker.ts): `src/passes.worker.ts`
- [Satellite model](https://github.com/hhaider3/live-sat-location/blob/main/src/satellites.ts): `src/satellites.ts`
- [Simulation clock](https://github.com/hhaider3/live-sat-location/blob/main/src/time.ts): `src/time.ts`
- [Satellite picking](https://github.com/hhaider3/live-sat-location/blob/main/src/picking.ts): `src/picking.ts`

### Catalog API

- [API router](https://github.com/hhaider3/live-sat-location/blob/main/worker/index.js): `worker/index.js`
- [Catalog proxy](https://github.com/hhaider3/live-sat-location/blob/main/worker/proxy.js): `worker/proxy.js`

### Catalog validation and storage

- [OMM CSV parser](https://github.com/hhaider3/live-sat-location/blob/main/shared/csv.ts): `shared/csv.ts`
- [OMM validation](https://github.com/hhaider3/live-sat-location/blob/main/shared/omm.ts): `shared/omm.ts`
- [Snapshot validation](https://github.com/hhaider3/live-sat-location/blob/main/shared/snapshot.ts): `shared/snapshot.ts`
- [Snapshot service](https://github.com/hhaider3/live-sat-location/blob/main/worker/snapshot.js): `worker/snapshot.js`
- [Catalog storage](https://github.com/hhaider3/live-sat-location/blob/main/worker/store.js): `worker/store.js`

### Other components

- **Explorer**
- **CelesTrak**
- [Hosted snapshot](https://github.com/hhaider3/live-sat-location/blob/main/public/data/active.json): `public/data/active.json`

## Connections

- Explorer → Explorer interface: uses (evidence: `README.md`)
- Explorer interface → Catalog loading: loads groups (evidence: `src/App.tsx`)
- Explorer interface → Batch scheduler: schedules loads (evidence: `src/App.tsx`)
- Explorer interface → Catalog parser: configures parsing (evidence: `src/App.tsx`)
- Catalog parser → Parse worker: parses off-thread
- Catalog loading → API router: requests catalog (evidence: `README.md`)
- Explorer interface → 3D globe and controls: controls display (evidence: `src/App.tsx`)
- Explorer interface → Pass planner: renders planner (evidence: `src/App.tsx`)
- Pass planner → Pass prediction: requests predictions (evidence: `src/PassPlanner.tsx`)
- Pass prediction → Satellite model: uses orbit data (evidence: `src/PassPlanner.tsx`)
- Pass prediction → Pass worker: runs in worker (evidence: `src/passes.worker.ts`)
- 3D globe and controls → Orbit propagation: requests snapshots (evidence: `src/engine.ts`)
- 3D globe and controls → Satellite model: samples orbits (evidence: `src/engine.ts`)
- 3D globe and controls → Simulation clock: advances time (evidence: `src/engine.ts`)
- 3D globe and controls → Satellite picking: picks satellites (evidence: `src/engine.ts`)
- Propagation worker → Orbit propagation: builds snapshots (evidence: `src/propagation.worker.ts`)
- Orbit propagation → Satellite model: propagates records (evidence: `src/propagation.ts`)
- API router → Catalog proxy: routes requests (evidence: `worker/index.js`)
- Catalog proxy → OMM CSV parser: parses feed (evidence: `worker/proxy.js`)
- Catalog proxy → OMM validation: validates records (evidence: `worker/proxy.js`)
- Catalog proxy → Snapshot service: loads snapshots (evidence: `worker/proxy.js`)
- Catalog proxy → Catalog storage: reads and writes (evidence: `worker/proxy.js`)
- Catalog proxy → CelesTrak: fetches feed (evidence: `README.md`)
- Snapshot service → Snapshot validation: validates snapshot (evidence: `worker/snapshot.js`)
- Snapshot service → Hosted snapshot: reads asset (evidence: `worker/snapshot.js`)
- Catalog loading → Hosted snapshot: fallback fetch (evidence: `README.md`)
