# bikashpandeya/test_alterecho architecture

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

- Interactive diagram: https://gitdiagram.com/bikashpandeya/test_alterecho
- Repository: https://github.com/bikashpandeya/test_alterecho

## Overview

TerraLuna AI lets users explore Earth terrain candidates and compare them with a Mars reference. The main workflow runs from the dashboard through the frontend API client to FastAPI discovery: the comparison route selects real or demo summaries, checks compatibility, computes similarity, and returns ranked results. A separate provenance workflow acquires DEM data, harmonizes it to versioned AOIs, computes terrain metrics, and records quality and provenance for API use. The graph includes documented visualization and source-management capabilities; unsampled implementation details are omitted where their call relationships cannot be verified.

Main entry points: [`backend/app/services/geospatial_service.py`](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/geospatial_service.py) (Geospatial processing), [`frontend/app/page.tsx`](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/page.tsx) (Dashboard), [`backend/app/services/catalog_service.py`](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/catalog_service.py) (Catalog service), [`backend/app/main.py`](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Explorer interface"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_candidate_map["Candidate map<br/>[CandidateMap.tsx]"]
  node_planet_selector["Planet selector<br/>[PlanetSelector.tsx]"]
  node_planet_viewer["Planet viewer<br/>[PlanetViewer.tsx]"]
  node_space_scene["Space scene<br/>[SpaceScene.tsx]"]
end

subgraph group_api["API and discovery"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_catalog_routes["Catalog routes<br/>[catalog.py]"]
  node_comparison_routes["Discovery route<br/>[comparison.py]"]
  node_geospatial_routes["Geospatial routes<br/>[geospatial.py]"]
  node_health_routes["Health route<br/>[health.py]"]
  node_similarity["Similarity engine"]
  node_explanation["Result explanations"]
end

subgraph group_terrain["Terrain processing"]
  node_geospatial["Geospatial processing"]
  node_terrain_metrics["Terrain metrics<br/>[terrain_service.py]"]
  node_srtm["SRTM acquisition<br/>[srtm_service.py]"]
  node_processing_cli["Dataset processing<br/>[process_site.py]"]
  node_acquisition_cli["Dataset acquisition<br/>[acquire_dataset.py]"]
end

subgraph group_catalogdata["Catalog and provenance"]
  node_catalog_service["Catalog service<br/>[catalog_service.py]"]
  node_site_data["Site catalog<br/>[sites.json]"]
  node_similarity_config["Similarity configuration<br/>[similarity.v2.json]"]
  node_processed_data[("Processed terrain summaries")]
  node_aoi_data["Versioned AOIs"]
  node_source_manifests["Source manifests"]
end

node_user(("Explorer"))
node_backend_service(("Backend API"))

node_user -->|"explores"| node_dashboard
node_dashboard -->|"renders"| node_planet_selector
node_dashboard -->|"renders"| node_candidate_map
node_dashboard -->|"renders"| node_space_scene
node_dashboard -->|"renders"| node_planet_viewer
node_dashboard -->|"requests data"| node_api_client
node_api_client -->|"calls HTTP API"| node_backend_service
node_api_app -->|"registers"| node_catalog_routes
node_api_app -->|"registers"| node_comparison_routes
node_api_app -->|"registers"| node_geospatial_routes
node_api_app -->|"registers"| node_health_routes
node_catalog_routes -->|"calls"| node_catalog_service
node_comparison_routes -->|"loads summaries"| node_catalog_service
node_comparison_routes -->|"compares features"| node_similarity
node_comparison_routes -->|"builds explanations"| node_explanation
node_geospatial_routes -->|"loads catalog"| node_catalog_service
node_geospatial_routes -->|"reads provenance"| node_geospatial
node_similarity -->|"loads configuration"| node_similarity_config
node_catalog_service -->|"reads"| node_site_data
node_catalog_service -->|"reads summaries"| node_processed_data
node_catalog_service -->|"validates data"| node_schemas
node_processing_cli -->|"processes site"| node_geospatial
node_acquisition_cli -->|"acquires tiles"| node_srtm
node_acquisition_cli -->|"uses geospatial tools"| node_geospatial
node_geospatial -->|"computes summaries"| node_terrain_metrics
node_geospatial -->|"uses AOIs"| node_aoi_data
node_geospatial -->|"records provenance"| node_source_manifests
node_geospatial -->|"writes summaries"| node_processed_data
node_api_client -->|"provides map types"| node_candidate_map

click node_dashboard "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/page.tsx"
click node_api_client "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/lib/api.ts"
click node_candidate_map "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/CandidateMap.tsx"
click node_planet_selector "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/PlanetSelector.tsx"
click node_planet_viewer "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/PlanetViewer.tsx"
click node_space_scene "https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/SpaceScene.tsx"
click node_api_app "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/main.py"
click node_schemas "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/models/schemas.py"
click node_catalog_routes "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/catalog.py"
click node_comparison_routes "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/comparison.py"
click node_geospatial_routes "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/geospatial.py"
click node_health_routes "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/health.py"
click node_catalog_service "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/catalog_service.py"
click node_similarity "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/similarity_service.py"
click node_explanation "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/explanation_service.py"
click node_geospatial "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/geospatial_service.py"
click node_terrain_metrics "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/terrain_service.py"
click node_srtm "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/srtm_service.py"
click node_processing_cli "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/scripts/process_site.py"
click node_acquisition_cli "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/scripts/acquire_dataset.py"
click node_site_data "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/data/sites.json"
click node_similarity_config "https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/data/similarity.v2.json"
click node_processed_data "https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/processed"
click node_aoi_data "https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/aoi"
click node_source_manifests "https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/manifests"

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_dashboard,node_api_client,node_candidate_map,node_planet_selector,node_planet_viewer,node_space_scene toneBlue
class node_api_app,node_schemas,node_catalog_routes,node_comparison_routes,node_geospatial_routes,node_health_routes,node_similarity,node_explanation toneAmber
class node_geospatial,node_terrain_metrics,node_srtm,node_processing_cli,node_acquisition_cli,node_backend_service toneMint
class node_catalog_service,node_site_data,node_similarity_config,node_processed_data,node_aoi_data,node_source_manifests toneRose
class node_user toneIndigo
```

## Components

### Explorer interface

- [Dashboard](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [API client](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Candidate map](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/CandidateMap.tsx): `frontend/app/components/CandidateMap.tsx`
- [Planet selector](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/PlanetSelector.tsx): `frontend/app/components/PlanetSelector.tsx`
- [Planet viewer](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/PlanetViewer.tsx): `frontend/app/components/PlanetViewer.tsx`
- [Space scene](https://github.com/bikashpandeya/test_alterecho/blob/main/frontend/app/components/SpaceScene.tsx): `frontend/app/components/SpaceScene.tsx`

### API and discovery

- [FastAPI application](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/main.py): `backend/app/main.py`
- [API schemas](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Catalog routes](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/catalog.py): `backend/app/routers/catalog.py`
- [Discovery route](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/comparison.py): `backend/app/routers/comparison.py`
- [Geospatial routes](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/geospatial.py): `backend/app/routers/geospatial.py`
- [Health route](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/routers/health.py): `backend/app/routers/health.py`
- [Similarity engine](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/similarity_service.py): `backend/app/services/similarity_service.py`
- [Result explanations](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/explanation_service.py): `backend/app/services/explanation_service.py`

### Terrain processing

- [Geospatial processing](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/geospatial_service.py): `backend/app/services/geospatial_service.py`
- [Terrain metrics](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/terrain_service.py): `backend/app/services/terrain_service.py`
- [SRTM acquisition](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/srtm_service.py): `backend/app/services/srtm_service.py`
- [Dataset processing](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/scripts/process_site.py): `backend/app/scripts/process_site.py`
- [Dataset acquisition](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/scripts/acquire_dataset.py): `backend/app/scripts/acquire_dataset.py`

### Catalog and provenance

- [Catalog service](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/services/catalog_service.py): `backend/app/services/catalog_service.py`
- [Site catalog](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/data/sites.json): `backend/app/data/sites.json`
- [Similarity configuration](https://github.com/bikashpandeya/test_alterecho/blob/main/backend/app/data/similarity.v2.json): `backend/app/data/similarity.v2.json`
- [Processed terrain summaries](https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/processed): `backend/data/processed`
- [Versioned AOIs](https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/aoi): `backend/data/aoi`
- [Source manifests](https://github.com/bikashpandeya/test_alterecho/tree/main/backend/data/manifests): `backend/data/manifests`

### Other components

- **Explorer**
- **Backend API**

## Connections

- Explorer → Dashboard: explores (evidence: `README.md`)
- Dashboard → Planet selector: renders (evidence: `frontend/app/page.tsx`)
- Dashboard → Candidate map: renders (evidence: `frontend/app/page.tsx`)
- Dashboard → Space scene: renders (evidence: `frontend/app/page.tsx`)
- Dashboard → Planet viewer: renders (evidence: `frontend/app/page.tsx`)
- Dashboard → API client: requests data (evidence: `frontend/app/page.tsx`)
- API client → Backend API: calls HTTP API (evidence: `README.md`)
- FastAPI application → Catalog routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Discovery route: registers (evidence: `backend/app/main.py`)
- FastAPI application → Geospatial routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Health route: registers (evidence: `backend/app/main.py`)
- Catalog routes → Catalog service: calls (evidence: `backend/app/routers/catalog.py`)
- Discovery route → Catalog service: loads summaries (evidence: `backend/app/routers/comparison.py`)
- Discovery route → Similarity engine: compares features (evidence: `backend/app/routers/comparison.py`)
- Discovery route → Result explanations: builds explanations (evidence: `backend/app/routers/comparison.py`)
- Geospatial routes → Catalog service: loads catalog (evidence: `backend/app/routers/geospatial.py`)
- Geospatial routes → Geospatial processing: reads provenance (evidence: `backend/app/routers/geospatial.py`)
- Similarity engine → Similarity configuration: loads configuration (evidence: `README.md`)
- Catalog service → Site catalog: reads (evidence: `backend/app/services/catalog_service.py`)
- Catalog service → Processed terrain summaries: reads summaries (evidence: `backend/app/services/catalog_service.py`)
- Catalog service → API schemas: validates data (evidence: `backend/app/services/catalog_service.py`)
- Dataset processing → Geospatial processing: processes site (evidence: `backend/app/scripts/process_site.py`)
- Dataset acquisition → SRTM acquisition: acquires tiles (evidence: `backend/app/scripts/acquire_dataset.py`)
- Dataset acquisition → Geospatial processing: uses geospatial tools (evidence: `backend/app/scripts/acquire_dataset.py`)
- Geospatial processing → Terrain metrics: computes summaries (evidence: `backend/app/services/geospatial_service.py`)
- Geospatial processing → Versioned AOIs: uses AOIs (evidence: `README.md`)
- Geospatial processing → Source manifests: records provenance (evidence: `README.md`)
- Geospatial processing → Processed terrain summaries: writes summaries (evidence: `backend/app/services/geospatial_service.py`)
- API client → Candidate map: provides map types (evidence: `frontend/app/components/CandidateMap.tsx`)