# hiccup21/depthscope architecture

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

- Interactive diagram: https://gitdiagram.com/hiccup21/depthscope
- Repository: https://github.com/hiccup21/depthscope

## Overview

DepthScope turns regional GEBCO bathymetry into 3D terrain, then overlays live, region-filtered USGS earthquakes and a camera-tracked depth readout. Users choose regions and layers in the sidebar; App coordinates data loading and scene components. The README documents three regions and a Python bathymetry pipeline. The frontend earthquake hook is sampled; the Python earthquake script is an offline/reference path. Static data copying into the frontend is documented, but its implementation is not shown.

Main entry points: [`frontend/src/App.jsx`](https://github.com/hiccup21/depthscope/blob/main/frontend/src/App.jsx) (App orchestration), [`frontend/src/components/useEarthquakes.js`](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/useEarthquakes.js) (Earthquake fetch and filter), [`frontend/src/components/Rail.jsx`](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/Rail.jsx) (Region and layer controls), [`gebco_pipeline.py`](https://github.com/hiccup21/depthscope/blob/main/gebco_pipeline.py) (Bathymetry pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bathymetry["Bathymetry data"]
  node_pipeline["Bathymetry pipeline<br/>[gebco_pipeline.py]"]
  node_generated["Generated heightmaps"]
  node_serveddata["Frontend heightmaps"]
  node_heightloader["Heightmap loader<br/>[useHeightmap.js]"]
end

subgraph group_seismic["Seismic overlay"]
  node_quakehook["Earthquake fetch and filter<br/>[useEarthquakes.js]"]
  node_quakejson["Offline earthquake export"]
  node_markers["Earthquake markers"]
end

subgraph group_scene["3D exploration"]
  node_terrain["Terrain mesh<br/>[TerrainMesh.jsx]"]
  node_probe["Depth probe<br/>[DepthProbe.jsx]"]
end

subgraph group_interface["User interface"]
  node_app["App orchestration<br/>[App.jsx]"]
  node_rail["Region and layer controls<br/>[Rail.jsx]"]
  node_gauge["Depth gauge<br/>[FathomGauge.jsx]"]
  node_quakeinfo["Earthquake legend<br/>[EarthquakeInfo.jsx]"]
  node_entry["React entry<br/>[main.jsx]"]
end

node_explorer(("Explorer"))
node_gebco{{"GEBCO OPeNDAP"}}
node_usgs{{"USGS feed"}}

node_explorer -->|"selects region"| node_rail
node_explorer -->|"toggles layer"| node_rail
node_rail -->|"reports selections"| node_app
node_entry -->|"renders"| node_app
node_app -->|"requests region data"| node_heightloader
node_heightloader -->|"fetches JSON"| node_serveddata
node_app -->|"requests regional events"| node_quakehook
node_quakehook -->|"fetches feed"| node_usgs
node_quakehook -->|"returns filtered events"| node_app
node_app -->|"passes heightmap"| node_terrain
node_app -->|"passes mesh and controls"| node_probe
node_probe -->|"updates readout"| node_app
node_app -->|"passes depth reading"| node_gauge
node_app -->|"passes events and terrain"| node_markers
node_app -->|"passes feed status"| node_quakeinfo
node_pipeline -->|"fetches bathymetry"| node_gebco
node_pipeline -->|"exports heightmap"| node_generated
node_generated -.->|"copied for frontend"| node_serveddata
node_quakejson -.->|"fetches reference feed"| node_usgs

click node_pipeline "https://github.com/hiccup21/depthscope/blob/main/gebco_pipeline.py"
click node_generated "https://github.com/hiccup21/depthscope/blob/main/manila_trench_heightmap.json"
click node_serveddata "https://github.com/hiccup21/depthscope/blob/main/frontend/public/data/manila_trench_heightmap.json"
click node_heightloader "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/useHeightmap.js"
click node_quakehook "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/useEarthquakes.js"
click node_quakejson "https://github.com/hiccup21/depthscope/blob/main/fetch_earthquakes.py"
click node_app "https://github.com/hiccup21/depthscope/blob/main/frontend/src/App.jsx"
click node_rail "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/Rail.jsx"
click node_terrain "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/TerrainMesh.jsx"
click node_probe "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/DepthProbe.jsx"
click node_gauge "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/FathomGauge.jsx"
click node_markers "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/EarthquakeMarkers.jsx"
click node_quakeinfo "https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/EarthquakeInfo.jsx"
click node_entry "https://github.com/hiccup21/depthscope/blob/main/frontend/src/main.jsx"

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_pipeline,node_generated,node_serveddata,node_heightloader toneBlue
class node_quakehook,node_quakejson,node_markers toneAmber
class node_terrain,node_probe toneMint
class node_app,node_rail,node_gauge,node_quakeinfo,node_entry toneRose
class node_explorer,node_gebco,node_usgs toneIndigo
```

## Components

### Bathymetry data

- [Bathymetry pipeline](https://github.com/hiccup21/depthscope/blob/main/gebco_pipeline.py): `gebco_pipeline.py`
- [Generated heightmaps](https://github.com/hiccup21/depthscope/blob/main/manila_trench_heightmap.json): `manila_trench_heightmap.json`
- [Frontend heightmaps](https://github.com/hiccup21/depthscope/blob/main/frontend/public/data/manila_trench_heightmap.json): `frontend/public/data/manila_trench_heightmap.json`
- [Heightmap loader](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/useHeightmap.js): `frontend/src/components/useHeightmap.js`

### Seismic overlay

- [Earthquake fetch and filter](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/useEarthquakes.js): `frontend/src/components/useEarthquakes.js`
- [Offline earthquake export](https://github.com/hiccup21/depthscope/blob/main/fetch_earthquakes.py): `fetch_earthquakes.py`
- [Earthquake markers](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/EarthquakeMarkers.jsx): `frontend/src/components/EarthquakeMarkers.jsx`

### 3D exploration

- [Terrain mesh](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/TerrainMesh.jsx): `frontend/src/components/TerrainMesh.jsx`
- [Depth probe](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/DepthProbe.jsx): `frontend/src/components/DepthProbe.jsx`

### User interface

- [App orchestration](https://github.com/hiccup21/depthscope/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Region and layer controls](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/Rail.jsx): `frontend/src/components/Rail.jsx`
- [Depth gauge](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/FathomGauge.jsx): `frontend/src/components/FathomGauge.jsx`
- [Earthquake legend](https://github.com/hiccup21/depthscope/blob/main/frontend/src/components/EarthquakeInfo.jsx): `frontend/src/components/EarthquakeInfo.jsx`
- [React entry](https://github.com/hiccup21/depthscope/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Other components

- **Explorer**
- **GEBCO OPeNDAP**
- **USGS feed**

## Connections

- Explorer → Region and layer controls: selects region
- Explorer → Region and layer controls: toggles layer
- Region and layer controls → App orchestration: reports selections
- React entry → App orchestration: renders
- App orchestration → Heightmap loader: requests region data
- Heightmap loader → Frontend heightmaps: fetches JSON
- App orchestration → Earthquake fetch and filter: requests regional events
- Earthquake fetch and filter → USGS feed: fetches feed
- Earthquake fetch and filter → App orchestration: returns filtered events
- App orchestration → Terrain mesh: passes heightmap
- App orchestration → Depth probe: passes mesh and controls
- Depth probe → App orchestration: updates readout
- App orchestration → Depth gauge: passes depth reading
- App orchestration → Earthquake markers: passes events and terrain
- App orchestration → Earthquake legend: passes feed status
- Bathymetry pipeline → GEBCO OPeNDAP: fetches bathymetry
- Bathymetry pipeline → Generated heightmaps: exports heightmap
- Generated heightmaps → Frontend heightmaps: copied for frontend
- Offline earthquake export → USGS feed: fetches reference feed