# bajpaidhruv2018/desert_hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/bajpaidhruv2018/desert_hackathon
- Repository: https://github.com/bajpaidhruv2018/desert_hackathon

## Overview

This repo is an **applied ML semantic-segmentation system** with two distinct “modes”:

##### Offline ML pipeline (training + evaluation + experiment iterations V0–V5)
- Multiple training scripts (`run_training.py`, `local_train*.py`, `train_total_war*.py`, etc.)
- Multiple evaluation/verification scripts (`check_iou.py`, `final_test.py`, `accurate_check.py`, etc.)
- Produces a **model artifact**: `best_model.pth`

##### Online inference/demo UI(s)
- **Streamlit app**: `app.py` (explicitly documented in README)
- A separate `web-ui/` folder that looks like a **Vite + React frontend** plus a small Python backend (`web-ui/api_server.py`) likely used as an HTTP inference API for the React UI.

So the “system” is not a single service—it’s a **pipeline + artifact + one (or two) demo surfaces**.

##### Data / Inputs
- **Offroad_Segmentation_Training_Dataset/** (gitignored, external)
- `train/Color_Images/`, `train/Segmentation/`
- `val/Color_Images/`, `val/Segmentation/`
- Key domain constraint: masks use **raw pixel IDs** (100…10000) that must be read with `cv2.imread(..., -1)` and remapped via an **ID_MAPPING** to class indices 0–9.

##### ML Training & Experimentation (offline)
- Training scripts representing iterations:
- Baseline → fixed mask mapping → augmentation/loss/scheduler → 512 fine-tune
- Core ML stack:
- **PyTorch**
- **segmentation-models-pytorch** (U-Net, ResNet34 encoder, ImageNet pretrained)
- Output:
- `best_model.pth` (weights)

##### Evaluation & Reporting (offline)
- Scripts that compute:
- IoU, pixel accuracy, confusion matrix, qualitative overlays
- Outputs stored in:
- `final_submission_results/`
- `test_results/`
- `readme_assets/` (metrics charts, etc.)

##### Inference Runtime(s) (online demo)
- **Streamlit** (`app.py`)
- Loads `best_model.pth`
- **React Web UI** (`web-ui/src/*`) + **API server** (`web-ui/api_server.py`)
- Likely: browser uploads image → API server runs inference → returns mask/overlay/metrics → UI renders

##### Streamlit path
**User → Streamlit UI (app.py) → Preprocess → Model load + inference → Postprocess overlay + confidence → UI**

##### React path
**User Browser (React/Vite) → HTTP upload → Python API server (api_server.py) → Model inference → Response (mask/overlay/metrics) → React render**

##### Training vs Inference are different runtimes
- Training: GPU-heavy, batch-based, uses augmentation, backprop
- Inference: single-image forward pass, deterministic transforms

##### Model artifact as the contract
- `best_model.pth` is the handoff between offline and online worlds
- It as a first-class node: “Model Registry/Artifact Store (local file)”

##### Dataset is external + versioned implicitly
- Since dataset is gitignored, treat it as an external dependency

##### Preprocessing/postprocessing are system components
- Especially mask ID mapping + overlay coloring + resizing to 512×512

##### Project-specific “don’t miss these details” checklist

- **Two UI surfaces** if both are real: Streamlit (`app.py`) and `web-ui/` (React + `api_server.py`)
- **Model architecture detail** at the right level: “U-Net (ResNet34 encoder, SMP)”
- **Training evolution** as either:
- a side panel listing V0–V5 scripts, or
- **Outputs**: confusion matrix + per-class IoU plots + qualitative overlays (`final_submission_results/`, `readme_assets/`)
- **Explicit boundary** around “Repo code” vs “External dataset”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ============ System Context ============
  subgraph "Diagram 1 — System Context"
    direction TB

    ActorML["ML Engineer/Team"]:::actor
    ActorUser["End User (Demo)"]:::actor

    subgraph "External Dependencies"
      direction TB
      ExtData[("Offroad_Segmentation_Training_Dataset/ (external, gitignored)")]:::externalStore
      ExtGPU["GPU Machine (optional)"]:::external
    end

    System["Offroad Environment Segmentation AI (this repo)"]:::system

    ActorML -->|"trains/evaluates"| System
    ActorUser -->|"uploads image / views results"| System
    ExtData -->|"provides images+masks"| System
    ExtGPU -.->|"accelerates training/inference"| System
  end

  %% ============ Container Diagram ============
  subgraph "Diagram 2 — Container Diagram (Offline + Online)"
    direction TB

    subgraph "Repo Boundary"
      direction TB

      subgraph "Offline: Training + Evaluation (Python)"
        direction TB
        TrainRunner["Training Script Runner (PyTorch)"]:::service
        EvalRunner["Evaluation / Verification Runner"]:::service
        TrainNotes["Notes: V0–V5 iterations\nV2 fixed mask mapping\nV3 CE+Dice + flips + cosine\nV4 512 fine-tune"]:::note
      end

      Artifact[("Model Artifact Store\nbest_model.pth (weights)")]:::artifact

      subgraph "Online: Demo Surfaces"
        direction TB

        Streamlit["Streamlit Inference Demo (app.py)"]:::service

        subgraph "Web UI (Optional)"
          direction TB
          ReactUI["React/Vite Frontend (web-ui/)"]:::frontend
          APIServer["Python Inference API Server (web-ui/api_server.py)"]:::service
        end
      end

      Reports[("Evaluation Outputs\nfinal_submission_results/\ntest_results/\nreadme_assets/")]:::store
    end

    %% Flows
    ExtData -->|"reads images+masks"| TrainRunner
    TrainRunner -->|"writes model weights"| Artifact
    ExtData -->|"reads val images+masks"| EvalRunner
    Artifact -->|"loads weights"| EvalRunner
    EvalRunner -->|"writes metrics+overlays"| Reports

    ActorUser -->|"uses UI"| Streamlit
    Artifact -->|"loads weights"| Streamlit

    ActorUser -->|"uses browser"| ReactUI
    ReactUI -->|"HTTP upload image"| APIServer
    Artifact -->|"loads weights"| APIServer
    APIServer -->|"returns mask/overlay/metrics"| ReactUI
  end

  %% ============ Component Diagram ============
  subgraph "Diagram 3 — Component Diagram (Pipeline + Inference)"
    direction TB

    subgraph "Offline ML Pipeline (Training/Evaluation Components)"
      direction TB

      subgraph "Data Ingest + Label Normalization"
        direction TB
        DL["Dataset Loader / DataLoader"]:::component
        MaskRead["Mask Reader\ncv2.imread(..., -1)"]:::component
        RawIDs["Raw Pixel IDs\n(100…10000)"]:::component
        IDMap["ID_MAPPING\n{100→0,…,10000→9}"]:::component
        Targets["Target Tensor\nclass indices 0–9"]:::component
      end

      subgraph "Training Loop (Backprop)"
        direction TB
        Aug["Augmentation\n(flips, etc.)"]:::component
        ResizeTrain["Input Resize\n512×512"]:::component
        Model["Model: U-Net\n(ResNet34 encoder, SMP)"]:::component
        Loss["Loss: CE + Dice"]:::component
        Opt["Optimizer: Adam"]:::component
        Sched["Scheduler: Cosine Annealing"]:::component
        Ckpt["Checkpointing\n(best)"]:::component
      end

      subgraph "Evaluation + Reporting"
        direction TB
        InferLoop["Inference Loop\n(val/test)"]:::component
        Metrics["Metrics\nIoU + Pixel Acc\nConfusion Matrix"]:::component
        Overlays["Qualitative Overlays\n(mask+color)"]:::component
        Plots["Charts/Reports\n(readme_assets)"]:::component
      end
    end

    subgraph "Online Inference Components (Streamlit / API)"
      direction TB
      Pre["Preprocess\nresize/normalize"]:::component
      LoadW["Load Weights\nbest_model.pth"]:::component
      Forward["Forward Pass\n10-class logits"]:::component
      Post["Postprocess\nsoftmax/confidence\nargmax mask"]:::component
      Color["Mask → Color Legend"]:::component
      OverlayGen["Overlay Generator"]:::component

      subgraph "Response Surface"
        direction TB
        UIResp["UI Render (Streamlit)\nor JSON/Image (API)"]:::component
      end
    end

    %% Offline flows
    ExtData -->|"reads images+masks"| DL
    DL -->|"reads masks"| MaskRead
    MaskRead -->|"produces"| RawIDs
    RawIDs -->|"mapped via"| IDMap
    IDMap -->|"yields"| Targets

    DL -->|"images"| Aug
    Aug -->|"transforms"| ResizeTrain
    ResizeTrain -->|"tensor"| Model
    Targets -->|"supervision"| Loss
    Model -->|"pred logits"| Loss
    Loss -->|"grads"| Opt
    Opt -->|"updates"| Model
    Sched -->|"lr schedule"| Opt
    Model -->|"saves best"| Ckpt
    Ckpt -->|"writes"| Artifact

    Artifact -->|"loads weights"| InferLoop
    DL -->|"val/test batches"| InferLoop
    InferLoop -->|"computes"| Metrics
    InferLoop -->|"generates"| Overlays
    Metrics -->|"writes"| Reports
    Overlays -->|"writes"| Reports
    Metrics -->|"summarize"| Plots
    Plots -->|"stored in"| Reports

    %% Online flows
    ActorUser -->|"upload image"| Pre
    Pre -->|"normalized tensor"| LoadW
    LoadW -->|"model ready"| Forward
    Artifact -->|"weights"| LoadW
    Forward -->|"logits"| Post
    Post -->|"mask"| Color
    Color -->|"colored mask"| OverlayGen
    OverlayGen -->|"overlay+metrics"| UIResp
  end

  %% ============ Click Events (from component_mapping) ============
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/run_training.py"
  click Artifact "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/best_model.pth"

  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/check_iou.py"
  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/accurate_check.py"
  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/final_test.py"
  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/final_submission_test.py"
  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/check_model.py"
  click EvalRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/check_split.py"

  click Reports "https://github.com/bajpaidhruv2018/desert_hackathon/tree/main/final_submission_results/"
  click Reports "https://github.com/bajpaidhruv2018/desert_hackathon/tree/main/test_results/"
  click Reports "https://github.com/bajpaidhruv2018/desert_hackathon/tree/main/readme_assets/"
  click Plots "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/readme_assets/metrics.txt"

  click Streamlit "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/app.py"

  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/tree/main/web-ui/"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/App.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/main.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/index.html"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/vite.config.js"

  click APIServer "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/api_server.py"

  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/tree/main/web-ui/src/components/"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/Upload.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/Legend.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/Metrics.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/Hero.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/Navbar.jsx"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/src/components/HowItWorks.jsx"

  click System "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/requirements.txt"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/package.json"
  click ReactUI "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/web-ui/package-lock.json"

  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/local_train.py"
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/local_train_final.py"
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/local_train_v2.py"
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/local_train_v3.py"
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/train_total_war.py"
  click TrainRunner "https://github.com/bajpaidhruv2018/desert_hackathon/blob/main/train_total_war_v2.py"

  %% ============ Styles ============
  classDef actor fill:#2ecc71,stroke:#145a32,stroke-width:1px,color:#0b2e13
  classDef external fill:#ecf0f1,stroke:#7f8c8d,stroke-width:1px,color:#2c3e50
  classDef externalStore fill:#dfe6e9,stroke:#636e72,stroke-width:1px,color:#2d3436
  classDef system fill:#9b59b6,stroke:#4a235a,stroke-width:1px,color:#ffffff
  classDef service fill:#3498db,stroke:#1f4e79,stroke-width:1px,color:#ffffff
  classDef frontend fill:#27ae60,stroke:#145a32,stroke-width:1px,color:#ffffff
  classDef store fill:#95a5a6,stroke:#2f3640,stroke-width:1px,color:#ffffff
  classDef artifact fill:#7f8c8d,stroke:#2d3436,stroke-width:1px,color:#ffffff
  classDef component fill:#5dade2,stroke:#1b4f72,stroke-width:1px,color:#0b2235
  classDef note fill:#f9e79f,stroke:#7d6608,stroke-width:1px,color:#4d3f00
```
