# 2536070004phd2026/prototype architecture

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

- Interactive diagram: https://gitdiagram.com/2536070004phd2026/prototype
- Repository: https://github.com/2536070004phd2026/prototype

## Overview

#### Purpose and Entry Points
This is a GPU-oriented prototype for pixel-level land-use/land-cover (LULC) segmentation of Indian satellite imagery using the Sen-2 LULC dataset. Its lifecycle is: validate a manually downloaded dataset, build PyTorch loaders, train three segmentation architectures, and serve predictions/results in Streamlit.

Primary entry points:
- Dataset verification: `01_download_dataset.py`
- Data loading smoke test and reusable pipeline: `02_data_pipeline.py`
- Model training and artifact generation: `03_train_models.py`
- Interactive UI: `streamlit_app.py`

#### Dataset Boundary
The dataset is externally obtained from Mendeley and expected to be extracted locally as `sen2lulc`; it is not versioned in the repository. `01_download_dataset.py` verifies that expected local data is available. `02_data_pipeline.py` owns the image/mask directory assumptions and is the boundary between raw raster/image files and training tensors.

#### Data Pipeline
`02_data_pipeline.py` defines the segmentation dataset abstraction and creates train, validation, and test `DataLoader`s. It pairs satellite tiles with corresponding class masks, applies image/mask preprocessing, and emits batched tensors suitable for semantic segmentation. Batch size is deliberately constrained for a 6 GB RTX 3060-class GPU.

The pipeline is shared control infrastructure: training consumes its loaders, while the UI must reproduce compatible image preprocessing for inference.

#### Training Orchestration
`03_train_models.py` is the central training workflow. It trains three encoder families—ConvNeXt, Swin Transformer, and ResNet—through `segmentation-models-pytorch`/`timm`-based segmentation models. It runs GPU training with PyTorch mixed precision to reduce VRAM pressure.

The workflow evaluates segmentation quality using IoU and Dice, records training duration, and persists trained weights plus a results summary under an `outputs` location at runtime. Those artifacts form the contract consumed by the demonstration layer.

#### Inference and Demonstration UI
`streamlit_app.py` is the deployed-facing interface, despite the README referring to a stale `04_app.py` filename. It provides an image-upload prediction workflow that renders a color-coded LULC mask and a model-comparison view driven by saved evaluation metrics. It depends on compatible model checkpoints and result artifacts produced by `03_train_models.py`.

#### Runtime and Dependencies
The primary runtime is Python with CUDA-enabled PyTorch, intended for NVIDIA GPU execution. Core libraries include `torch`, `torchvision`, `segmentation-models-pytorch`, `timm`, NumPy/Pandas, Pillow, scikit-learn, and Streamlit. External dependencies are the locally downloaded Sen-2 LULC dataset and the Mendeley dataset host; there is no indicated database, API backend, or cloud infrastructure.

#### End-to-End Control Flow
1. Obtain and extract Sen-2 LULC data externally.
2. Validate local placement via `01_download_dataset.py`.
3. Configure and validate image/mask loading through `02_data_pipeline.py`.
4. Train and evaluate three models in `03_train_models.py`.
5. Load generated checkpoints/results into `streamlit_app.py` for uploaded-image inference and comparison.

Key operational boundary: model weights, metrics JSON, class ordering, image size, normalization, and mask color/class mappings must remain consistent between `02_data_pipeline.py`, `03_train_models.py`, and `streamlit_app.py`.

Main entry points: [`02_data_pipeline.py`](https://github.com/2536070004phd2026/prototype/blob/master/02_data_pipeline.py) (Segmentation dataset), [`03_train_models.py`](https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py) (Three segmentation models), [`streamlit_app.py`](https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py) (Inference preprocessing), [`01_download_dataset.py`](https://github.com/2536070004phd2026/prototype/blob/master/01_download_dataset.py) (Dataset verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset & Pipeline"]
  node_mendeley[("Mendeley dataset host<br/>external dataset")]
  node_local_dataset[("Local sen2lulc dataset<br/>unversioned raster data")]
  node_dataset_verify["Dataset verification<br/>Python entry point"]
  node_segmentation_dataset["Segmentation dataset<br/>PyTorch dataset abstraction"]
  node_dataloaders["Train/val/test loaders<br/>PyTorch DataLoaders"]
end

subgraph group_training["GPU Training"]
  node_training_workflow["Training workflow<br/>Python entry point<br/>[03_train_models.py]"]
  node_model_families["Three segmentation models<br/>SMP/timm models<br/>[03_train_models.py]"]
  node_gpu_runtime{{"CUDA PyTorch runtime<br/>GPU runtime"}}
  node_evaluation["Segmentation evaluation<br/>metrics stage<br/>[03_train_models.py]"]
  node_artifacts[("Checkpoints &amp; results<br/>runtime output artifacts")]
end

subgraph group_demo["Inference UI"]
  node_streamlit_ui["Streamlit application<br/>Python entry point<br/>[streamlit_app.py]"]
  node_inference_preprocessing["Inference preprocessing<br/>compatibility layer<br/>[streamlit_app.py]"]
  node_prediction_view["LULC prediction &amp; comparison<br/>interactive output<br/>[streamlit_app.py]"]
end

node_mendeley -->|"manual download &amp; extract"| node_local_dataset
node_local_dataset -->|"validate placement"| node_dataset_verify
node_local_dataset -->|"tiles and masks"| node_segmentation_dataset
node_segmentation_dataset -->|"split and batch"| node_dataloaders
node_dataloaders -->|"training inputs"| node_training_workflow
node_training_workflow -->|"instantiate and train"| node_model_families
node_gpu_runtime -->|"CUDA mixed precision"| node_training_workflow
node_model_families -->|"predictions"| node_evaluation
node_evaluation -->|"metrics summary"| node_artifacts
node_model_families -->|"trained weights"| node_artifacts
node_artifacts -->|"load checkpoints and results"| node_streamlit_ui
node_streamlit_ui -->|"uploaded image"| node_inference_preprocessing
node_inference_preprocessing -->|"model prediction"| node_prediction_view
node_artifacts -->|"comparison metrics"| node_prediction_view
node_segmentation_dataset -.->|"shared preprocessing contract"| node_inference_preprocessing

click node_dataset_verify "https://github.com/2536070004phd2026/prototype/blob/master/01_download_dataset.py"
click node_segmentation_dataset "https://github.com/2536070004phd2026/prototype/blob/master/02_data_pipeline.py"
click node_dataloaders "https://github.com/2536070004phd2026/prototype/blob/master/02_data_pipeline.py"
click node_training_workflow "https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py"
click node_model_families "https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py"
click node_evaluation "https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py"
click node_streamlit_ui "https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py"
click node_inference_preprocessing "https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py"
click node_prediction_view "https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.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_mendeley,node_local_dataset,node_dataset_verify,node_segmentation_dataset,node_dataloaders toneBlue
class node_training_workflow,node_model_families,node_gpu_runtime,node_evaluation,node_artifacts toneAmber
class node_streamlit_ui,node_inference_preprocessing,node_prediction_view toneMint
```

## Components

### Dataset & Pipeline

- **Mendeley dataset host**: external dataset
- **Local sen2lulc dataset**: unversioned raster data · Manually downloaded and extracted locally.
- [Dataset verification](https://github.com/2536070004phd2026/prototype/blob/master/01_download_dataset.py): Python entry point · Checks expected local dataset placement. · `01_download_dataset.py`
- [Segmentation dataset](https://github.com/2536070004phd2026/prototype/blob/master/02_data_pipeline.py): PyTorch dataset abstraction · Pairs satellite tiles with class masks and preprocesses both. · `02_data_pipeline.py`
- [Train/val/test loaders](https://github.com/2536070004phd2026/prototype/blob/master/02_data_pipeline.py): PyTorch DataLoaders · GPU-constrained batched training tensors. · `02_data_pipeline.py`

### GPU Training

- [Training workflow](https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py): Python entry point · Trains, evaluates, and writes demonstration artifacts. · `03_train_models.py`
- [Three segmentation models](https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py): SMP/timm models · ConvNeXt, Swin Transformer, and ResNet encoder families. · `03_train_models.py`
- **CUDA PyTorch runtime**: GPU runtime · Uses mixed precision to reduce VRAM pressure.
- [Segmentation evaluation](https://github.com/2536070004phd2026/prototype/blob/master/03_train_models.py): metrics stage · Computes IoU, Dice, and training duration. · `03_train_models.py`
- **Checkpoints & results**: runtime output artifacts · Weights and evaluation summary consumed by the UI.

### Inference UI

- [Streamlit application](https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py): Python entry point · Deployed-facing upload prediction and comparison interface. · `streamlit_app.py`
- [Inference preprocessing](https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py): compatibility layer · Must match training image size, normalization, classes, and colors. · `streamlit_app.py`
- [LULC prediction & comparison](https://github.com/2536070004phd2026/prototype/blob/master/streamlit_app.py): interactive output · Renders a color-coded mask and model metrics comparison. · `streamlit_app.py`

## Connections

- Mendeley dataset host → Local sen2lulc dataset: manual download & extract
- Local sen2lulc dataset → Dataset verification: validate placement
- Local sen2lulc dataset → Segmentation dataset: tiles and masks
- Segmentation dataset → Train/val/test loaders: split and batch
- Train/val/test loaders → Training workflow: training inputs
- Training workflow → Three segmentation models: instantiate and train
- CUDA PyTorch runtime → Training workflow: CUDA mixed precision
- Three segmentation models → Segmentation evaluation: predictions
- Segmentation evaluation → Checkpoints & results: metrics summary
- Three segmentation models → Checkpoints & results: trained weights
- Checkpoints & results → Streamlit application: load checkpoints and results
- Streamlit application → Inference preprocessing: uploaded image
- Inference preprocessing → LULC prediction & comparison: model prediction
- Checkpoints & results → LULC prediction & comparison: comparison metrics
- Segmentation dataset → Inference preprocessing: shared preprocessing contract