# syedmuhammadhunain/climate-machine-learning architecture

> Architecture diagram of the GitHub repository syedmuhammadhunain/climate-machine-learning, 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/syedmuhammadhunain/climate-machine-learning
- Repository: https://github.com/syedmuhammadhunain/climate-machine-learning

## Overview

This project predicts crop yields and ranks 13 crops for drought scenarios in Punjab, Sindh, and Balochistan. The main workflow is climate inputs → validation and feature completion → model inference → comparison with typical provincial yields → ranked recommendations and caveats. A shared Python package also supports model training, evaluation, and presentation logic. FastAPI serves API and web pages; separate Streamlit and Hugging Face apps are documented. Frontend source files and model artifacts are not in the supplied tree, so their internal wiring is not shown.

Main entry points: [`app/services/model_service.py`](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/services/model_service.py) (Model service), [`app/api/v1/endpoints.py`](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/api/v1/endpoints.py) (Prediction API routes), [`src/climate_machine_learning/inference.py`](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/inference.py) (Yield inference), [`app/main.py`](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/main.py) (App server and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_model["Data and model"]
  node_feature_engineering["Feature engineering<br/>[features.py]"]
  node_training["Training and evaluation<br/>[training.py]"]
  node_training_data[("Climate and yield data")]
  node_artifacts[("Saved model and metrics")]
end

subgraph group_shared_runtime["Shared prediction runtime"]
  node_inference["Yield inference<br/>[inference.py]"]
  node_ranking["Crop ranking<br/>[inference.py]"]
  node_presentation["Shared presentation logic<br/>[presentation.py]"]
  node_recommendation["Ranked crop results<br/>[recommend.py]"]
end

subgraph group_fastapi["FastAPI service"]
  node_climate_inputs["Climate scenario<br/>[predict.py]"]
  node_request_schemas["Request and response schemas<br/>[recommend.py]"]
  node_api_routes["Prediction API routes<br/>[endpoints.py]"]
  node_app_server["App server and pages<br/>[main.py]"]
  node_model_service["Model service<br/>[model_service.py]"]
  node_exception_handling["Validation errors<br/>[exceptions.py]"]
end

subgraph group_other_apps["Other app surfaces"]
  node_web_frontend["Web frontend"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_hf_app["Hugging Face app<br/>[app.py]"]
end

node_farmer(("Farmer or officer"))
node_nasa_power["NASA POWER"]

node_farmer -->|"enters scenario"| node_climate_inputs
node_climate_inputs -->|"submits to"| node_api_routes
node_api_routes -->|"calls"| node_model_service
node_api_routes -->|"validates with"| node_request_schemas
node_app_server -->|"registers routes"| node_api_routes
node_app_server -->|"loads at startup"| node_model_service
node_app_server -->|"registers handlers"| node_exception_handling
node_model_service -->|"loads artifacts"| node_artifacts
node_model_service -->|"uses features"| node_feature_engineering
node_model_service -->|"uses inference"| node_inference
node_model_service -->|"builds ranking"| node_ranking
node_ranking -->|"formats results"| node_recommendation
node_feature_engineering -->|"prepares inputs"| node_inference
node_training_data -->|"supplies data"| node_feature_engineering
node_nasa_power -->|"provides soil data"| node_training_data
node_feature_engineering -->|"builds training features"| node_training
node_training -->|"writes model results"| node_artifacts
node_artifacts -->|"provides trained model"| node_inference
node_web_frontend -->|"calls API"| node_api_routes
node_app_server -->|"serves pages"| node_web_frontend
node_streamlit -->|"uses shared core"| node_inference
node_streamlit -->|"uses shared presentation"| node_presentation
node_hf_app -->|"uses shared core"| node_inference
node_hf_app -->|"uses shared presentation"| node_presentation
node_recommendation -->|"returns results"| node_farmer

click node_climate_inputs "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/predict.py"
click node_request_schemas "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/recommend.py"
click node_api_routes "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/api/v1/endpoints.py"
click node_app_server "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/main.py"
click node_model_service "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/services/model_service.py"
click node_exception_handling "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/core/exceptions.py"
click node_feature_engineering "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/features.py"
click node_training "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/training.py"
click node_inference "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/inference.py"
click node_ranking "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/inference.py"
click node_presentation "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/presentation.py"
click node_web_frontend "https://github.com/syedmuhammadhunain/climate-machine-learning/tree/hunain-deploy/frontend/climate-resilient-frontend"
click node_streamlit "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/streamlit_app/app.py"
click node_hf_app "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/hf_space/app.py"
click node_recommendation "https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/recommend.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_feature_engineering,node_training,node_training_data,node_artifacts toneBlue
class node_inference,node_ranking,node_presentation,node_recommendation toneAmber
class node_climate_inputs,node_request_schemas,node_api_routes,node_app_server,node_model_service,node_exception_handling toneMint
class node_web_frontend,node_streamlit,node_hf_app toneRose
class node_farmer,node_nasa_power toneIndigo
```

## Components

### Data and model

- [Feature engineering](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/features.py): `src/climate_machine_learning/features.py`
- [Training and evaluation](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/training.py): `src/climate_machine_learning/training.py`
- **Climate and yield data**
- **Saved model and metrics**

### Shared prediction runtime

- [Yield inference](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/inference.py): `src/climate_machine_learning/inference.py`
- [Crop ranking](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/inference.py): `src/climate_machine_learning/inference.py`
- [Shared presentation logic](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/src/climate_machine_learning/presentation.py): `src/climate_machine_learning/presentation.py`
- [Ranked crop results](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/recommend.py): `app/schemas/recommend.py`

### FastAPI service

- [Climate scenario](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/predict.py): `app/schemas/predict.py`
- [Request and response schemas](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/schemas/recommend.py): `app/schemas/recommend.py`
- [Prediction API routes](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/api/v1/endpoints.py): `app/api/v1/endpoints.py`
- [App server and pages](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/main.py): `app/main.py`
- [Model service](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/services/model_service.py): `app/services/model_service.py`
- [Validation errors](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/app/core/exceptions.py): `app/core/exceptions.py`

### Other app surfaces

- [Web frontend](https://github.com/syedmuhammadhunain/climate-machine-learning/tree/hunain-deploy/frontend/climate-resilient-frontend): `frontend/climate-resilient-frontend`
- [Streamlit app](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/streamlit_app/app.py): `streamlit_app/app.py`
- [Hugging Face app](https://github.com/syedmuhammadhunain/climate-machine-learning/blob/hunain-deploy/hf_space/app.py): `hf_space/app.py`

### Other components

- **Farmer or officer**
- **NASA POWER**

## Connections

- Farmer or officer → Climate scenario: enters scenario (evidence: `README.md`)
- Climate scenario → Prediction API routes: submits to (evidence: `README.md`)
- Prediction API routes → Model service: calls (evidence: `app/api/v1/endpoints.py`)
- Prediction API routes → Request and response schemas: validates with (evidence: `app/api/v1/endpoints.py`)
- App server and pages → Prediction API routes: registers routes (evidence: `app/main.py`)
- App server and pages → Model service: loads at startup (evidence: `app/main.py`)
- App server and pages → Validation errors: registers handlers (evidence: `app/main.py`)
- Model service → Saved model and metrics: loads artifacts (evidence: `app/services/model_service.py`)
- Model service → Feature engineering: uses features (evidence: `app/services/model_service.py`)
- Model service → Yield inference: uses inference (evidence: `app/services/model_service.py`)
- Model service → Crop ranking: builds ranking (evidence: `app/services/model_service.py`)
- Crop ranking → Ranked crop results: formats results (evidence: `app/services/model_service.py`)
- Feature engineering → Yield inference: prepares inputs (evidence: `src/climate_machine_learning/inference.py`)
- Climate and yield data → Feature engineering: supplies data (evidence: `README.md`)
- NASA POWER → Climate and yield data: provides soil data (evidence: `README.md`)
- Feature engineering → Training and evaluation: builds training features (evidence: `src/climate_machine_learning/training.py`)
- Training and evaluation → Saved model and metrics: writes model results (evidence: `README.md`)
- Saved model and metrics → Yield inference: provides trained model (evidence: `README.md`)
- Web frontend → Prediction API routes: calls API (evidence: `README.md`)
- App server and pages → Web frontend: serves pages (evidence: `app/main.py`)
- Streamlit app → Yield inference: uses shared core (evidence: `streamlit_app/app.py`)
- Streamlit app → Shared presentation logic: uses shared presentation (evidence: `streamlit_app/app.py`)
- Hugging Face app → Yield inference: uses shared core (evidence: `hf_space/app.py`)
- Hugging Face app → Shared presentation logic: uses shared presentation (evidence: `hf_space/app.py`)
- Ranked crop results → Farmer or officer: returns results (evidence: `README.md`)
