# shud-system/rshud architecture

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

- Interactive diagram: https://gitdiagram.com/shud-system/rshud
- Repository: https://github.com/shud-system/rshud

## Overview

##### Project Type and Purpose
- Type: An open-source R toolbox (R package) supplemented by C++ (via Rcpp) for computationally intensive tasks.
- Purpose: Prepare, configure, and analyze SHUD (Simulator for Hydrological Unstructured Domain) models—handling GIS data ingestion, mesh generation, SHUD input/output, calibration, time-series analysis, and visualization.

##### Main Architectural Components
a.  R Layer (Core Toolbox)
- Submodules under R/:
–  Data Ingestion & Filtering (DataFilter.R, Func_Get.R, read*.R)
–  GIS Processing (Func_GIS.R, GIS_*.R, NLCD.R)
–  Mesh & Domain Generation (MeshDomain.R, triangulate.R, triTopology.cpp wrapper)
–  Model Configuration & I/O (ModelConfigure.R, writeInput.R, readout.R, write.*.R)
–  Calibration & Parameter Tools (Func_PTF.R, ModelBC.R)
–  Time-Series & Analysis (Hydro_obs.R, readTSD.R, ts2*.R)
–  Visualization & Plotting (plot.R, plotMap.R, demo scripts)
b.  Native Layer (C++ via Rcpp)
- src/polygonArea.cpp, src/triTopology.cpp – performance-critical geometry routines
- RcppExports.cpp – glue code between R and C++
c.  External Dependencies & Services
- GDAL/PROJ (vector/raster reprojection, shapefile, raster I/O)
- RTriangle (Delaunay triangulation)
- netCDF4 (reading/writing NetCDF climate/forcing data)
- R packages: sp, gstat, ncdf4, raster, etc.
d.  Data Stores & Artifacts
- /data – sample .rda datasets
- SHUD input files (.riv, .ic, .forc, mesh files)
- SHUD output files (time-series, NetCDF)
- Shapefiles/Rasters generated by GIS routines
e.  Demo & Examples
- /demo – end-to-end scripts that orchestrate data ingestion → mesh building → model file writing → result plotting

##### Relationships & Data Flows
- Ingestion Layer reads raw spatial (raster/vector) and time-series data → hands off to GIS Processing.
- GIS Processing calls GDAL/PROJ to standardize projections → outputs cleaned spatial layers.
- Mesh Generation invokes RTriangle and C++ geometry routines (via Rcpp) → creates unstructured triangular mesh.
- Model Configuration assembles mesh + parameter sets → writes SHUD input files.
- SHUD engine (external process) runs on input files (not inside this package).
- I/O Layer reads SHUD output (NetCDF or text) → feeds into analysis (time-series) and visualization modules.
- Demo scripts orchestrate and display end-to-end workflows.

##### Architectural Patterns & Design Principles
- Modular separation: each functional area (GIS, mesh, I/O, analysis) is a distinct R namespace.
- Hybrid computation: heavy geometry tasks offloaded to C++/Rcpp.
- Extensibility: new GIS formats or mesh algorithms can be plugged in by adding R functions or C++ modules.
- Data-centric flow: clearly delineated layers moving from raw inputs to processed outputs.

##### Technologies, Frameworks & Libraries
- R + devtools/testthat for package development and testing
- Rcpp for native integration
- GDAL/PROJ for spatial I/O and reprojection
- RTriangle for triangulation
- ncdf4 for NetCDF handling
- sp, raster, gstat, hydroGOF, xts for analysis/plotting

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "R Layer: Data Ingestion & Filtering"
        DF["DataFilter.R"]:::rModule
        FG["Func_Get.R"]:::rModule
        RI["readinput.R"]:::rModule
    end

    subgraph "R Layer: GIS Processing"
        GIS1["Func_GIS.R"]:::rModule
        GIS2["GIS_SimplifyPolylines.R"]:::rModule
        GIS3["GIS_Projection.R"]:::rModule
        NLCD["NLCD.R"]:::rModule
    end

    subgraph "R Layer: Mesh & Domain Generation"
        MD["MeshDomain.R"]:::rModule
        TRI["trianglulate.R"]:::rModule
    end

    subgraph "Native Layer (C++)"
        RCPP["RcppExports.cpp"]:::cppModule
        POLY["polygonArea.cpp"]:::cppModule
        TRI_CPP["triTopology.cpp"]:::cppModule
    end

    subgraph "R Layer: Model Configuration & I/O"
        MC["ModelConfigure.R"]:::rModule
        WI["writeInput.R"]:::rModule
        RO["readout.R"]:::rModule
    end

    subgraph "R Layer: Calibration & Parameter Tools"
        PTF["Func_PTF.R"]:::rModule
        MBC["ModelBC.R"]:::rModule
    end

    subgraph "R Layer: Time-Series & Analysis"
        HO["Hydro_obs.R"]:::rModule
        TS["readTSD.R"]:::rModule
    end

    subgraph "R Layer: Visualization & Plotting"
        PLOT["plot.R"]:::rModule
        PM["plotMap.R"]:::rModule
    end

    subgraph "External Dependencies & Services"
        GDAL["GDAL/PROJ"]:::external
        RT["RTriangle"]:::external
        NETCDF["netCDF4"]:::external
        RPKG["sp, gstat, raster, etc."]:::external
    end

    subgraph "Data Stores & Artifacts"
        RAW["/data"]:::datastore
        GIS_OUT["Shapefiles/Rasters"]:::datastore
        SHUD_IN["SHUD Input Files"]:::datastore
        SHUD_OUT["SHUD Output Files"]:::datastore
    end

    subgraph "Demo & Examples"
        DEMO["demo/ scripts"]:::demo
    end

    SHUD["External SHUD Engine"]:::external

    %% Data flow
    RAW --> DF
    DF --> GIS1
    GIS1 --> GIS_OUT
    GIS2 --> GIS_OUT
    GIS3 --> GIS_OUT
    NLCD --> GIS_OUT
    GIS1 --> GDAL
    GIS3 --> GDAL
    GIS_OUT --> MD
    MD --> TRI_CPP
    MD --> POLY
    TRI_CPP --> MD
    POLY --> MD
    RCPP --> MD
    MD --> MC
    MC --> SHUD_IN
    SHUD_IN --> SHUD
    SHUD --> SHUD_OUT
    SHUD_OUT --> RO
    RO --> TS
    TS --> PLOT
    PLOT --> DEMO

    %% Demo orchestration
    DEMO --> DF
    DEMO --> MD
    DEMO --> MC
    DEMO --> PLOT

    %% Click Events
    click DF "https://github.com/shud-system/rshud/blob/master/R/DataFilter.R"
    click FG "https://github.com/shud-system/rshud/blob/master/R/Func_Get.R"
    click RI "https://github.com/shud-system/rshud/blob/master/R/readinput.R"
    click GIS1 "https://github.com/shud-system/rshud/blob/master/R/Func_GIS.R"
    click GIS2 "https://github.com/shud-system/rshud/blob/master/R/GIS_SimplifyPolylines.R"
    click GIS3 "https://github.com/shud-system/rshud/blob/master/R/GIS_Projection.R"
    click NLCD "https://github.com/shud-system/rshud/blob/master/R/NLCD.R"
    click MD "https://github.com/shud-system/rshud/blob/master/R/MeshDomain.R"
    click TRI "https://github.com/shud-system/rshud/blob/master/R/trianglulate.R"
    click TRI_CPP "https://github.com/shud-system/rshud/blob/master/src/triTopology.cpp"
    click MC "https://github.com/shud-system/rshud/blob/master/R/ModelConfigure.R"
    click WI "https://github.com/shud-system/rshud/blob/master/R/writeInput.R"
    click RO "https://github.com/shud-system/rshud/blob/master/R/readout.R"
    click PTF "https://github.com/shud-system/rshud/blob/master/R/Func_PTF.R"
    click MBC "https://github.com/shud-system/rshud/blob/master/R/ModelBC.R"
    click HO "https://github.com/shud-system/rshud/blob/master/R/Hydro_obs.R"
    click TS "https://github.com/shud-system/rshud/blob/master/R/readTSD.R"
    click PLOT "https://github.com/shud-system/rshud/blob/master/R/plot.R"
    click PM "https://github.com/shud-system/rshud/blob/master/R/plotMap.R"
    click RCPP "https://github.com/shud-system/rshud/blob/master/src/RcppExports.cpp"
    click POLY "https://github.com/shud-system/rshud/blob/master/src/polygonArea.cpp"
    click RAW "https://github.com/shud-system/rshud/tree/master/data/"
    click DEMO "https://github.com/shud-system/rshud/tree/master/demo/"

    %% Styles
    classDef rModule fill:#ADD8E6,stroke:#333;
    classDef cppModule fill:#90EE90,stroke:#333;
    classDef external fill:#FFFF99,stroke:#333;
    classDef datastore fill:#D3D3D3,stroke:#333;
    classDef demo stroke-dasharray: 5 5,fill:#FFF,stroke:#333;
```
