# deusnexus/geo-ai-superres architecture

> Architecture diagram of the GitHub repository deusnexus/geo-ai-superres, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deusnexus/geo-ai-superres
- Repository: https://github.com/deusnexus/geo-ai-superres

## Overview

##### Project Type and Purpose
- This is a geospatial AI pipeline combining data ingestion, preprocessing, super‐resolution modeling, land‐cover classification, temporal analysis, and urban growth prediction.
- It operates as a research/analysis tool rather than a traditional deployed web service. Core interactions happen in Jupyter notebooks invoking modular Python code.

##### Key Components
a. Data Layer
- Raw satellite imagery (“Sentinel‐1,” “Sentinel‐2,” DEM) and auxiliary masks (NDVI, slope, water bodies) under data/raw and data/masks.
- Processed datasets (cloud‐masked, normalized) under data/processed.
- Super‐resolved outputs stored in data/superres.
- Time‐series data for trend analysis under data/temporal.
b. Processing Layer (src/data_processing)
- Data ingestion and chunking into patches.
- GeoJSON metadata handling for patches_on_land, highlighted_patches.
- Preprocessing steps called by notebooks (normalization, masking).
c. Modeling Layer (src/models and models/)
- Super‐resolution model (EHNet: CNN + Swin Transformer)
- Land‐cover classification model
- Urban growth prediction model
- Checkpoints and weights stored in models/*.pth
d. Analysis & Visualization (src/visualization, notebooks)
- Jupyter notebooks orchestrate entire pipeline:
– 00_* for data exploration and patch extraction
– 01_* to 05_* for training superres, classification, temporal analysis, growth prediction
- Visualization utilities for maps, charts, and generation of final reports and figures.
e. Outputs
- Final maps, charts, reports saved under outputs/maps, outputs/charts, outputs/reports.

##### Interactions and Data Flow
- Flow starts with raw imagery → data_processing modules → processed patches.
- Processed patches feed into model training pipelines for super‐resolution, land‐cover, and growth models.
- Trained models are loaded by notebooks for inference, generating high‐res outputs and predictions.
- Visualization modules consume predictions and raw/processed imagery to produce maps and dashboards.

##### Architectural Patterns and Design Principles
- Modular layering: clear separation between data ingestion, preprocessing, model training, and visualization.
- Notebook‐driven orchestration: notebooks as control plane that invoke Python modules in src/.
- Checkpointing: persistent model artifacts in models/ for reproducibility.
- Reusability & extensibility: src/utils for shared code; ability to swap models or add new analysis notebooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        DS["Data Storage\n(raw, processed, masks,\nsuperres, temporal)"]:::data
        subgraph "Patches & Metadata"
            Patches["Patches Directory"]:::storage
            HPatches["Highlighted Patches\n.geojson"]:::storage
            LPatches["Patches on Land\n.geojson"]:::storage
            Meta["Metadata\n.json"]:::storage
        end
    end

    Preprocessing["Preprocessing Service\n(src/data_processing)"]:::compute
    Processing["Processed Data Storage"]:::data

    ModelTraining["Model Training Service\n(src/models)"]:::compute

    subgraph "Model Storage"
        SRCP["Super-Resolution Model\n.pth"]:::storage
        LPModel["Land-Cover Classification\n.pth"]:::storage
        UPModel["Urban Growth Prediction\n.pth"]:::storage
    end

    subgraph "Notebook Orchestrator (Jupyter)"
        NB1["Data Exploration &\nPatch Extraction"]:::notebooks
        NB2["Masking &\nPreparation"]:::notebooks
        NB3["Super-Resolution\nTraining"]:::notebooks
        NB4["Land-Cover\nClassification"]:::notebooks
        NB5["Temporal\nAnalysis"]:::notebooks
        NB6["Urban Growth\nPrediction"]:::notebooks
        NBlog["Batch Job Logs\n.csv"]:::storage
    end

    Visualization["Visualization Service\n(src/visualization)"]:::compute
    Outputs["Outputs\n(maps, charts, reports)"]:::outputs

    DS -->|"Raw imagery\n(TIFF)"| Preprocessing
    Patches -->|"GeoJSON patches"| Preprocessing
    Preprocessing -->|"Processed patches"| Processing
    Processing -->|"Processed data"| ModelTraining

    ModelTraining -->|"Checkpoint .pth"| SRCP
    ModelTraining -->|"Checkpoint .pth"| LPModel
    ModelTraining -->|"Checkpoint .pth"| UPModel

    SRCP --> NB3
    LPModel --> NB4
    UPModel --> NB6

    Processing --> NB3
    Processing --> NB4
    Processing --> NB5
    Processing --> NB6

    NB1 -->|"controls"| Preprocessing
    NB2 -->|"controls"| Preprocessing

    NB3 -->|"predictions"| Visualization
    NB4 -->|"predictions"| Visualization
    NB5 -->|"analysis"| Visualization
    NB6 -->|"predictions"| Visualization

    Visualization -->|"figures & maps"| Outputs

    click Patches "https://github.com/deusnexus/geo-ai-superres/tree/main/data/patches/"
    click HPatches "https://github.com/deusnexus/geo-ai-superres/blob/main/data/patches/highlighted_patches.geojson"
    click LPatches "https://github.com/deusnexus/geo-ai-superres/blob/main/data/patches/patches_on_land.geojson"
    click Meta "https://github.com/deusnexus/geo-ai-superres/blob/main/data/patches/metadata.json"
    click SRCP "https://github.com/deusnexus/geo-ai-superres/blob/main/models/superres_model.pth"
    click LPModel "https://github.com/deusnexus/geo-ai-superres/blob/main/models/landcover_model.pth"
    click UPModel "https://github.com/deusnexus/geo-ai-superres/blob/main/models/urban_growth_model.pth"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_01_shp_bali.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_02_patches.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_03_visualize_patches.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_sentinel-1_patches_v2.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_sentinel-1_visualize.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_sentinel-2.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_sentinel-2_patches.ipynb"
    click NB1 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/00_sentinel-2_patches_v2.ipynb"
    click NB2 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/01_00_urban_mask.ipynb"
    click NB2 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/01_01_dem_mask.ipynb"
    click NB2 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/01_data_preparation.ipynb"
    click NB3 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/02_superresolution_training.ipynb"
    click NB4 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/03_land_cover_classification.ipynb"
    click NB5 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/04_temporal_analysis.ipynb"
    click NB6 "https://github.com/deusnexus/geo-ai-superres/blob/main/notebooks/05_urban_growth_prediction.ipynb"

    classDef data fill:#cce5ff,stroke:#004085,color:#004085
    classDef compute fill:#d4edda,stroke:#155724,color:#155724
    classDef notebooks fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef outputs fill:#fff3cd,stroke:#856404,color:#856404
```
