# tristanscloud/stickleback-environmental-metrics architecture

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

- Interactive diagram: https://gitdiagram.com/tristanscloud/stickleback-environmental-metrics
- Repository: https://github.com/tristanscloud/stickleback-environmental-metrics

## Overview

This is a Python pipeline for validating stickleback sample coordinates and enriching them with habitat, water-feature, climate, terrain, hydrology, and ecological-metric context. Its principal workflow is validated sites → habitat-aware matching or environmental extraction → status/provenance-bearing metrics; cached pilot results can also be materialized offline. A secondary branch prepares frozen validation assets for a read-only Earth Engine viewer. Several orchestration and extraction links are documented at module level but their runtime callers were not shown, so those relationships are marked unverified.

Main entry points: [`src/enviro_data/runner.py`](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/runner.py) (Pipeline runner), [`src/enviro_data/cached_enrichment.py`](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/cached_enrichment.py) (Cached enrichment), [`src/enviro_data/pilot.py`](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/pilot.py) (Pilot workflow), [`src/enviro_data/habitats.py`](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/habitats.py) (Habitat domains)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site preparation"]
  node_input["Site validation<br/>[input.py]"]
  node_habitat["Habitat inference<br/>[site_habitat.py]"]
  node_habitat_domains["Habitat domains<br/>[habitats.py]"]
  node_osm["OSM matching<br/>[osm_matching.py]"]
  node_pilot["Pilot workflow<br/>[pilot.py]"]
  node_runner["Pipeline runner<br/>[runner.py]"]
end

subgraph group_environment["Environmental data"]
  node_climate["Climate sampling<br/>[climate.py]"]
  node_terrain["Terrain sampling<br/>[terrain.py]"]
  node_dem["DEM acquisition<br/>[dem_acquisition.py]"]
  node_topography["Topography extraction<br/>[topography.py]"]
  node_hydrology["Hydrology integration<br/>[hydrology.py]"]
  node_extraction["Extraction planning<br/>[extraction_plan.py]"]
end

subgraph group_metrics["Metrics and sources"]
  node_catalog["Source catalog<br/>[source_catalog.py]"]
  node_transforms["Unit transforms<br/>[transforms.py]"]
  node_temporal["Temporal summaries<br/>[temporal.py]"]
  node_metrics_contract["Metric contract<br/>[metrics.py]"]
  node_cached["Cached enrichment"]
  node_variables["Environmental variables"]
  node_variable_helpers["Variable geometry helpers<br/>[_common.py]"]
end

subgraph group_review["Pilot review"]
  node_assets["Validation asset builder<br/>[ee_app_assets.py]"]
  node_viewer["Validation viewer"]
end

node_user(("Analyst"))
node_earth_engine["Google Earth Engine"]

node_user -->|"loads sites"| node_input
node_input -->|"provides records"| node_pilot
node_pilot -.->|"infers habitat"| node_habitat
node_habitat -->|"normalizes domain"| node_habitat_domains
node_pilot -.->|"matches features"| node_osm
node_runner -.->|"samples climate"| node_climate
node_runner -.->|"samples terrain"| node_terrain
node_dem -->|"supplies cached DEM"| node_topography
node_runner -.->|"acquires bounded data"| node_dem
node_runner -.->|"uses hydrology"| node_hydrology
node_catalog -->|"routes by habitat"| node_habitat_domains
node_user -.->|"plans extraction"| node_extraction
node_cached -->|"normalizes habitat"| node_habitat_domains
node_cached -->|"creates metrics"| node_metrics_contract
node_cached -.->|"derives variables"| node_variables
node_variables -->|"uses geometry helpers"| node_variable_helpers
node_user -->|"enriches pilot cache"| node_cached
node_user -->|"prepares review assets"| node_assets
node_assets -->|"prepares viewer inputs"| node_viewer
node_viewer -->|"selects approved release"| node_earth_engine
node_catalog -.->|"declares transforms"| node_transforms
node_metrics_contract -.->|"summarizes metrics"| node_temporal

click node_input "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/input.py"
click node_habitat "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/site_habitat.py"
click node_habitat_domains "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/habitats.py"
click node_osm "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/osm_matching.py"
click node_pilot "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/pilot.py"
click node_runner "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/runner.py"
click node_climate "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/climate.py"
click node_terrain "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/terrain.py"
click node_dem "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/dem_acquisition.py"
click node_topography "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/topography.py"
click node_hydrology "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/hydrology.py"
click node_extraction "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/extraction_plan.py"
click node_catalog "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/source_catalog.py"
click node_transforms "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/transforms.py"
click node_temporal "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/temporal.py"
click node_metrics_contract "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/metrics.py"
click node_cached "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/cached_enrichment.py"
click node_variables "https://github.com/tristanscloud/stickleback-environmental-metrics/tree/main/src/enviro_data/variables"
click node_variable_helpers "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/variables/_common.py"
click node_assets "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/ee_app_assets.py"
click node_viewer "https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/apps/earth_engine_validation/ee_pilot_validation_app.js"

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_input,node_habitat,node_habitat_domains,node_osm,node_pilot,node_runner toneBlue
class node_climate,node_terrain,node_dem,node_topography,node_hydrology,node_extraction toneAmber
class node_catalog,node_transforms,node_temporal,node_metrics_contract,node_cached,node_variables,node_variable_helpers toneMint
class node_assets,node_viewer toneRose
class node_user,node_earth_engine toneIndigo
```

## Components

### Site preparation

- [Site validation](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/input.py): `src/enviro_data/input.py`
- [Habitat inference](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/site_habitat.py): `src/enviro_data/site_habitat.py`
- [Habitat domains](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/habitats.py): `src/enviro_data/habitats.py`
- [OSM matching](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/osm_matching.py): `src/enviro_data/osm_matching.py`
- [Pilot workflow](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/pilot.py): `src/enviro_data/pilot.py`
- [Pipeline runner](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/runner.py): `src/enviro_data/runner.py`

### Environmental data

- [Climate sampling](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/climate.py): `src/enviro_data/climate.py`
- [Terrain sampling](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/terrain.py): `src/enviro_data/terrain.py`
- [DEM acquisition](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/dem_acquisition.py): `src/enviro_data/dem_acquisition.py`
- [Topography extraction](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/topography.py): `src/enviro_data/topography.py`
- [Hydrology integration](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/hydrology.py): `src/enviro_data/hydrology.py`
- [Extraction planning](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/extraction_plan.py): `src/enviro_data/extraction_plan.py`

### Metrics and sources

- [Source catalog](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/source_catalog.py): `src/enviro_data/source_catalog.py`
- [Unit transforms](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/transforms.py): `src/enviro_data/transforms.py`
- [Temporal summaries](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/temporal.py): `src/enviro_data/temporal.py`
- [Metric contract](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/metrics.py): `src/enviro_data/metrics.py`
- [Cached enrichment](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/cached_enrichment.py): `src/enviro_data/cached_enrichment.py`
- [Environmental variables](https://github.com/tristanscloud/stickleback-environmental-metrics/tree/main/src/enviro_data/variables): `src/enviro_data/variables`
- [Variable geometry helpers](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/variables/_common.py): `src/enviro_data/variables/_common.py`

### Pilot review

- [Validation asset builder](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/src/enviro_data/ee_app_assets.py): `src/enviro_data/ee_app_assets.py`
- [Validation viewer](https://github.com/tristanscloud/stickleback-environmental-metrics/blob/main/apps/earth_engine_validation/ee_pilot_validation_app.js): `apps/earth_engine_validation/ee_pilot_validation_app.js`

### Other components

- **Analyst**
- **Google Earth Engine**

## Connections

- Analyst → Site validation: loads sites (evidence: `README.md`)
- Site validation → Pilot workflow: provides records (evidence: `src/enviro_data/pilot.py`)
- Pilot workflow → Habitat inference: infers habitat
- Habitat inference → Habitat domains: normalizes domain (evidence: `src/enviro_data/site_habitat.py`)
- Pilot workflow → OSM matching: matches features
- Pipeline runner → Climate sampling: samples climate
- Pipeline runner → Terrain sampling: samples terrain
- DEM acquisition → Topography extraction: supplies cached DEM (evidence: `src/enviro_data/topography.py`)
- Pipeline runner → DEM acquisition: acquires bounded data
- Pipeline runner → Hydrology integration: uses hydrology
- Source catalog → Habitat domains: routes by habitat (evidence: `src/enviro_data/source_catalog.py`)
- Analyst → Extraction planning: plans extraction
- Cached enrichment → Habitat domains: normalizes habitat (evidence: `src/enviro_data/cached_enrichment.py`)
- Cached enrichment → Metric contract: creates metrics (evidence: `src/enviro_data/cached_enrichment.py`)
- Cached enrichment → Environmental variables: derives variables
- Environmental variables → Variable geometry helpers: uses geometry helpers (evidence: `src/enviro_data/variables/coastal_context.py`)
- Analyst → Cached enrichment: enriches pilot cache (evidence: `README.md`)
- Analyst → Validation asset builder: prepares review assets (evidence: `README.md`)
- Validation asset builder → Validation viewer: prepares viewer inputs (evidence: `README.md`)
- Validation viewer → Google Earth Engine: selects approved release (evidence: `README.md`)
- Source catalog → Unit transforms: declares transforms
- Metric contract → Temporal summaries: summarizes metrics