# mr-melenas/pathfinders42-back architecture

> Architecture diagram of the GitHub repository mr-melenas/pathfinders42-back, 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/mr-melenas/pathfinders42-back
- Repository: https://github.com/mr-melenas/pathfinders42-back

## Overview

Pathfinders42 is a FastAPI backend that serves precomputed Earth-analogue results for lunar and Martian sites; it does not run the heavy comparison models in the API. The main workflow is API request → endpoint router → shared data access and domain-specific assembly → JSON, GeoJSON, or map response. Major branches include site and layer comparisons, ice verdicts, M1 candidate results, and explanations with document retrieval and optional web/LLM chat. The README documents several endpoints whose internal implementation was not sampled; those routes are represented without speculative internal call chains.

Main entry points: [`app/main.py`](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/main.py) (FastAPI app), [`app/dependencias.py`](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/dependencias.py) (Data dependency), [`app/datos.py`](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/datos.py) (Manifest data access), [`app/explanations/router.py`](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/router.py) (Explanation routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI app<br/>[main.py]"]
  node_health["Health and metadata<br/>[salud.py]"]
  node_layers["Layer endpoints<br/>[capas.py]"]
  node_sites_api["Site endpoints<br/>[sitios.py]"]
  node_candidates_api["Candidate endpoints<br/>[candidatos.py]"]
  node_ice_api["Ice endpoints<br/>[hielo.py]"]
  node_uses_api["Use endpoints<br/>[usos.py]"]
  node_analogues_api["Analogue endpoints<br/>[analogos.py]"]
  node_dependency["Data dependency<br/>[dependencias.py]"]
end

subgraph group_domain["Analogue domains"]
  node_data_access[("Manifest data access<br/>[datos.py]")]
  node_site_index["Site layer index<br/>[sitios.py]"]
  node_ice_results["Ice verdicts<br/>[hielo.py]"]
  node_analogue_results["Analogue results<br/>[analogos.py]"]
  node_use_results["Use results<br/>[usos.py]"]
end

subgraph group_explain["Explanations"]
  node_explanation_api["Explanation routes<br/>[router.py]"]
  node_text_index[("BM25 text index<br/>[index.py]")]
  node_retrieval["Document retrieval<br/>[retrieval.py]"]
  node_writer["Validated writer<br/>[writer.py]"]
  node_validator["Answer validator<br/>[validator.py]"]
  node_web_search["Web search<br/>[web.py]"]
  node_llm_client["LLM API client<br/>[llm.py]"]
end

subgraph group_model["M1 candidate model"]
  node_candidates["M1 result reader<br/>[m1.py]"]
  node_trainer["M1 training<br/>[entrenar.py]"]
  node_grid["Earth grid<br/>[rejilla.py]"]
end

node_client(("API client"))
node_external_llm{{"LLM service"}}

node_client -->|"requests"| node_app
node_app -->|"routes to"| node_health
node_app -->|"routes to"| node_layers
node_app -->|"routes to"| node_sites_api
node_app -->|"routes to"| node_candidates_api
node_app -->|"routes to"| node_ice_api
node_app -->|"routes to"| node_uses_api
node_app -->|"routes to"| node_analogues_api
node_app -->|"routes to"| node_explanation_api
node_health -->|"gets data"| node_dependency
node_layers -->|"gets data"| node_dependency
node_sites_api -->|"gets data"| node_dependency
node_candidates_api -->|"gets data"| node_dependency
node_ice_api -->|"gets data"| node_dependency
node_uses_api -->|"gets data"| node_dependency
node_analogues_api -->|"gets data"| node_dependency
node_dependency -->|"loads"| node_data_access
node_data_access -->|"builds"| node_site_index
node_data_access -->|"builds"| node_ice_results
node_data_access -->|"builds"| node_analogue_results
node_data_access -->|"builds"| node_use_results
node_data_access -->|"builds"| node_candidates
node_sites_api -->|"serves site data"| node_site_index
node_ice_api -->|"serves ice data"| node_ice_results
node_uses_api -->|"serves use data"| node_use_results
node_analogues_api -->|"serves analogues"| node_analogue_results
node_candidates_api -->|"serves results"| node_candidates
node_explanation_api -->|"retrieves fragments"| node_retrieval
node_explanation_api -->|"writes answer"| node_writer
node_explanation_api -.->|"optional search"| node_web_search
node_explanation_api -.->|"loads explanations"| node_text_index
node_retrieval -->|"searches"| node_text_index
node_writer -.->|"validates"| node_validator
node_writer -.->|"generates draft"| node_llm_client
node_llm_client -->|"calls API"| node_external_llm
node_trainer -->|"uses grid"| node_grid

click node_app "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/main.py"
click node_health "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/salud.py"
click node_layers "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/capas.py"
click node_sites_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/sitios.py"
click node_candidates_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/candidatos.py"
click node_ice_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/hielo.py"
click node_uses_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/usos.py"
click node_analogues_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/analogos.py"
click node_data_access "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/datos.py"
click node_dependency "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/dependencias.py"
click node_site_index "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/sitios.py"
click node_ice_results "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/hielo.py"
click node_analogue_results "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/analogos.py"
click node_use_results "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/usos.py"
click node_explanation_api "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/router.py"
click node_text_index "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/index.py"
click node_retrieval "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/retrieval.py"
click node_writer "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/writer.py"
click node_validator "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/validator.py"
click node_web_search "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/web.py"
click node_llm_client "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/llm.py"
click node_candidates "https://github.com/mr-melenas/pathfinders42-back/blob/main/app/m1.py"
click node_trainer "https://github.com/mr-melenas/pathfinders42-back/blob/main/modelos/m1/entrenar.py"
click node_grid "https://github.com/mr-melenas/pathfinders42-back/blob/main/modelos/m1/rejilla.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_app,node_health,node_layers,node_sites_api,node_candidates_api,node_ice_api,node_uses_api,node_analogues_api,node_dependency,node_client toneBlue
class node_data_access,node_site_index,node_ice_results,node_analogue_results,node_use_results toneAmber
class node_explanation_api,node_text_index,node_retrieval,node_writer,node_validator,node_web_search,node_llm_client toneMint
class node_candidates,node_trainer,node_grid toneRose
class node_external_llm toneIndigo
```

## Components

### API surface

- [FastAPI app](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/main.py): `app/main.py`
- [Health and metadata](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/salud.py): `app/routers/salud.py`
- [Layer endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/capas.py): `app/routers/capas.py`
- [Site endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/sitios.py): `app/routers/sitios.py`
- [Candidate endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/candidatos.py): `app/routers/candidatos.py`
- [Ice endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/hielo.py): `app/routers/hielo.py`
- [Use endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/usos.py): `app/routers/usos.py`
- [Analogue endpoints](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/routers/analogos.py): `app/routers/analogos.py`
- [Data dependency](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/dependencias.py): `app/dependencias.py`

### Analogue domains

- [Manifest data access](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/datos.py): `app/datos.py`
- [Site layer index](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/sitios.py): `app/sitios.py`
- [Ice verdicts](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/hielo.py): `app/hielo.py`
- [Analogue results](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/analogos.py): `app/analogos.py`
- [Use results](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/usos.py): `app/usos.py`

### Explanations

- [Explanation routes](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/router.py): `app/explanations/router.py`
- [BM25 text index](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/index.py): `app/explanations/index.py`
- [Document retrieval](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/retrieval.py): `app/explanations/retrieval.py`
- [Validated writer](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/writer.py): `app/explanations/writer.py`
- [Answer validator](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/validator.py): `app/explanations/validator.py`
- [Web search](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/web.py): `app/explanations/web.py`
- [LLM API client](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/explanations/llm.py): `app/explanations/llm.py`

### M1 candidate model

- [M1 result reader](https://github.com/mr-melenas/pathfinders42-back/blob/main/app/m1.py): `app/m1.py`
- [M1 training](https://github.com/mr-melenas/pathfinders42-back/blob/main/modelos/m1/entrenar.py): `modelos/m1/entrenar.py`
- [Earth grid](https://github.com/mr-melenas/pathfinders42-back/blob/main/modelos/m1/rejilla.py): `modelos/m1/rejilla.py`

### Other components

- **API client**
- **LLM service**

## Connections

- API client → FastAPI app: requests (evidence: `README.md`)
- FastAPI app → Health and metadata: routes to (evidence: `app/main.py`)
- FastAPI app → Layer endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Site endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Candidate endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Ice endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Use endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Analogue endpoints: routes to (evidence: `app/main.py`)
- FastAPI app → Explanation routes: routes to (evidence: `app/main.py`)
- Health and metadata → Data dependency: gets data (evidence: `app/routers/salud.py`)
- Layer endpoints → Data dependency: gets data (evidence: `app/routers/capas.py`)
- Site endpoints → Data dependency: gets data (evidence: `app/routers/sitios.py`)
- Candidate endpoints → Data dependency: gets data (evidence: `app/routers/candidatos.py`)
- Ice endpoints → Data dependency: gets data (evidence: `app/routers/hielo.py`)
- Use endpoints → Data dependency: gets data (evidence: `app/routers/usos.py`)
- Analogue endpoints → Data dependency: gets data (evidence: `app/routers/analogos.py`)
- Data dependency → Manifest data access: loads (evidence: `app/dependencias.py`)
- Manifest data access → Site layer index: builds (evidence: `app/datos.py`)
- Manifest data access → Ice verdicts: builds (evidence: `app/datos.py`)
- Manifest data access → Analogue results: builds (evidence: `app/datos.py`)
- Manifest data access → Use results: builds (evidence: `app/datos.py`)
- Manifest data access → M1 result reader: builds (evidence: `app/datos.py`)
- Site endpoints → Site layer index: serves site data (evidence: `app/routers/sitios.py`)
- Ice endpoints → Ice verdicts: serves ice data (evidence: `app/routers/hielo.py`)
- Use endpoints → Use results: serves use data (evidence: `app/routers/usos.py`)
- Analogue endpoints → Analogue results: serves analogues (evidence: `app/routers/analogos.py`)
- Candidate endpoints → M1 result reader: serves results (evidence: `app/routers/candidatos.py`)
- Explanation routes → Document retrieval: retrieves fragments (evidence: `app/explanations/router.py`)
- Explanation routes → Validated writer: writes answer (evidence: `app/explanations/router.py`)
- Explanation routes → Web search: optional search (evidence: `app/explanations/router.py`)
- Explanation routes → BM25 text index: loads explanations (evidence: `app/explanations/router.py`)
- Document retrieval → BM25 text index: searches (evidence: `app/explanations/retrieval.py`)
- Validated writer → Answer validator: validates (evidence: `app/explanations/writer.py`)
- Validated writer → LLM API client: generates draft (evidence: `app/explanations/llm.py`)
- LLM API client → LLM service: calls API (evidence: `app/explanations/llm.py`)
- M1 training → Earth grid: uses grid (evidence: `modelos/m1/entrenar.py`)