# harvey-euph/geo-vis architecture

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

- Interactive diagram: https://gitdiagram.com/harvey-euph/geo-vis
- Repository: https://github.com/harvey-euph/geo-vis

## Overview

Geo-Vis is a browser-based administrative geography explorer. Users navigate or search countries and ADM1/ADM2 regions, inspect and select features, change projections, and optionally combine regions with Union/Dissolve tools; URL parameters can initialize and share the view. The main coordinator composes data, interaction, labels, and UI hooks. The graph preserves the documented label, capital, vertex, and starfield capabilities. Some subsystem links rely on README descriptions or source-index references; unsampled internals are not inferred beyond those links.

Main entry points: [`src/components/GeoVisApp.tsx`](https://github.com/harvey-euph/geo-vis/blob/main/src/components/GeoVisApp.tsx) (App coordinator), [`src/components/hooks/useRegionLabels.ts`](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useRegionLabels.ts) (Region labels), [`src/components/hooks/useGeoData.ts`](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useGeoData.ts) (Geo data loading), [`src/components/hooks/useUrlState.ts`](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useUrlState.ts) (URL state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and UI"]
  node_page["App entry<br/>[page.tsx]"]
  node_coordinator["App coordinator<br/>[GeoVisApp.tsx]"]
  node_navigation["Navigation controls"]
  node_options["Map options<br/>[OptionsWindow.tsx]"]
  node_inspector["Region inspector"]
  node_devtools["Union controls"]
  node_toolbar["Dev toolbar"]
  node_vertexui["Vertex tooltip<br/>[VertexTooltip.tsx]"]
end

subgraph group_data["Geographic Data"]
  node_geodata["Geo data loading<br/>[useGeoData.ts]"]
  node_fgb["FGB loader<br/>[fgb-loader.ts]"]
  node_hierarchy["Admin hierarchy"]
  node_url["URL state<br/>[useUrlState.ts]"]
  node_target["Target resolver<br/>[target-resolver.ts]"]
end

subgraph group_map["Map Interaction"]
  node_mapsync["Map event sync<br/>[useMapSync.ts]"]
  node_layers["Interactive layers"]
  node_layerconfig["Map layer config<br/>[map-layers.ts]"]
  node_vertices["Vertex extraction"]
end

subgraph group_analysis["Geometry and Union"]
  node_projection["Projection transforms<br/>[projections.ts]"]
  node_spatial["Spatial hit index<br/>[spatial-index.ts]"]
  node_unionmanager["Union state manager<br/>[useUnionManager.ts]"]
  node_unionengine["Union engine<br/>[union-engine.ts]"]
  node_bbox["Fit bounds<br/>[bbox-helper.ts]"]
  node_capital["Capital mapping<br/>[capital-manager.ts]"]
end

subgraph group_presentation["Labels and Effects"]
  node_labels["Region labels<br/>[useRegionLabels.ts]"]
  node_labelparse["Label parser<br/>[label-parser.ts]"]
  node_labelhierarchy["Label hierarchy"]
  node_labelmanager["Label rendering<br/>[label-manager.ts]"]
  node_anchors["Label anchors<br/>[label-anchors.ts]"]
  node_starhook["Starfield rendering"]
  node_starfield["Star catalog renderer<br/>[starfield.ts]"]
end

node_user(("Map user"))

node_user -->|"opens"| node_page
node_page -->|"renders"| node_coordinator
node_coordinator -->|"composes"| node_navigation
node_coordinator -->|"composes"| node_options
node_coordinator -->|"composes"| node_inspector
node_coordinator -->|"composes"| node_devtools
node_coordinator -->|"composes"| node_toolbar
node_coordinator -->|"composes"| node_vertexui
node_coordinator -->|"coordinates"| node_geodata
node_geodata -->|"loads features"| node_fgb
node_geodata -->|"loads hierarchy"| node_hierarchy
node_coordinator -->|"coordinates"| node_url
node_url -->|"resolves targets"| node_target
node_coordinator -->|"coordinates"| node_mapsync
node_mapsync -->|"loads hierarchy"| node_hierarchy
node_mapsync -->|"configures"| node_layerconfig
node_coordinator -->|"coordinates"| node_layers
node_layers -->|"projects geometry"| node_projection
node_layers -->|"builds hit index"| node_spatial
node_coordinator -->|"coordinates"| node_unionmanager
node_unionmanager -->|"dissolves features"| node_unionengine
node_unionengine -->|"checks capitals"| node_capital
node_url -.->|"fits target"| node_bbox
node_coordinator -->|"coordinates"| node_vertices
node_coordinator -->|"coordinates"| node_labels
node_labels -->|"parses datasets"| node_labelparse
node_labels -->|"resolves labels"| node_labelhierarchy
node_labels -->|"renders labels"| node_labelmanager
node_labelmanager -->|"gets anchors"| node_anchors
node_labelmanager -->|"projects anchors"| node_projection
node_coordinator -->|"coordinates"| node_starhook
node_starhook -->|"renders catalog"| node_starfield

click node_page "https://github.com/harvey-euph/geo-vis/blob/main/src/app/page.tsx"
click node_coordinator "https://github.com/harvey-euph/geo-vis/blob/main/src/components/GeoVisApp.tsx"
click node_navigation "https://github.com/harvey-euph/geo-vis/blob/main/src/components/TopNavigationBar.tsx"
click node_options "https://github.com/harvey-euph/geo-vis/blob/main/src/components/OptionsWindow.tsx"
click node_inspector "https://github.com/harvey-euph/geo-vis/blob/main/src/components/LeftHudInspector.tsx"
click node_devtools "https://github.com/harvey-euph/geo-vis/blob/main/src/components/RightDevSidebar.tsx"
click node_toolbar "https://github.com/harvey-euph/geo-vis/blob/main/src/components/DevUnionToolbar.tsx"
click node_vertexui "https://github.com/harvey-euph/geo-vis/blob/main/src/components/VertexTooltip.tsx"
click node_geodata "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useGeoData.ts"
click node_fgb "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/fgb-loader.ts"
click node_hierarchy "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/hierarchy-manager.ts"
click node_url "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useUrlState.ts"
click node_target "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/target-resolver.ts"
click node_mapsync "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useMapSync.ts"
click node_layers "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useInteractiveLayers.ts"
click node_layerconfig "https://github.com/harvey-euph/geo-vis/blob/main/src/components/map/map-layers.ts"
click node_vertices "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/usePolygonVertices.ts"
click node_projection "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/projections.ts"
click node_spatial "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/spatial-index.ts"
click node_unionmanager "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useUnionManager.ts"
click node_unionengine "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/union-engine.ts"
click node_bbox "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/bbox-helper.ts"
click node_capital "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/capital-manager.ts"
click node_labels "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useRegionLabels.ts"
click node_labelparse "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-parser.ts"
click node_labelhierarchy "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-hierarchy-resolver.ts"
click node_labelmanager "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-manager.ts"
click node_anchors "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-anchors.ts"
click node_starhook "https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useStarfieldRender.ts"
click node_starfield "https://github.com/harvey-euph/geo-vis/blob/main/src/lib/starfield.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_page,node_coordinator,node_navigation,node_options,node_inspector,node_devtools,node_toolbar,node_vertexui,node_user toneBlue
class node_geodata,node_fgb,node_hierarchy,node_url,node_target toneAmber
class node_mapsync,node_layers,node_layerconfig,node_vertices toneMint
class node_projection,node_spatial,node_unionmanager,node_unionengine,node_bbox,node_capital toneRose
class node_labels,node_labelparse,node_labelhierarchy,node_labelmanager,node_anchors,node_starhook,node_starfield toneIndigo
```

## Components

### Application and UI

- [App entry](https://github.com/harvey-euph/geo-vis/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [App coordinator](https://github.com/harvey-euph/geo-vis/blob/main/src/components/GeoVisApp.tsx): `src/components/GeoVisApp.tsx`
- [Navigation controls](https://github.com/harvey-euph/geo-vis/blob/main/src/components/TopNavigationBar.tsx): `src/components/TopNavigationBar.tsx`
- [Map options](https://github.com/harvey-euph/geo-vis/blob/main/src/components/OptionsWindow.tsx): `src/components/OptionsWindow.tsx`
- [Region inspector](https://github.com/harvey-euph/geo-vis/blob/main/src/components/LeftHudInspector.tsx): `src/components/LeftHudInspector.tsx`
- [Union controls](https://github.com/harvey-euph/geo-vis/blob/main/src/components/RightDevSidebar.tsx): `src/components/RightDevSidebar.tsx`
- [Dev toolbar](https://github.com/harvey-euph/geo-vis/blob/main/src/components/DevUnionToolbar.tsx): `src/components/DevUnionToolbar.tsx`
- [Vertex tooltip](https://github.com/harvey-euph/geo-vis/blob/main/src/components/VertexTooltip.tsx): `src/components/VertexTooltip.tsx`

### Geographic Data

- [Geo data loading](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useGeoData.ts): `src/components/hooks/useGeoData.ts`
- [FGB loader](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/fgb-loader.ts): `src/lib/fgb-loader.ts`
- [Admin hierarchy](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/hierarchy-manager.ts): `src/lib/hierarchy-manager.ts`
- [URL state](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useUrlState.ts): `src/components/hooks/useUrlState.ts`
- [Target resolver](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/target-resolver.ts): `src/lib/target-resolver.ts`

### Map Interaction

- [Map event sync](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useMapSync.ts): `src/components/hooks/useMapSync.ts`
- [Interactive layers](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useInteractiveLayers.ts): `src/components/hooks/useInteractiveLayers.ts`
- [Map layer config](https://github.com/harvey-euph/geo-vis/blob/main/src/components/map/map-layers.ts): `src/components/map/map-layers.ts`
- [Vertex extraction](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/usePolygonVertices.ts): `src/components/hooks/usePolygonVertices.ts`

### Geometry and Union

- [Projection transforms](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/projections.ts): `src/lib/projections.ts`
- [Spatial hit index](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/spatial-index.ts): `src/lib/spatial-index.ts`
- [Union state manager](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useUnionManager.ts): `src/components/hooks/useUnionManager.ts`
- [Union engine](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/union-engine.ts): `src/lib/union-engine.ts`
- [Fit bounds](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/bbox-helper.ts): `src/lib/bbox-helper.ts`
- [Capital mapping](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/capital-manager.ts): `src/lib/capital-manager.ts`

### Labels and Effects

- [Region labels](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useRegionLabels.ts): `src/components/hooks/useRegionLabels.ts`
- [Label parser](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-parser.ts): `src/lib/label-parser.ts`
- [Label hierarchy](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-hierarchy-resolver.ts): `src/lib/label-hierarchy-resolver.ts`
- [Label rendering](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-manager.ts): `src/lib/label-manager.ts`
- [Label anchors](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/label-anchors.ts): `src/lib/label-anchors.ts`
- [Starfield rendering](https://github.com/harvey-euph/geo-vis/blob/main/src/components/hooks/useStarfieldRender.ts): `src/components/hooks/useStarfieldRender.ts`
- [Star catalog renderer](https://github.com/harvey-euph/geo-vis/blob/main/src/lib/starfield.ts): `src/lib/starfield.ts`

### Other components

- **Map user**

## Connections

- Map user → App entry: opens (evidence: `src/app/page.tsx`)
- App entry → App coordinator: renders (evidence: `src/app/page.tsx`)
- App coordinator → Navigation controls: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Map options: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Region inspector: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Union controls: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Dev toolbar: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Vertex tooltip: composes (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Geo data loading: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Geo data loading → FGB loader: loads features (evidence: `src/components/hooks/useGeoData.ts`)
- Geo data loading → Admin hierarchy: loads hierarchy (evidence: `src/components/hooks/useGeoData.ts`)
- App coordinator → URL state: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- URL state → Target resolver: resolves targets (evidence: `src/components/hooks/useUrlState.ts`)
- App coordinator → Map event sync: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Map event sync → Admin hierarchy: loads hierarchy (evidence: `src/components/hooks/useMapSync.ts`)
- Map event sync → Map layer config: configures (evidence: `src/components/hooks/useMapSync.ts`)
- App coordinator → Interactive layers: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Interactive layers → Projection transforms: projects geometry (evidence: `src/components/hooks/useInteractiveLayers.ts`)
- Interactive layers → Spatial hit index: builds hit index (evidence: `src/components/hooks/useInteractiveLayers.ts`)
- App coordinator → Union state manager: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Union state manager → Union engine: dissolves features (evidence: `src/components/hooks/useUnionManager.ts`)
- Union engine → Capital mapping: checks capitals (evidence: `src/lib/union-engine.ts`)
- URL state → Fit bounds: fits target
- App coordinator → Vertex extraction: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- App coordinator → Region labels: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Region labels → Label parser: parses datasets (evidence: `src/components/hooks/useRegionLabels.ts`)
- Region labels → Label hierarchy: resolves labels (evidence: `src/components/hooks/useRegionLabels.ts`)
- Region labels → Label rendering: renders labels (evidence: `src/components/hooks/useRegionLabels.ts`)
- Label rendering → Label anchors: gets anchors (evidence: `src/lib/label-manager.ts`)
- Label rendering → Projection transforms: projects anchors (evidence: `src/lib/label-manager.ts`)
- App coordinator → Starfield rendering: coordinates (evidence: `src/components/GeoVisApp.tsx`)
- Starfield rendering → Star catalog renderer: renders catalog (evidence: `src/components/hooks/useStarfieldRender.ts`)