How youcef3939/terramind works
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: main_simple.py API entry · App.js App shell · Dashboard.js Dashboard · insight_engine.py Insights
Components 16
Frontend
React app for AOI selection and results visualization
- Entry · Bootstraps the single-page app
frontend/src/index.js - App shell · Top-level application container
frontend/src/App.js - Dashboard · AOI drawing and analysis trigger interface
frontend/src/components/Dashboard.js - Results · Displays analysis outputs, comparisons, and recommendations
frontend/src/components/AnalysisResults.js - Header · Shell and page chrome
frontend/src/components/Header.js - Loading · Request-state feedback during analysis
frontend/src/components/LoadingSpinner.js
Backend
FastAPI service plus analysis modules
- API entry · HTTP boundary for analysis, imagery, forecast, and reports
backend/main_simple.py - Satellite API · Fetches satellite imagery from external providers
backend/modules/satellite_api.py - AgroVision · Vegetation health, NDVI/NDWI, and crop stress analysis
backend/modules/agrovision.py - EcoGuard · Deforestation, degradation, and ecosystem health analysis
backend/modules/ecoguard.py - ClimaRisk · Climate and weather risk prediction
backend/modules/climarisk.py - Insights · Combines analysis outputs into actionable guidance
backend/modules/insight_engine.py - Reports · Builds downloadable PDF reports from results
backend/modules/report_generator.py
Other components
- External data · Sentinel Hub, Landsat, and weather APIs
- AOI input · Area of interest selected on the map
- Analysis result · Structured results returned to the frontend
Connections 20
- 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