# karim-071/flood-prediction architecture

> Architecture diagram of the GitHub repository karim-071/flood-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karim-071/flood-prediction
- Repository: https://github.com/karim-071/flood-prediction

## Overview

1. **Overall shape**
   - This repository is a small, self-contained Python analytics application with two distinct execution paths:
     - **Interactive inference/UI** via `app.py`
     - **Offline model training** via `train_model.py`
   - The app is focused on **historical flood-risk assessment**, not forecasting. The bundled model artifact in `models/flood_risk_model.pkl` is loaded at runtime by the Streamlit app.

2. **Primary runtime entrypoint: `app.py`**
   - `app.py` is the user-facing entrypoint and is the main Streamlit application.
   - It likely orchestrates the entire UI: loading data, generating rainfall charts, calling the prediction helper, and rendering model explanation outputs.
   - In an architecture diagram, this is the top-level presentation layer and the central consumer of the model and data utilities.

3. **Data source boundary**
   - The repository uses a local CSV file at `data/rainfall.csv` as the core dataset.
   - This file is the system’s main analytical input for both:
     - descriptive rainfall exploration
     - feature engineering for flood-risk classification
   - There are no external databases or APIs in the repo; the data boundary is local file-based.

4. **Model artifact boundary**
   - `models/flood_risk_model.pkl` is a persisted scikit-learn model artifact.
   - The Streamlit app likely loads this file through `utils/predict.py` to produce probability and risk labels.
   - This separation means training is offline, while inference is lightweight and file-based.

5. **Training pipeline: `train_model.py`**
   - `train_model.py` is the offline ML pipeline that builds the classifier from the rainfall dataset.
   - It likely:
     - reads `data/rainfall.csv`
     - creates engineered climatic features
     - derives flood-risk labels
     - trains a Random Forest Classifier
     - saves the fitted model into `models/flood_risk_model.pkl`
   - This training script is the only place where model generation happens; the app itself is not retraining the model.

6. **Feature engineering layer: `utils/features.py`**
   - This module is the feature boundary between raw rainfall records and model-ready inputs.
   - Based on the README, it likely computes:
     - annual rainfall
     - monsoon rainfall
     - pre-monsoon rainfall
     - post-monsoon rainfall
     - monsoon anomaly
     - monsoon percentile
   - This is a key subsystem because both training and inference must use the same feature definitions.

7. **Label generation and risk definition: `utils/labeling.py`**
   - This module likely converts historical rainfall patterns into flood-risk labels for supervised training.
   - The README suggests the target is derived from **extreme monsoon rainfall percentiles** rather than from actual flood-event operational data.
   - In an architecture diagram, this is the domain logic that defines what “flood risk” means in this system.

8. **Prediction workflow: `utils/predict.py`**
   - This module is the inference adapter used by the app.
   - Its role is likely to load the trained model, assemble the feature vector for a selected state/period, and return:
     - flood probability
     - risk class such as low / medium / high
   - This module sits between the UI and the persisted model artifact.

9. **Explainability layer: `utils/explain.py`**
   - The app includes model explainability, and this module likely extracts or formats feature-importance information from the trained Random Forest.
   - This is a presentation-support subsystem, not part of the prediction logic itself.
   - It helps the Streamlit UI visualize why the model produced a certain risk score.

10. **Data loading boundary: `utils/data_loader.py`**
    - This module likely centralizes CSV ingestion and preprocessing of the rainfall dataset.
    - Keeping loading logic isolated avoids duplicating file-path and parsing assumptions across the app and training script.
    - It is the first step in both the analytical and ML flows.

11. **User-facing analytical features**
    - The README describes a second major app section for rainfall analysis and visualization.
    - That part likely reads directly from the dataset and produces Plotly charts and monthly/period statistics without involving the ML model.
    - So the app has two parallel flows:
      - **descriptive analytics** from raw data
      - **risk scoring** through the trained classifier

12. **Technology and packaging boundaries**
    - Core stack: **Streamlit**, **Pandas**, **scikit-learn**, **Plotly**, **Joblib**.
    - `requirements.txt` defines the runtime dependencies.
    - `.devcontainer/` suggests the repo is set up for containerized development, but it does not appear to affect runtime architecture.

13. **End-to-end data flow**
    - The likely end-to-end flow is:
      - CSV dataset → loading/preprocessing → feature engineering → model training → serialized model
      - At runtime: user interaction in Streamlit → data selection/aggregation → feature construction → model inference → probability/risk output → explanation/chart rendering
    - The key architectural boundary is between **offline training** and **online inference/UI**.

14. **What to show in a diagram**
    - At minimum, depict these nodes and connections:
      - `app.py` as the UI orchestrator
      - `data/rainfall.csv` as the source dataset
      - `utils/data_loader.py`, `utils/features.py`, `utils/labeling.py` as preprocessing/domain logic
      - `train_model.py` as offline model builder
      - `models/flood_risk_model.pkl` as the persisted ML artifact
      - `utils/predict.py` and `utils/explain.py` as inference/explainability services inside the app
    - The architecture is monolithic and local, with no distributed services or external APIs.

Main entry points: [`app.py`](https://github.com/karim-071/flood-prediction/blob/main/app.py) (app.py), [`train_model.py`](https://github.com/karim-071/flood-prediction/blob/main/train_model.py) (train_model.py), [`utils/features.py`](https://github.com/karim-071/flood-prediction/blob/main/utils/features.py) (Features), [`utils/predict.py`](https://github.com/karim-071/flood-prediction/blob/main/utils/predict.py) (Predict)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Interactive runtime"]
  node_app_py["app.py<br/>Streamlit app<br/>[app.py]"]
  node_predict_py["Predict<br/>inference<br/>[predict.py]"]
  node_explain_py["Explain<br/>[explain.py]"]
end

subgraph group_training["Offline training"]
  node_train_model_py["train_model.py<br/>training script<br/>[train_model.py]"]
end

subgraph group_data["Data boundary"]
  node_rainfall_csv["rainfall.csv<br/>dataset<br/>[rainfall.csv]"]
  node_model_pkl[("model.pkl<br/>serialized model")]
end

subgraph group_logic["Domain logic"]
  node_data_loader_py["Data loader<br/>ingest<br/>[data_loader.py]"]
  node_features_py["Features<br/>feature engineering<br/>[features.py]"]
  node_labeling_py["Labeling<br/>target logic<br/>[labeling.py]"]
end

node_requirements_txt["requirements<br/>dependencies<br/>[requirements.txt]"]
node_devcontainer_json["Dev container<br/>dev setup<br/>[devcontainer.json]"]

node_app_py -->|"score risk"| node_predict_py
node_app_py -->|"show reasons"| node_explain_py
node_app_py -->|"load data"| node_data_loader_py
node_app_py -->|"build inputs"| node_features_py
node_predict_py -->|"load model"| node_model_pkl
node_predict_py -->|"assemble features"| node_features_py
node_explain_py -->|"inspect model"| node_model_pkl
node_train_model_py -->|"ingest data"| node_data_loader_py
node_train_model_py -->|"engineer inputs"| node_features_py
node_train_model_py -->|"derive labels"| node_labeling_py
node_train_model_py -->|"save artifact"| node_model_pkl
node_data_loader_py -->|"read"| node_rainfall_csv
node_features_py -->|"transform"| node_rainfall_csv
node_labeling_py -->|"derive target"| node_rainfall_csv
node_app_py -.->|"depends on"| node_requirements_txt
node_train_model_py -.->|"depends on"| node_requirements_txt
node_app_py -.->|"dev setup"| node_devcontainer_json

click node_app_py "https://github.com/karim-071/flood-prediction/blob/main/app.py"
click node_predict_py "https://github.com/karim-071/flood-prediction/blob/main/utils/predict.py"
click node_explain_py "https://github.com/karim-071/flood-prediction/blob/main/utils/explain.py"
click node_data_loader_py "https://github.com/karim-071/flood-prediction/blob/main/utils/data_loader.py"
click node_features_py "https://github.com/karim-071/flood-prediction/blob/main/utils/features.py"
click node_labeling_py "https://github.com/karim-071/flood-prediction/blob/main/utils/labeling.py"
click node_train_model_py "https://github.com/karim-071/flood-prediction/blob/main/train_model.py"
click node_rainfall_csv "https://github.com/karim-071/flood-prediction/blob/main/data/rainfall.csv"
click node_model_pkl "https://github.com/karim-071/flood-prediction/blob/main/models/flood_risk_model.pkl"
click node_requirements_txt "https://github.com/karim-071/flood-prediction/blob/main/requirements.txt"
click node_devcontainer_json "https://github.com/karim-071/flood-prediction/blob/main/.devcontainer/devcontainer.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_app_py,node_predict_py,node_explain_py toneBlue
class node_train_model_py toneAmber
class node_rainfall_csv,node_model_pkl toneMint
class node_data_loader_py,node_features_py,node_labeling_py toneRose
class node_requirements_txt,node_devcontainer_json toneNeutral
```

## Components

### Interactive runtime

Streamlit app and inference-side support

- [app.py](https://github.com/karim-071/flood-prediction/blob/main/app.py): Streamlit app · User-facing entrypoint that drives analytics, prediction, and explanation views · `app.py`
- [Predict](https://github.com/karim-071/flood-prediction/blob/main/utils/predict.py): inference · Loads the trained model and returns flood-risk scores and classes · `utils/predict.py`
- [Explain](https://github.com/karim-071/flood-prediction/blob/main/utils/explain.py): explainability · Formats model interpretation outputs for the UI · `utils/explain.py`

### Offline training

Model build and serialization flow

- [train_model.py](https://github.com/karim-071/flood-prediction/blob/main/train_model.py): training script · Offline pipeline that trains the classifier and saves the artifact · `train_model.py`

### Data boundary

Local dataset and persisted artifact

- [rainfall.csv](https://github.com/karim-071/flood-prediction/blob/main/data/rainfall.csv): dataset · Local rainfall history used for analysis and model building · `data/rainfall.csv`
- [model.pkl](https://github.com/karim-071/flood-prediction/blob/main/models/flood_risk_model.pkl): serialized model · Persisted flood-risk classifier loaded at runtime · `models/flood_risk_model.pkl`

### Domain logic

Feature and label preparation

- [Data loader](https://github.com/karim-071/flood-prediction/blob/main/utils/data_loader.py): ingest · Centralizes CSV reading and dataset preparation · `utils/data_loader.py`
- [Features](https://github.com/karim-071/flood-prediction/blob/main/utils/features.py): feature engineering · Builds rainfall-based model features from raw records · `utils/features.py`
- [Labeling](https://github.com/karim-071/flood-prediction/blob/main/utils/labeling.py): target logic · Derives historical flood-risk labels for supervised training · `utils/labeling.py`

### Other components

- [requirements](https://github.com/karim-071/flood-prediction/blob/main/requirements.txt): dependencies · Python package set for app and training execution · `requirements.txt`
- [Dev container](https://github.com/karim-071/flood-prediction/blob/main/.devcontainer/devcontainer.json): dev setup · Containerized development configuration · `.devcontainer/devcontainer.json`

## Connections

- app.py → Predict: score risk · Interactive UI requests flood-risk predictions
- app.py → Explain: show reasons · UI renders model interpretation outputs
- app.py → Data loader: load data · UI reads the rainfall dataset for descriptive analysis
- app.py → Features: build inputs · UI prepares feature vectors for selected views
- Predict → model.pkl: load model · Inference uses the persisted classifier artifact
- Predict → Features: assemble features · Prediction depends on the shared feature definitions
- Explain → model.pkl: inspect model · Explainability derives outputs from the trained classifier
- train_model.py → Data loader: ingest data · Training starts from the local rainfall dataset
- train_model.py → Features: engineer inputs · Training converts raw rainfall records into model features
- train_model.py → Labeling: derive labels · Training creates flood-risk targets from historical rainfall patterns
- train_model.py → model.pkl: save artifact · Training persists the fitted model for later inference
- Data loader → rainfall.csv: read · CSV ingestion boundary
- Features → rainfall.csv: transform · Feature engineering consumes raw rainfall history
- Labeling → rainfall.csv: derive target · Label logic analyzes the same historical dataset
- app.py → requirements: depends on · Runtime package boundary
- train_model.py → requirements: depends on · Training package boundary
- app.py → Dev container: dev setup · Development environment support
