# rjoel158/tarpuy-nasa-cochabamba- architecture

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

- Interactive diagram: https://gitdiagram.com/rjoel158/tarpuy-nasa-cochabamba-
- Repository: https://github.com/rjoel158/tarpuy-nasa-cochabamba-

## Overview

Tarpuy is an offline-first, bilingual agricultural decision-support PWA for Cochabamba producers. The main journey is location and zone selection, weather and municipal context retrieval, comparative crop-rotation recommendations and alerts, then visual and audio guidance; saved bundles support offline use. The README also describes satellite/climate ingestion and printable materials. The documented architecture supplies some links beyond the excerpts; where implementation wiring was not shown, those links are marked dashed or omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/App.jsx) (PWA application), [`backend/main.py`](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/main.py) (FastAPI), [`engine/recommender.py`](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/recommender.py) (Rotation recommendations), [`frontend/src/services/apiClient.js`](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/apiClient.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Climate ingestion"]
  node_etl["Data harmonization<br/>[harmonizer.py]"]
  node_weather_ingest["Weather clients"]
  node_district_ingest["District data<br/>[gamc_districts.py]"]
end

subgraph group_domain["Agronomy engine"]
  node_zones[("Zone repository<br/>[recommender.py]")]
  node_recommend["Rotation recommendations<br/>[recommender.py]"]
  node_scoring["Strategy scoring<br/>[scoring.py]"]
  node_categories["Crop categories<br/>[categories.py]"]
  node_periurban["Municipal context<br/>[periurban.py]"]
  node_alerts["Weather alerts<br/>[alerts.py]"]
end

subgraph group_service["API services"]
  node_api["FastAPI<br/>[main.py]"]
  node_gamc_proxy["GAMC proxy<br/>[gamc.py]"]
  node_poster["Printable materials<br/>[poster.py]"]
end

subgraph group_client["Producer PWA"]
  node_app["PWA application<br/>[App.jsx]"]
  node_producer_mode["Producer mode<br/>[ProducerMode.jsx]"]
  node_technical_mode["Technical mode<br/>[TechnicalMode.jsx]"]
  node_map["Cochabamba map<br/>[CochabambaMap.jsx]"]
end

subgraph group_offline["Offline and audio"]
  node_api_client["API client<br/>[apiClient.js]"]
  node_device_store[("Device snapshot store<br/>[embeddedDb.js]")]
  node_speech["Speech playback<br/>[speechService.js]"]
  node_narration["Bilingual narration<br/>[narration.js]"]
  node_tts["Quechua and Spanish TTS"]
end

node_producer(("Producer"))
node_nasa[("NASA and climate sources")]
node_weather_provider["Weather provider"]
node_gamc["GAMC map services"]

node_producer -->|"uses"| node_app
node_nasa -->|"feeds"| node_etl
node_etl -.->|"harmonizes data"| node_zones
node_weather_provider -->|"supplies forecasts"| node_weather_ingest
node_weather_ingest -->|"provides weather"| node_api
node_district_ingest -.->|"provides districts"| node_gamc_proxy
node_zones -->|"supplies zones"| node_recommend
node_recommend -->|"scores strategies"| node_scoring
node_recommend -->|"uses categories"| node_categories
node_recommend -->|"builds context"| node_periurban
node_api -->|"requests recommendations"| node_recommend
node_api -->|"evaluates alerts"| node_alerts
node_api -.->|"generates materials"| node_poster
node_api -.->|"routes map requests"| node_gamc_proxy
node_app -->|"fetches alerts"| node_api_client
node_app -->|"loads snapshot"| node_device_store
node_app -.->|"requests map context"| node_gamc_proxy
node_app -->|"renders"| node_producer_mode
node_app -->|"renders"| node_technical_mode
node_app -->|"renders"| node_map
node_api_client -->|"saves offline bundles"| node_device_store
node_api_client -->|"calls recommendations"| node_api
node_map -->|"queries map services"| node_gamc
node_speech -->|"builds narration"| node_narration
node_speech -.->|"requests generated audio"| node_tts
node_api -->|"generates audio"| node_tts

click node_etl "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/harmonizer.py"
click node_weather_ingest "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/realtime_weather_client.py"
click node_district_ingest "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/gamc_districts.py"
click node_zones "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/recommender.py"
click node_recommend "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/recommender.py"
click node_scoring "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/scoring.py"
click node_categories "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/categories.py"
click node_periurban "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/periurban.py"
click node_alerts "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/alerts.py"
click node_api "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/main.py"
click node_gamc_proxy "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/gamc.py"
click node_poster "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/poster.py"
click node_app "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/App.jsx"
click node_producer_mode "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/ProducerMode.jsx"
click node_technical_mode "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/TechnicalMode.jsx"
click node_map "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/maps/CochabambaMap.jsx"
click node_api_client "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/apiClient.js"
click node_device_store "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/embeddedDb.js"
click node_speech "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/speechService.js"
click node_narration "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/narration.js"
click node_tts "https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/quechua_tts_client.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_etl,node_weather_ingest,node_district_ingest toneBlue
class node_zones,node_recommend,node_scoring,node_categories,node_periurban,node_alerts,node_nasa toneAmber
class node_api,node_gamc_proxy,node_poster toneMint
class node_app,node_producer_mode,node_technical_mode,node_map toneRose
class node_api_client,node_device_store,node_speech,node_narration,node_tts,node_producer,node_weather_provider,node_gamc toneIndigo
```

## Components

### Climate ingestion

- [Data harmonization](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/harmonizer.py): `etl/harmonizer.py`
- [Weather clients](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/realtime_weather_client.py): `etl/realtime_weather_client.py`
- [District data](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/gamc_districts.py): `etl/gamc_districts.py`

### Agronomy engine

- [Zone repository](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/recommender.py): `engine/recommender.py`
- [Rotation recommendations](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/recommender.py): `engine/recommender.py`
- [Strategy scoring](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/scoring.py): `engine/scoring.py`
- [Crop categories](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/categories.py): `engine/categories.py`
- [Municipal context](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/periurban.py): `engine/periurban.py`
- [Weather alerts](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/engine/alerts.py): `engine/alerts.py`

### API services

- [FastAPI](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/main.py): `backend/main.py`
- [GAMC proxy](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/gamc.py): `backend/gamc.py`
- [Printable materials](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/backend/poster.py): `backend/poster.py`

### Producer PWA

- [PWA application](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Producer mode](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/ProducerMode.jsx): `frontend/src/components/ProducerMode.jsx`
- [Technical mode](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/TechnicalMode.jsx): `frontend/src/components/TechnicalMode.jsx`
- [Cochabamba map](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/components/maps/CochabambaMap.jsx): `frontend/src/components/maps/CochabambaMap.jsx`

### Offline and audio

- [API client](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/apiClient.js): `frontend/src/services/apiClient.js`
- [Device snapshot store](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/embeddedDb.js): `frontend/src/services/embeddedDb.js`
- [Speech playback](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/speechService.js): `frontend/src/services/speechService.js`
- [Bilingual narration](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/frontend/src/services/narration.js): `frontend/src/services/narration.js`
- [Quechua and Spanish TTS](https://github.com/rjoel158/tarpuy-nasa-cochabamba-/blob/main/etl/quechua_tts_client.py): `etl/quechua_tts_client.py`

### Other components

- **Producer**
- **NASA and climate sources**
- **Weather provider**
- **GAMC map services**

## Connections

- Producer → PWA application: uses (evidence: `README.md`)
- NASA and climate sources → Data harmonization: feeds (evidence: `README.md`)
- Data harmonization → Zone repository: harmonizes data
- Weather provider → Weather clients: supplies forecasts (evidence: `etl/realtime_weather_client.py`)
- Weather clients → FastAPI: provides weather (evidence: `backend/main.py`)
- District data → GAMC proxy: provides districts
- Zone repository → Rotation recommendations: supplies zones (evidence: `engine/recommender.py`)
- Rotation recommendations → Strategy scoring: scores strategies (evidence: `engine/recommender.py`)
- Rotation recommendations → Crop categories: uses categories (evidence: `engine/recommender.py`)
- Rotation recommendations → Municipal context: builds context (evidence: `engine/recommender.py`)
- FastAPI → Rotation recommendations: requests recommendations (evidence: `backend/main.py`)
- FastAPI → Weather alerts: evaluates alerts (evidence: `backend/main.py`)
- FastAPI → Printable materials: generates materials (evidence: `backend/main.py`)
- FastAPI → GAMC proxy: routes map requests (evidence: `backend/main.py`)
- PWA application → API client: fetches alerts (evidence: `frontend/src/App.jsx`)
- PWA application → Device snapshot store: loads snapshot (evidence: `frontend/src/App.jsx`)
- PWA application → GAMC proxy: requests map context
- PWA application → Producer mode: renders (evidence: `frontend/src/App.jsx`)
- PWA application → Technical mode: renders (evidence: `frontend/src/App.jsx`)
- PWA application → Cochabamba map: renders (evidence: `frontend/src/App.jsx`)
- API client → Device snapshot store: saves offline bundles (evidence: `frontend/src/services/apiClient.js`)
- API client → FastAPI: calls recommendations (evidence: `frontend/src/services/apiClient.js`)
- Cochabamba map → GAMC map services: queries map services (evidence: `frontend/src/components/maps/CochabambaMap.jsx`)
- Speech playback → Bilingual narration: builds narration (evidence: `frontend/src/services/speechService.js`)
- Speech playback → Quechua and Spanish TTS: requests generated audio
- FastAPI → Quechua and Spanish TTS: generates audio (evidence: `backend/main.py`)
