# dma-teams/nasa-app-api architecture

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

- Interactive diagram: https://gitdiagram.com/dma-teams/nasa-app-api
- Repository: https://github.com/dma-teams/nasa-app-api

## Overview

This is a Go crop-rotation recommendation API backed by a separately run data-loading pipeline. ETL gathers climate, soil, forecast, and boundary data into versioned Redis datasets; API requests locate a municipality, retrieve its prepared data, simulate and score crop rotations, and return structured recommendations. The README also documents crop and administrative listings, health and API documentation endpoints, and a calibration workflow. Relationships below follow excerpts, SOURCE INDEX references, or README statements; unsampled internals are not assumed to have unshown calls.

Main entry points: [`internal/store/store.go`](https://github.com/dma-teams/nasa-app-api/blob/master/internal/store/store.go) (Versioned datasets), [`internal/httpapi/handlers.go`](https://github.com/dma-teams/nasa-app-api/blob/master/internal/httpapi/handlers.go) (HTTP handlers), [`internal/plan/service.go`](https://github.com/dma-teams/nasa-app-api/blob/master/internal/plan/service.go) (Plan service), [`internal/etl/build.go`](https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/build.go) (Dataset builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_etl_command["ETL command<br/>[main.go]"]
  node_etl_builder["Dataset builder<br/>[build.go]"]
  node_etl_soil["Soil processing<br/>[soil.go]"]
  node_etl_forecast["Forecast loading<br/>[forecast.go]"]
  node_source_clients["Source clients"]
end

subgraph group_domain["Agronomy and geography"]
  node_agro_engine["Rotation engine<br/>[engine.go]"]
  node_agro_evaluation["Scoring and evaluation<br/>[evaluator.go]"]
  node_site_profile["Site profiles<br/>[profile.go]"]
  node_crop_catalog["Crop catalog<br/>[crops_data.go]"]
  node_geo_index["Municipal geography<br/>[geo.go]"]
end

subgraph group_serving["Recommendation API"]
  node_api_command["API startup<br/>[main.go]"]
  node_http_handlers["HTTP handlers<br/>[handlers.go]"]
  node_plan_service["Plan service<br/>[service.go]"]
  node_department_plans["Department plans<br/>[department.go]"]
end

subgraph group_persistence["Redis storage"]
  node_redis_store[("Versioned datasets<br/>[store.go]")]
  node_series_codec["Climate codec<br/>[codec.go]"]
end

subgraph group_calibration["Calibration"]
  node_calibrate_command["Calibration command<br/>[main.go]"]
  node_imerg_download["IMERG downloader<br/>[imerg.go]"]
  node_canicula_report["Canícula analysis<br/>[canicula.go]"]
end

node_redis_service[("Redis")]
node_requester(("API user"))
node_data_providers["Climate and soil providers"]

node_etl_command -->|"runs build"| node_etl_builder
node_etl_command -->|"configures clients"| node_source_clients
node_etl_command -->|"configures storage"| node_redis_store
node_etl_builder -->|"fetches inputs"| node_source_clients
node_etl_builder -->|"writes datasets"| node_redis_store
node_etl_builder -->|"builds profiles"| node_site_profile
node_etl_soil -->|"gets soil data"| node_source_clients
node_etl_forecast -->|"gets forecasts"| node_source_clients
node_etl_forecast -.->|"writes forecasts"| node_redis_store
node_redis_store -->|"reads and writes"| node_redis_service
node_redis_store -->|"encodes climate"| node_series_codec
node_requester -->|"requests plan"| node_http_handlers
node_api_command -->|"loads datasets"| node_redis_store
node_api_command -->|"wires service"| node_plan_service
node_api_command -->|"starts API"| node_http_handlers
node_http_handlers -->|"locates municipality"| node_geo_index
node_http_handlers -->|"requests plan"| node_plan_service
node_http_handlers -.->|"serves crop listing"| node_crop_catalog
node_plan_service -->|"evaluates rotation"| node_agro_engine
node_agro_engine -->|"scores candidates"| node_agro_evaluation
node_plan_service -->|"loads prepared data"| node_redis_store
node_plan_service -.->|"aggregates departments"| node_department_plans
node_calibrate_command -->|"runs download"| node_imerg_download
node_calibrate_command -->|"runs analysis"| node_canicula_report
node_imerg_download -->|"downloads IMERG"| node_data_providers

click node_etl_command "https://github.com/dma-teams/nasa-app-api/blob/master/cmd/etl/main.go"
click node_etl_builder "https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/build.go"
click node_etl_soil "https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/soil.go"
click node_etl_forecast "https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/forecast.go"
click node_source_clients "https://github.com/dma-teams/nasa-app-api/tree/master/internal/sources"
click node_agro_engine "https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/engine.go"
click node_agro_evaluation "https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/evaluator.go"
click node_site_profile "https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/profile.go"
click node_crop_catalog "https://github.com/dma-teams/nasa-app-api/blob/master/internal/catalog/crops_data.go"
click node_geo_index "https://github.com/dma-teams/nasa-app-api/blob/master/internal/geo/geo.go"
click node_api_command "https://github.com/dma-teams/nasa-app-api/blob/master/cmd/api/main.go"
click node_http_handlers "https://github.com/dma-teams/nasa-app-api/blob/master/internal/httpapi/handlers.go"
click node_plan_service "https://github.com/dma-teams/nasa-app-api/blob/master/internal/plan/service.go"
click node_department_plans "https://github.com/dma-teams/nasa-app-api/blob/master/internal/plan/department.go"
click node_redis_store "https://github.com/dma-teams/nasa-app-api/blob/master/internal/store/store.go"
click node_series_codec "https://github.com/dma-teams/nasa-app-api/blob/master/internal/store/codec.go"
click node_calibrate_command "https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/main.go"
click node_imerg_download "https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/imerg.go"
click node_canicula_report "https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/canicula.go"

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_command,node_etl_builder,node_etl_soil,node_etl_forecast,node_source_clients,node_requester toneBlue
class node_agro_engine,node_agro_evaluation,node_site_profile,node_crop_catalog,node_geo_index,node_redis_service toneAmber
class node_api_command,node_http_handlers,node_plan_service,node_department_plans toneMint
class node_redis_store,node_series_codec toneRose
class node_calibrate_command,node_imerg_download,node_canicula_report,node_data_providers toneIndigo
```

## Components

### Data ingestion

- [ETL command](https://github.com/dma-teams/nasa-app-api/blob/master/cmd/etl/main.go): `cmd/etl/main.go`
- [Dataset builder](https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/build.go): `internal/etl/build.go`
- [Soil processing](https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/soil.go): `internal/etl/soil.go`
- [Forecast loading](https://github.com/dma-teams/nasa-app-api/blob/master/internal/etl/forecast.go): `internal/etl/forecast.go`
- [Source clients](https://github.com/dma-teams/nasa-app-api/tree/master/internal/sources): `internal/sources`

### Agronomy and geography

- [Rotation engine](https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/engine.go): `internal/agro/engine.go`
- [Scoring and evaluation](https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/evaluator.go): `internal/agro/evaluator.go`
- [Site profiles](https://github.com/dma-teams/nasa-app-api/blob/master/internal/agro/profile.go): `internal/agro/profile.go`
- [Crop catalog](https://github.com/dma-teams/nasa-app-api/blob/master/internal/catalog/crops_data.go): `internal/catalog/crops_data.go`
- [Municipal geography](https://github.com/dma-teams/nasa-app-api/blob/master/internal/geo/geo.go): `internal/geo/geo.go`

### Recommendation API

- [API startup](https://github.com/dma-teams/nasa-app-api/blob/master/cmd/api/main.go): `cmd/api/main.go`
- [HTTP handlers](https://github.com/dma-teams/nasa-app-api/blob/master/internal/httpapi/handlers.go): `internal/httpapi/handlers.go`
- [Plan service](https://github.com/dma-teams/nasa-app-api/blob/master/internal/plan/service.go): `internal/plan/service.go`
- [Department plans](https://github.com/dma-teams/nasa-app-api/blob/master/internal/plan/department.go): `internal/plan/department.go`

### Redis storage

- [Versioned datasets](https://github.com/dma-teams/nasa-app-api/blob/master/internal/store/store.go): `internal/store/store.go`
- [Climate codec](https://github.com/dma-teams/nasa-app-api/blob/master/internal/store/codec.go): `internal/store/codec.go`

### Calibration

- [Calibration command](https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/main.go): `cmd/calibrate/main.go`
- [IMERG downloader](https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/imerg.go): `cmd/calibrate/imerg.go`
- [Canícula analysis](https://github.com/dma-teams/nasa-app-api/blob/master/cmd/calibrate/canicula.go): `cmd/calibrate/canicula.go`

### Other components

- **Redis**
- **API user**
- **Climate and soil providers**

## Connections

- ETL command → Dataset builder: runs build (evidence: `cmd/etl/main.go`)
- ETL command → Source clients: configures clients (evidence: `cmd/etl/main.go`)
- ETL command → Versioned datasets: configures storage (evidence: `cmd/etl/main.go`)
- Dataset builder → Source clients: fetches inputs (evidence: `internal/etl/build.go`)
- Dataset builder → Versioned datasets: writes datasets (evidence: `internal/etl/build.go`)
- Dataset builder → Site profiles: builds profiles (evidence: `internal/etl/build.go`)
- Soil processing → Source clients: gets soil data (evidence: `internal/etl/soil.go`)
- Forecast loading → Source clients: gets forecasts (evidence: `internal/etl/forecast.go`)
- Forecast loading → Versioned datasets: writes forecasts
- Versioned datasets → Redis: reads and writes (evidence: `internal/store/store.go`)
- Versioned datasets → Climate codec: encodes climate (evidence: `internal/store/codec.go`)
- API user → HTTP handlers: requests plan (evidence: `README.md`)
- API startup → Versioned datasets: loads datasets (evidence: `cmd/api/main.go`)
- API startup → Plan service: wires service (evidence: `cmd/api/main.go`)
- API startup → HTTP handlers: starts API (evidence: `cmd/api/main.go`)
- HTTP handlers → Municipal geography: locates municipality (evidence: `internal/httpapi/handlers.go`)
- HTTP handlers → Plan service: requests plan (evidence: `internal/httpapi/handlers.go`)
- HTTP handlers → Crop catalog: serves crop listing
- Plan service → Rotation engine: evaluates rotation (evidence: `internal/plan/service.go`)
- Rotation engine → Scoring and evaluation: scores candidates (evidence: `internal/agro/engine.go`)
- Plan service → Versioned datasets: loads prepared data (evidence: `README.md`)
- Plan service → Department plans: aggregates departments
- Calibration command → IMERG downloader: runs download (evidence: `cmd/calibrate/main.go`)
- Calibration command → Canícula analysis: runs analysis (evidence: `cmd/calibrate/main.go`)
- IMERG downloader → Climate and soil providers: downloads IMERG
