# youcef3939/terramind architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/terramind
- Repository: https://github.com/youcef3939/terramind

## Overview

1. **High-level shape**
   TerraMind is a two-tier application: a **React frontend** for AOI selection and result visualization, and a **Python/FastAPI backend** that orchestrates satellite ingestion, environmental analysis, recommendations, and report generation.

2. **Frontend boundary**
   The frontend lives under `frontend/` and is a single-page React app. `src/index.js` bootstraps `App.js`, while `Dashboard.js`, `AnalysisResults.js`, `Header.js`, and `LoadingSpinner.js` split the UI into map interaction, results display, shell/navigation, and request-state feedback. The README indicates Leaflet for map drawing and Chart.js for visual summaries.

3. **User interaction flow**
   The primary user action is drawing a circular **Area of Interest (AOI)** on the map and triggering analysis. That AOI is the core payload passed from the UI to the backend. The UI then renders the returned analysis, comparisons, and recommendations, and can request a PDF report.

4. **Backend entrypoint and API layer**
   `backend/main_simple.py` is the backend entrypoint in this tree. It is the FastAPI layer that exposes the HTTP endpoints described in the README, including analysis, satellite imagery, climate forecast, and report download. This layer is the main boundary between the frontend and the analysis modules.

5. **Data acquisition subsystem**
   `backend/modules/satellite_api.py` is the external-data boundary for satellite imagery. The README also references Sentinel Hub, Landsat, and OpenWeatherMap API keys, so the backend depends on third-party geospatial and weather services for raw inputs rather than storing its own primary datasets.

6. **Analysis subsystem**
   The core AI/ML logic is split into domain modules:
   - `agrovision.py` for vegetation health, NDVI/NDWI, and crop stress
   - `ecoguard.py` for deforestation, degradation, and ecosystem health
   - `climarisk.py` for climate and weather risk prediction  
   These modules are the main compute boundary of the system and likely consume imagery/climate inputs to produce structured assessment outputs.

7. **Recommendation layer**
   `backend/modules/insight_engine.py` sits above the raw analyses and turns them into actionable guidance. Architecturally, this is the decision/interpretation layer: it consolidates outputs from the domain analyzers and produces prioritized sustainability or intervention suggestions.

8. **Report generation subsystem**
   `backend/modules/report_generator.py` is the artifact-generation boundary. The README describes PDF reports with maps, analysis, and recommendations, so this module likely converts backend results into a downloadable report rather than returning only JSON.

9. **End-to-end data flow**
   The typical flow is: **frontend AOI selection → POST to backend `/analyze` → backend fetches imagery/climate data → domain modules compute agricultural/environmental scores → insight engine creates recommendations → results returned to UI → optional PDF report requested via `/report/{aoi_id}`**. The `aoi_id` pattern in the README suggests analysis results are addressable after the initial request.

10. **Deployment and runtime boundaries**
    The repo is designed to run as two containers/services via `docker-compose.yml`, with separate Dockerfiles for `frontend/` and `backend/`. That keeps the UI and Python analysis stack isolated while still allowing them to communicate over HTTP.

11. **State and persistence**
    There is no obvious database, queue, or dedicated storage service in the tree. That suggests the architecture is mostly **request/response driven**, with generated outputs handled through API responses and report files rather than a heavy persistence layer.

12. **Repo-specific note**
    The README refers to `backend/main.py`, but the file tree shows `backend/main_simple.py`; for architecture purposes, treat `main_simple.py` as the active backend entrypoint in this snapshot.

Main entry points: [`backend/main_simple.py`](https://github.com/youcef3939/terramind/blob/main/backend/main_simple.py) (API entry), [`frontend/src/App.js`](https://github.com/youcef3939/terramind/blob/main/frontend/src/App.js) (App shell), [`frontend/src/components/Dashboard.js`](https://github.com/youcef3939/terramind/blob/main/frontend/src/components/Dashboard.js) (Dashboard), [`backend/modules/insight_engine.py`](https://github.com/youcef3939/terramind/blob/main/backend/modules/insight_engine.py) (Insights)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_index["Entry<br/>React bootstrap<br/>[index.js]"]
  node_frontend_app["App shell<br/>React root<br/>[App.js]"]
  node_frontend_dashboard["Dashboard<br/>map UI<br/>[Dashboard.js]"]
  node_frontend_results["Results<br/>[AnalysisResults.js]"]
  node_frontend_header["Header<br/>navigation UI<br/>[Header.js]"]
  node_frontend_spinner(("Loading<br/>state UI<br/>[LoadingSpinner.js]"))
end

subgraph group_backend["Backend"]
  node_backend_entry["API entry<br/>FastAPI app<br/>[main_simple.py]"]
  node_satellite_api["Satellite API<br/>ingestion adapter<br/>[satellite_api.py]"]
  node_agrovision["AgroVision<br/>agri analysis<br/>[agrovision.py]"]
  node_ecoguard["EcoGuard<br/>eco analysis<br/>[ecoguard.py]"]
  node_climarisk["ClimaRisk<br/>risk analysis<br/>[climarisk.py]"]
  node_insight_engine["Insights<br/>recommendation layer<br/>[insight_engine.py]"]
  node_report_generator["Reports<br/>artifact generator"]
end

node_external_data[("External data<br/>3rd-party services")]
node_user_aoi{{"AOI input<br/>user payload"}}
node_api_response["Analysis result<br/>HTTP response"]

node_frontend_index -->|"mounts"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_header
node_frontend_app -->|"hosts"| node_frontend_dashboard
node_frontend_app -->|"shows"| node_frontend_results
node_frontend_dashboard -->|"creates"| node_user_aoi
node_user_aoi -->|"POST /analyze"| node_backend_entry
node_backend_entry -->|"fetches"| node_satellite_api
node_backend_entry -->|"runs"| node_agrovision
node_backend_entry -->|"runs"| node_ecoguard
node_backend_entry -->|"runs"| node_climarisk
node_satellite_api -->|"reads"| node_external_data
node_agrovision -->|"feeds"| node_insight_engine
node_ecoguard -->|"feeds"| node_insight_engine
node_climarisk -->|"feeds"| node_insight_engine
node_insight_engine -->|"summarizes"| node_report_generator
node_backend_entry -->|"POST /report"| node_report_generator
node_backend_entry -->|"returns"| node_api_response
node_api_response -->|"renders"| node_frontend_results
node_frontend_dashboard -.->|"states"| node_frontend_spinner
node_backend_entry -.->|"served by"| node_frontend_dashboard

click node_frontend_index "https://github.com/youcef3939/terramind/blob/main/frontend/src/index.js"
click node_frontend_app "https://github.com/youcef3939/terramind/blob/main/frontend/src/App.js"
click node_frontend_dashboard "https://github.com/youcef3939/terramind/blob/main/frontend/src/components/Dashboard.js"
click node_frontend_results "https://github.com/youcef3939/terramind/blob/main/frontend/src/components/AnalysisResults.js"
click node_frontend_header "https://github.com/youcef3939/terramind/blob/main/frontend/src/components/Header.js"
click node_frontend_spinner "https://github.com/youcef3939/terramind/blob/main/frontend/src/components/LoadingSpinner.js"
click node_backend_entry "https://github.com/youcef3939/terramind/blob/main/backend/main_simple.py"
click node_satellite_api "https://github.com/youcef3939/terramind/blob/main/backend/modules/satellite_api.py"
click node_agrovision "https://github.com/youcef3939/terramind/blob/main/backend/modules/agrovision.py"
click node_ecoguard "https://github.com/youcef3939/terramind/blob/main/backend/modules/ecoguard.py"
click node_climarisk "https://github.com/youcef3939/terramind/blob/main/backend/modules/climarisk.py"
click node_insight_engine "https://github.com/youcef3939/terramind/blob/main/backend/modules/insight_engine.py"
click node_report_generator "https://github.com/youcef3939/terramind/blob/main/backend/modules/report_generator.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_frontend_index,node_frontend_app,node_frontend_dashboard,node_frontend_results,node_frontend_header,node_frontend_spinner toneBlue
class node_backend_entry,node_satellite_api,node_agrovision,node_ecoguard,node_climarisk,node_insight_engine,node_report_generator toneAmber
class node_external_data,node_user_aoi,node_api_response toneNeutral
```

## Components

### Frontend

React app for AOI selection and results visualization

- [Entry](https://github.com/youcef3939/terramind/blob/main/frontend/src/index.js): React bootstrap · Bootstraps the single-page app · `frontend/src/index.js`
- [App shell](https://github.com/youcef3939/terramind/blob/main/frontend/src/App.js): React root · Top-level application container · `frontend/src/App.js`
- [Dashboard](https://github.com/youcef3939/terramind/blob/main/frontend/src/components/Dashboard.js): map UI · AOI drawing and analysis trigger interface · `frontend/src/components/Dashboard.js`
- [Results](https://github.com/youcef3939/terramind/blob/main/frontend/src/components/AnalysisResults.js): results UI · Displays analysis outputs, comparisons, and recommendations · `frontend/src/components/AnalysisResults.js`
- [Header](https://github.com/youcef3939/terramind/blob/main/frontend/src/components/Header.js): navigation UI · Shell and page chrome · `frontend/src/components/Header.js`
- [Loading](https://github.com/youcef3939/terramind/blob/main/frontend/src/components/LoadingSpinner.js): state UI · Request-state feedback during analysis · `frontend/src/components/LoadingSpinner.js`

### Backend

FastAPI service plus analysis modules

- [API entry](https://github.com/youcef3939/terramind/blob/main/backend/main_simple.py): FastAPI app · HTTP boundary for analysis, imagery, forecast, and reports · `backend/main_simple.py`
- [Satellite API](https://github.com/youcef3939/terramind/blob/main/backend/modules/satellite_api.py): ingestion adapter · Fetches satellite imagery from external providers · `backend/modules/satellite_api.py`
- [AgroVision](https://github.com/youcef3939/terramind/blob/main/backend/modules/agrovision.py): agri analysis · Vegetation health, NDVI/NDWI, and crop stress analysis · `backend/modules/agrovision.py`
- [EcoGuard](https://github.com/youcef3939/terramind/blob/main/backend/modules/ecoguard.py): eco analysis · Deforestation, degradation, and ecosystem health analysis · `backend/modules/ecoguard.py`
- [ClimaRisk](https://github.com/youcef3939/terramind/blob/main/backend/modules/climarisk.py): risk analysis · Climate and weather risk prediction · `backend/modules/climarisk.py`
- [Insights](https://github.com/youcef3939/terramind/blob/main/backend/modules/insight_engine.py): recommendation layer · Combines analysis outputs into actionable guidance · `backend/modules/insight_engine.py`
- [Reports](https://github.com/youcef3939/terramind/blob/main/backend/modules/report_generator.py): artifact generator · Builds downloadable PDF reports from results · `backend/modules/report_generator.py`

### Other components

- **External data**: 3rd-party services · Sentinel Hub, Landsat, and weather APIs
- **AOI input**: user payload · Area of interest selected on the map
- **Analysis result**: HTTP response · Structured results returned to the frontend

## Connections

- Entry → App shell: mounts · Initial React bootstrap renders the app
- App shell → Header: uses · Renders shared page shell
- App shell → Dashboard: hosts · Primary AOI interaction surface
- App shell → Results: shows · Displays returned analysis content
- Dashboard → AOI input: creates · User draws and submits an area of interest
- AOI input → API entry: POST /analyze · AOI payload sent to backend analysis endpoint
- API entry → Satellite API: fetches · Retrieves imagery inputs
- API entry → AgroVision: runs · Computes agricultural health signals
- API entry → EcoGuard: runs · Computes environmental degradation signals
- API entry → ClimaRisk: runs · Computes climate risk signals
- Satellite API → External data: reads · Consumes third-party geospatial and weather services
- AgroVision → Insights: feeds · Provides agricultural findings
- EcoGuard → Insights: feeds · Provides ecosystem findings
- ClimaRisk → Insights: feeds · Provides climate risk findings
- Insights → Reports: summarizes · Prepared guidance can be embedded in reports
- API entry → Reports: POST /report · Generates downloadable PDF artifact
- API entry → Analysis result: returns · Sends structured analysis to client
- Analysis result → Results: renders · Frontend displays results and recommendations
- Dashboard → Loading: states · Shows loading feedback while request is in flight
- API entry → Dashboard: served by · Frontend consumes backend endpoints over HTTP
