# h3ndrick/agroguard-api architecture

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

- Interactive diagram: https://gitdiagram.com/h3ndrick/agroguard-api
- Repository: https://github.com/h3ndrick/agroguard-api

## Overview

AgroGuard serves municipal environmental-risk and agricultural-suitability scores. A user selects a state and queries a location; the API resolves its municipality, loads or calculates state-level component scores, and returns a combined risk report plus separate ZARC suitability. The graph preserves the documented SISSER and ZARC branches and shared percentile normalization. Data-loading details and some endpoint wiring are only partially excerpted, so those relationships rely on README statements where noted.

Main entry points: [`api.py`](https://github.com/h3ndrick/agroguard-api/blob/main/api.py) (FastAPI service), [`scores/normalizacao.py`](https://github.com/h3ndrick/agroguard-api/blob/main/scores/normalizacao.py) (Percentile normalization), [`scores/score_fogo.py`](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_fogo.py) (Fire score), [`scores/score_agricola.py`](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_agricola.py) (Agricultural score)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Map and search<br/>[index.html]"]
end

subgraph group_api["API and geography"]
  node_api_service["FastAPI service<br/>[api.py]"]
  node_municipal_lookup["Municipality lookup<br/>[api.py]"]
  node_state_cache[("State score cache<br/>[api.py]")]
end

subgraph group_scores["Scoring modules"]
  node_fire["Fire score<br/>[score_fogo.py]"]
  node_climate["Climate score<br/>[score_climatico.py]"]
  node_agriculture["Agricultural score<br/>[score_agricola.py]"]
  node_sisser["SISSER exposure<br/>[score_sisser.py]"]
  node_zarc["ZARC suitability<br/>[score_zarc.py]"]
  node_normalization["Percentile normalization<br/>[normalizacao.py]"]
  node_report["Risk report<br/>[score_geral.py]"]
end

subgraph group_data["Data sources"]
  node_municipal_shapes["Municipal boundaries<br/>[municipios.json]"]
  node_state_outlines["State outlines<br/>[go_contorno.json]"]
  node_public_sources[("Public data sources")]
end

node_user(("User"))

node_user -->|"selects location"| node_frontend
node_frontend -->|"requests scores"| node_api_service
node_api_service -->|"resolves coordinates"| node_municipal_lookup
node_municipal_lookup -->|"uses boundaries"| node_municipal_shapes
node_api_service -->|"loads state"| node_state_cache
node_api_service -->|"calculates fire"| node_fire
node_api_service -->|"calculates climate"| node_climate
node_api_service -->|"calculates agriculture"| node_agriculture
node_api_service -->|"aggregates insurance"| node_sisser
node_api_service -->|"aggregates suitability"| node_zarc
node_api_service -->|"builds report"| node_report
node_fire -->|"normalizes components"| node_normalization
node_climate -->|"normalizes components"| node_normalization
node_agriculture -->|"normalizes components"| node_normalization
node_sisser -->|"normalizes components"| node_normalization
node_zarc -->|"normalizes components"| node_normalization
node_report -.->|"returns report"| node_api_service
node_api_service -->|"serves outline"| node_state_outlines
node_public_sources -->|"supplies fire records"| node_fire
node_public_sources -->|"supplies irrigation data"| node_agriculture
node_public_sources -->|"supplies insurance data"| node_sisser
node_public_sources -->|"supplies zoning data"| node_zarc
node_public_sources -->|"supplies boundaries"| node_municipal_shapes

click node_frontend "https://github.com/h3ndrick/agroguard-api/blob/main/static/index.html"
click node_api_service "https://github.com/h3ndrick/agroguard-api/blob/main/api.py"
click node_municipal_lookup "https://github.com/h3ndrick/agroguard-api/blob/main/api.py"
click node_state_cache "https://github.com/h3ndrick/agroguard-api/blob/main/api.py"
click node_fire "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_fogo.py"
click node_climate "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_climatico.py"
click node_agriculture "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_agricola.py"
click node_sisser "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_sisser.py"
click node_zarc "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_zarc.py"
click node_normalization "https://github.com/h3ndrick/agroguard-api/blob/main/scores/normalizacao.py"
click node_report "https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_geral.py"
click node_municipal_shapes "https://github.com/h3ndrick/agroguard-api/blob/main/static/municipios.json"
click node_state_outlines "https://github.com/h3ndrick/agroguard-api/blob/main/static/go_contorno.json"

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_frontend,node_user toneBlue
class node_api_service,node_municipal_lookup,node_state_cache toneAmber
class node_fire,node_climate,node_agriculture,node_sisser,node_zarc,node_normalization,node_report toneMint
class node_municipal_shapes,node_state_outlines,node_public_sources toneRose
```

## Components

### User experience

- [Map and search](https://github.com/h3ndrick/agroguard-api/blob/main/static/index.html): `static/index.html`

### API and geography

- [FastAPI service](https://github.com/h3ndrick/agroguard-api/blob/main/api.py): `api.py`
- [Municipality lookup](https://github.com/h3ndrick/agroguard-api/blob/main/api.py): `api.py`
- [State score cache](https://github.com/h3ndrick/agroguard-api/blob/main/api.py): `api.py`

### Scoring modules

- [Fire score](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_fogo.py): `scores/score_fogo.py`
- [Climate score](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_climatico.py): `scores/score_climatico.py`
- [Agricultural score](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_agricola.py): `scores/score_agricola.py`
- [SISSER exposure](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_sisser.py): `scores/score_sisser.py`
- [ZARC suitability](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_zarc.py): `scores/score_zarc.py`
- [Percentile normalization](https://github.com/h3ndrick/agroguard-api/blob/main/scores/normalizacao.py): `scores/normalizacao.py`
- [Risk report](https://github.com/h3ndrick/agroguard-api/blob/main/scores/score_geral.py): `scores/score_geral.py`

### Data sources

- [Municipal boundaries](https://github.com/h3ndrick/agroguard-api/blob/main/static/municipios.json): `static/municipios.json`
- [State outlines](https://github.com/h3ndrick/agroguard-api/blob/main/static/go_contorno.json): `static/go_contorno.json`
- **Public data sources**

### Other components

- **User**

## Connections

- User → Map and search: selects location (evidence: `README.md`)
- Map and search → FastAPI service: requests scores (evidence: `README.md`)
- FastAPI service → Municipality lookup: resolves coordinates (evidence: `README.md`)
- Municipality lookup → Municipal boundaries: uses boundaries (evidence: `README.md`)
- FastAPI service → State score cache: loads state (evidence: `README.md`)
- FastAPI service → Fire score: calculates fire (evidence: `api.py`)
- FastAPI service → Climate score: calculates climate (evidence: `api.py`)
- FastAPI service → Agricultural score: calculates agriculture (evidence: `api.py`)
- FastAPI service → SISSER exposure: aggregates insurance (evidence: `api.py`)
- FastAPI service → ZARC suitability: aggregates suitability (evidence: `api.py`)
- FastAPI service → Risk report: builds report (evidence: `api.py`)
- Fire score → Percentile normalization: normalizes components (evidence: `scores/score_fogo.py`)
- Climate score → Percentile normalization: normalizes components (evidence: `scores/score_climatico.py`)
- Agricultural score → Percentile normalization: normalizes components (evidence: `scores/score_agricola.py`)
- SISSER exposure → Percentile normalization: normalizes components (evidence: `scores/score_sisser.py`)
- ZARC suitability → Percentile normalization: normalizes components (evidence: `scores/score_zarc.py`)
- Risk report → FastAPI service: returns report (evidence: `api.py`)
- FastAPI service → State outlines: serves outline (evidence: `README.md`)
- Public data sources → Fire score: supplies fire records (evidence: `README.md`)
- Public data sources → Agricultural score: supplies irrigation data (evidence: `README.md`)
- Public data sources → SISSER exposure: supplies insurance data (evidence: `README.md`)
- Public data sources → ZARC suitability: supplies zoning data (evidence: `README.md`)
- Public data sources → Municipal boundaries: supplies boundaries (evidence: `README.md`)
