# zhengyi-yan/plumewatch architecture

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

- Interactive diagram: https://gitdiagram.com/zhengyi-yan/plumewatch
- Repository: https://github.com/zhengyi-yan/plumewatch

## Overview

PlumeWatch is a Sentinel-2 coastal-plume classification and review product, with an accompanying annotation and model-development workflow. The main user flow loads or uploads a scene, classifies it with a selected model, compares and inspects map layers, then exports native-grid rasters and summaries. Separate branches prepare reviewed labels and train/evaluate models. The README documents dashboard capabilities and connections; some implementation details, especially unsampled integrations and model dispatch, are represented only where documented or marked unverified.

Main entry points: [`app.py`](https://github.com/zhengyi-yan/plumewatch/blob/main/app.py) (Review dashboard), [`processing.py`](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py) (Class results), [`unet_worker.py`](https://github.com/zhengyi-yan/plumewatch/blob/main/unet_worker.py) (U-Net inference), [`annotation_pipeline.py`](https://github.com/zhengyi-yan/plumewatch/blob/main/annotation_pipeline.py) (Mask preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Scene review"]
  node_scene["Scene input<br/>[app.py]"]
  node_dashboard_app["Review dashboard<br/>[app.py]"]
  node_map_ui["Map controls<br/>[app.js]"]
  node_exports["Raster exports<br/>[processing.py]"]
end

subgraph group_inference["Classification"]
  node_scene_processing["Scene processing<br/>[processing.py]"]
  node_rf["Random Forest<br/>[processing.py]"]
  node_svm["RBF SVM<br/>[processing.py]"]
  node_unet_worker["U-Net inference<br/>[unet_worker.py]"]
  node_unet_model["U-Net model<br/>[model.py]"]
  node_results["Class results<br/>[processing.py]"]
end

subgraph group_annotation["Annotation"]
  node_annotation_tool["SAM candidates<br/>[auto_label.py]"]
  node_cvat["CVAT review<br/>[auto_label.py]"]
  node_mask_prep["Mask preparation"]
end

subgraph group_modeling["Model development"]
  node_rf_training["RF training"]
  node_svm_training["SVM training<br/>[train_svm.py]"]
  node_unet_training["U-Net training<br/>[run.py]"]
  node_patch_data["Patch sampling<br/>[data.py]"]
  node_model_arch["U-Net architecture<br/>[model.py]"]
end

subgraph group_exports["Scene preparation"]
  node_gee_exporter["Scene export scripts"]
end

node_user(("Reviewer"))
node_gee(("GEE exporter"))

node_user -->|"uses"| node_dashboard_app
node_gee -.->|"requests scenes"| node_gee_exporter
node_gee_exporter -.->|"exports GeoTIFF"| node_scene
node_user -->|"loads scene"| node_scene
node_dashboard_app -->|"calls"| node_scene_processing
node_dashboard_app -->|"presents controls"| node_map_ui
node_scene_processing -.->|"classifies"| node_rf
node_scene_processing -.->|"classifies"| node_svm
node_scene_processing -.->|"dispatches inference"| node_unet_worker
node_unet_worker -->|"runs model"| node_unet_model
node_rf -.->|"writes predictions"| node_results
node_svm -.->|"writes predictions"| node_results
node_unet_worker -->|"writes rasters"| node_results
node_results -->|"displays results"| node_dashboard_app
node_dashboard_app -->|"downloads"| node_exports
node_user -.->|"starts labeling"| node_annotation_tool
node_annotation_tool -->|"creates task"| node_cvat
node_cvat -->|"provides annotations"| node_mask_prep
node_mask_prep -->|"prepares labels"| node_rf_training
node_mask_prep -->|"provides masks"| node_patch_data
node_patch_data -->|"samples patches"| node_unet_training
node_unet_training -->|"trains"| node_model_arch
node_rf_training -.->|"evaluates model"| node_results
node_user -->|"reproduces fit"| node_svm_training

click node_scene "https://github.com/zhengyi-yan/plumewatch/blob/main/app.py"
click node_dashboard_app "https://github.com/zhengyi-yan/plumewatch/blob/main/app.py"
click node_map_ui "https://github.com/zhengyi-yan/plumewatch/blob/main/www/app.js"
click node_scene_processing "https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py"
click node_rf "https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py"
click node_svm "https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py"
click node_unet_worker "https://github.com/zhengyi-yan/plumewatch/blob/main/unet_worker.py"
click node_unet_model "https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/model.py"
click node_results "https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py"
click node_annotation_tool "https://github.com/zhengyi-yan/plumewatch/blob/main/integrations/cvat-sam2/auto_label.py"
click node_cvat "https://github.com/zhengyi-yan/plumewatch/blob/main/integrations/cvat-sam2/auto_label.py"
click node_mask_prep "https://github.com/zhengyi-yan/plumewatch/blob/main/annotation_pipeline.py"
click node_rf_training "https://github.com/zhengyi-yan/plumewatch/blob/main/train_multiclass.py"
click node_svm_training "https://github.com/zhengyi-yan/plumewatch/blob/main/train_svm.py"
click node_unet_training "https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/run.py"
click node_patch_data "https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/data.py"
click node_model_arch "https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/model.py"
click node_exports "https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py"
click node_gee_exporter "https://github.com/zhengyi-yan/plumewatch/blob/main/reusable_plume_export.js"

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_scene,node_dashboard_app,node_map_ui,node_exports,node_user toneBlue
class node_scene_processing,node_rf,node_svm,node_unet_worker,node_unet_model,node_results toneAmber
class node_annotation_tool,node_cvat,node_mask_prep toneMint
class node_rf_training,node_svm_training,node_unet_training,node_patch_data,node_model_arch toneRose
class node_gee_exporter,node_gee toneIndigo
```

## Components

### Scene review

- [Scene input](https://github.com/zhengyi-yan/plumewatch/blob/main/app.py): `app.py`
- [Review dashboard](https://github.com/zhengyi-yan/plumewatch/blob/main/app.py): `app.py`
- [Map controls](https://github.com/zhengyi-yan/plumewatch/blob/main/www/app.js): `www/app.js`
- [Raster exports](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py): `processing.py`

### Classification

- [Scene processing](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py): `processing.py`
- [Random Forest](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py): `processing.py`
- [RBF SVM](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py): `processing.py`
- [U-Net inference](https://github.com/zhengyi-yan/plumewatch/blob/main/unet_worker.py): `unet_worker.py`
- [U-Net model](https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/model.py): `experiments/unet/model.py`
- [Class results](https://github.com/zhengyi-yan/plumewatch/blob/main/processing.py): `processing.py`

### Annotation

- [SAM candidates](https://github.com/zhengyi-yan/plumewatch/blob/main/integrations/cvat-sam2/auto_label.py): `integrations/cvat-sam2/auto_label.py`
- [CVAT review](https://github.com/zhengyi-yan/plumewatch/blob/main/integrations/cvat-sam2/auto_label.py): `integrations/cvat-sam2/auto_label.py`
- [Mask preparation](https://github.com/zhengyi-yan/plumewatch/blob/main/annotation_pipeline.py): `annotation_pipeline.py`

### Model development

- [RF training](https://github.com/zhengyi-yan/plumewatch/blob/main/train_multiclass.py): `train_multiclass.py`
- [SVM training](https://github.com/zhengyi-yan/plumewatch/blob/main/train_svm.py): `train_svm.py`
- [U-Net training](https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/run.py): `experiments/unet/run.py`
- [Patch sampling](https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/data.py): `experiments/unet/data.py`
- [U-Net architecture](https://github.com/zhengyi-yan/plumewatch/blob/main/experiments/unet/model.py): `experiments/unet/model.py`

### Scene preparation

- [Scene export scripts](https://github.com/zhengyi-yan/plumewatch/blob/main/reusable_plume_export.js): `reusable_plume_export.js`

### Other components

- **Reviewer**
- **GEE exporter**

## Connections

- Reviewer → Review dashboard: uses (evidence: `README.md`)
- GEE exporter → Scene export scripts: requests scenes (evidence: `README.md`)
- Scene export scripts → Scene input: exports GeoTIFF (evidence: `README.md`)
- Reviewer → Scene input: loads scene (evidence: `README.md`)
- Review dashboard → Scene processing: calls (evidence: `app.py`)
- Review dashboard → Map controls: presents controls (evidence: `README.md`)
- Scene processing → Random Forest: classifies (evidence: `processing.py`)
- Scene processing → RBF SVM: classifies (evidence: `processing.py`)
- Scene processing → U-Net inference: dispatches inference (evidence: `unet_worker.py`)
- U-Net inference → U-Net model: runs model (evidence: `unet_worker.py`)
- Random Forest → Class results: writes predictions (evidence: `processing.py`)
- RBF SVM → Class results: writes predictions (evidence: `processing.py`)
- U-Net inference → Class results: writes rasters (evidence: `unet_worker.py`)
- Class results → Review dashboard: displays results (evidence: `README.md`)
- Review dashboard → Raster exports: downloads (evidence: `app.py`)
- Reviewer → SAM candidates: starts labeling
- SAM candidates → CVAT review: creates task (evidence: `integrations/cvat-sam2/auto_label.py`)
- CVAT review → Mask preparation: provides annotations (evidence: `annotation_pipeline.py`)
- Mask preparation → RF training: prepares labels (evidence: `train_multiclass.py`)
- Mask preparation → Patch sampling: provides masks (evidence: `experiments/unet/data.py`)
- Patch sampling → U-Net training: samples patches (evidence: `experiments/unet/run.py`)
- U-Net training → U-Net architecture: trains (evidence: `experiments/unet/run.py`)
- RF training → Class results: evaluates model (evidence: `train_multiclass.py`)
- Reviewer → SVM training: reproduces fit (evidence: `README.md`)
