# leshbs/terra-matcher architecture

> Architecture diagram of the GitHub repository leshbs/terra-matcher, 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/leshbs/terra-matcher
- Repository: https://github.com/leshbs/terra-matcher

## Overview

Terra Analog Mission Control turns a Gale Crater terrain reference and curated Earth candidates into an inspectable, feature-weighted similarity ranking—not a site approval. The main workflow serves scenario and candidate data through API routes, validates comparison data, and presents rankings and candidate-level explanations. Separate branches provide map-based exploration and methodology/provenance. An offline pipeline derives terrain features and rankings from raster inputs. The supplied excerpts support the scenario and methodology data access and several UI calls; some pipeline and API internals were not excerpted, so those relationships are omitted or marked unverified.

Main entry points: [`components/comparison-dashboard.tsx`](https://github.com/leshbs/terra-matcher/blob/main/components/comparison-dashboard.tsx) (Mission dashboard), [`app/compare/page.tsx`](https://github.com/leshbs/terra-matcher/blob/main/app/compare/page.tsx) (Ranking page), [`components/comparison/comparison-workspace.tsx`](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/comparison-workspace.tsx) (Candidate workspace), [`components/explore/ExploreShell.tsx`](https://github.com/leshbs/terra-matcher/blob/main/components/explore/ExploreShell.tsx) (Explore shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Comparison experience"]
  node_home["Mission dashboard"]
  node_ranking_page["Ranking page<br/>[page.tsx]"]
  node_data_bundle["Comparison data<br/>[data.ts]"]
  node_ranking["Ranked candidates"]
  node_contracts["Data contracts<br/>[contracts.ts]"]
  node_candidate_page["Candidate workspace"]
  node_explain["Score explanation"]
  node_feature_view["Feature comparison"]
  node_method_page["Methodology page"]
end

subgraph group_api["Data and provenance API"]
  node_scenario_api["Scenario endpoint<br/>[route.ts]"]
  node_candidate_api["Candidate endpoint<br/>[route.ts]"]
  node_method_api["Methodology endpoint<br/>[route.ts]"]
  node_supabase_client["Public DB client<br/>[public.ts]"]
end

subgraph group_explore["Map exploration"]
  node_explore_page["Explore shell<br/>[ExploreShell.tsx]"]
  node_explore_data["Explore data<br/>[data.ts]"]
  node_map["Terrain map<br/>[MapView.tsx]"]
  node_geo["Map geometry<br/>[geo.ts]"]
  node_layers["Terrain layers<br/>[layers.ts]"]
end

subgraph group_pipeline["Terrain pipeline"]
  node_ranking_pipeline["Ranking runner<br/>[run_rankings.py]"]
  node_rank_engine["Ranking engine<br/>[ranking.py]"]
  node_feature_runner["Feature runner"]
  node_raster_source["Raster inputs<br/>[source_rasters.py]"]
  node_terrain_features["Terrain features"]
end

node_visitor(("Mission analyst"))
node_supabase[("Supabase")]

node_visitor -->|"opens dashboard"| node_home
node_home -->|"fetches scenarios"| node_scenario_api
node_home -->|"fetches candidates"| node_candidate_api
node_scenario_api -->|"queries via"| node_supabase_client
node_method_api -->|"queries via"| node_supabase_client
node_supabase_client -.->|"connects to"| node_supabase
node_visitor -->|"opens rankings"| node_ranking_page
node_ranking_page -->|"loads bundle"| node_data_bundle
node_ranking_page -->|"renders ranking"| node_ranking
node_ranking -->|"uses definitions"| node_contracts
node_visitor -->|"opens candidate"| node_candidate_page
node_candidate_page -->|"renders explanation"| node_explain
node_candidate_page -->|"renders features"| node_feature_view
node_visitor -->|"opens methodology"| node_method_page
node_method_page -.->|"loads provenance"| node_method_api
node_visitor -->|"opens map"| node_explore_page
node_explore_page -->|"loads data"| node_explore_data
node_explore_page -->|"renders map"| node_map
node_map -->|"builds map points"| node_geo
node_map -->|"colors terrain"| node_layers
node_ranking_pipeline -.->|"uses ranking"| node_rank_engine
node_ranking_pipeline -.->|"uses features"| node_feature_runner
node_feature_runner -.->|"uses rasters"| node_raster_source
node_feature_runner -.->|"derives features"| node_terrain_features

click node_home "https://github.com/leshbs/terra-matcher/blob/main/components/comparison-dashboard.tsx"
click node_scenario_api "https://github.com/leshbs/terra-matcher/blob/main/app/api/scenarios/route.ts"
click node_candidate_api "https://github.com/leshbs/terra-matcher/blob/main/app/api/scenarios/%5BscenarioId%5D/candidates/route.ts"
click node_method_api "https://github.com/leshbs/terra-matcher/blob/main/app/api/methodology/route.ts"
click node_supabase_client "https://github.com/leshbs/terra-matcher/blob/main/lib/supabase/public.ts"
click node_ranking_page "https://github.com/leshbs/terra-matcher/blob/main/app/compare/page.tsx"
click node_data_bundle "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/data.ts"
click node_ranking "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/ranking-dashboard.tsx"
click node_contracts "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/contracts.ts"
click node_candidate_page "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/comparison-workspace.tsx"
click node_explain "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/comparison-explainability.tsx"
click node_feature_view "https://github.com/leshbs/terra-matcher/blob/main/components/comparison/feature-comparison.tsx"
click node_method_page "https://github.com/leshbs/terra-matcher/blob/main/components/methodology-content.tsx"
click node_explore_page "https://github.com/leshbs/terra-matcher/blob/main/components/explore/ExploreShell.tsx"
click node_explore_data "https://github.com/leshbs/terra-matcher/blob/main/lib/explore/data.ts"
click node_map "https://github.com/leshbs/terra-matcher/blob/main/components/explore/MapView.tsx"
click node_geo "https://github.com/leshbs/terra-matcher/blob/main/lib/explore/geo.ts"
click node_layers "https://github.com/leshbs/terra-matcher/blob/main/lib/explore/layers.ts"
click node_ranking_pipeline "https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/run_rankings.py"
click node_rank_engine "https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/ranking.py"
click node_feature_runner "https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/run_training_features.py"
click node_raster_source "https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/source_rasters.py"
click node_terrain_features "https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/terrain_features.py"

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_home,node_ranking_page,node_data_bundle,node_ranking,node_contracts,node_candidate_page,node_explain,node_feature_view,node_method_page toneBlue
class node_scenario_api,node_candidate_api,node_method_api,node_supabase_client,node_supabase toneAmber
class node_explore_page,node_explore_data,node_map,node_geo,node_layers toneMint
class node_ranking_pipeline,node_rank_engine,node_feature_runner,node_raster_source,node_terrain_features toneRose
class node_visitor toneIndigo
```

## Components

### Comparison experience

- [Mission dashboard](https://github.com/leshbs/terra-matcher/blob/main/components/comparison-dashboard.tsx): `components/comparison-dashboard.tsx`
- [Ranking page](https://github.com/leshbs/terra-matcher/blob/main/app/compare/page.tsx): `app/compare/page.tsx`
- [Comparison data](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/data.ts): `components/comparison/data.ts`
- [Ranked candidates](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/ranking-dashboard.tsx): `components/comparison/ranking-dashboard.tsx`
- [Data contracts](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/contracts.ts): `components/comparison/contracts.ts`
- [Candidate workspace](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/comparison-workspace.tsx): `components/comparison/comparison-workspace.tsx`
- [Score explanation](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/comparison-explainability.tsx): `components/comparison/comparison-explainability.tsx`
- [Feature comparison](https://github.com/leshbs/terra-matcher/blob/main/components/comparison/feature-comparison.tsx): `components/comparison/feature-comparison.tsx`
- [Methodology page](https://github.com/leshbs/terra-matcher/blob/main/components/methodology-content.tsx): `components/methodology-content.tsx`

### Data and provenance API

- [Scenario endpoint](https://github.com/leshbs/terra-matcher/blob/main/app/api/scenarios/route.ts): `app/api/scenarios/route.ts`
- [Candidate endpoint](https://github.com/leshbs/terra-matcher/blob/main/app/api/scenarios/%5BscenarioId%5D/candidates/route.ts): `app/api/scenarios/[scenarioId]/candidates/route.ts`
- [Methodology endpoint](https://github.com/leshbs/terra-matcher/blob/main/app/api/methodology/route.ts): `app/api/methodology/route.ts`
- [Public DB client](https://github.com/leshbs/terra-matcher/blob/main/lib/supabase/public.ts): `lib/supabase/public.ts`

### Map exploration

- [Explore shell](https://github.com/leshbs/terra-matcher/blob/main/components/explore/ExploreShell.tsx): `components/explore/ExploreShell.tsx`
- [Explore data](https://github.com/leshbs/terra-matcher/blob/main/lib/explore/data.ts): `lib/explore/data.ts`
- [Terrain map](https://github.com/leshbs/terra-matcher/blob/main/components/explore/MapView.tsx): `components/explore/MapView.tsx`
- [Map geometry](https://github.com/leshbs/terra-matcher/blob/main/lib/explore/geo.ts): `lib/explore/geo.ts`
- [Terrain layers](https://github.com/leshbs/terra-matcher/blob/main/lib/explore/layers.ts): `lib/explore/layers.ts`

### Terrain pipeline

- [Ranking runner](https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/run_rankings.py): `pipeline/src/terra_analog/run_rankings.py`
- [Ranking engine](https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/ranking.py): `pipeline/src/terra_analog/ranking.py`
- [Feature runner](https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/run_training_features.py): `pipeline/src/terra_analog/run_training_features.py`
- [Raster inputs](https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/source_rasters.py): `pipeline/src/terra_analog/source_rasters.py`
- [Terrain features](https://github.com/leshbs/terra-matcher/blob/main/pipeline/src/terra_analog/terrain_features.py): `pipeline/src/terra_analog/terrain_features.py`

### Other components

- **Mission analyst**
- **Supabase**

## Connections

- Mission analyst → Mission dashboard: opens dashboard (evidence: `README.md`)
- Mission dashboard → Scenario endpoint: fetches scenarios (evidence: `components/comparison-dashboard.tsx`)
- Mission dashboard → Candidate endpoint: fetches candidates (evidence: `components/comparison-dashboard.tsx`)
- Scenario endpoint → Public DB client: queries via (evidence: `app/api/scenarios/route.ts`)
- Methodology endpoint → Public DB client: queries via (evidence: `app/api/methodology/route.ts`)
- Public DB client → Supabase: connects to
- Mission analyst → Ranking page: opens rankings (evidence: `README.md`)
- Ranking page → Comparison data: loads bundle (evidence: `app/compare/page.tsx`)
- Ranking page → Ranked candidates: renders ranking (evidence: `app/compare/page.tsx`)
- Ranked candidates → Data contracts: uses definitions (evidence: `components/comparison/ranking-dashboard.tsx`)
- Mission analyst → Candidate workspace: opens candidate (evidence: `README.md`)
- Candidate workspace → Score explanation: renders explanation (evidence: `components/comparison/comparison-workspace.tsx`)
- Candidate workspace → Feature comparison: renders features (evidence: `components/comparison/comparison-workspace.tsx`)
- Mission analyst → Methodology page: opens methodology (evidence: `README.md`)
- Methodology page → Methodology endpoint: loads provenance
- Mission analyst → Explore shell: opens map
- Explore shell → Explore data: loads data (evidence: `components/explore/ExploreShell.tsx`)
- Explore shell → Terrain map: renders map (evidence: `components/explore/ExploreShell.tsx`)
- Terrain map → Map geometry: builds map points (evidence: `components/explore/MapView.tsx`)
- Terrain map → Terrain layers: colors terrain (evidence: `components/explore/MapView.tsx`)
- Ranking runner → Ranking engine: uses ranking (evidence: `pipeline/src/terra_analog/run_rankings.py`)
- Ranking runner → Feature runner: uses features (evidence: `pipeline/src/terra_analog/run_rankings.py`)
- Feature runner → Raster inputs: uses rasters (evidence: `pipeline/src/terra_analog/run_training_features.py`)
- Feature runner → Terrain features: derives features (evidence: `pipeline/src/terra_analog/run_training_features.py`)