# mikejohnson51/climater architecture

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

- Interactive diagram: https://gitdiagram.com/mikejohnson51/climater
- Repository: https://github.com/mikejohnson51/climater

## Overview

##### Project type and purpose
- This is an R package (library) published to CRAN/GitHub.
- Purpose: provide a “catalog + data‐access toolkit + shortcuts” for fetching spatio-temporal climate, land‐cover, and soils data from remote gridded data services (OPeNDAP, COG, VRT, ERDDAP).
- Secondary purposes: integrate with AOI (area-of-interest) and zonal packages; build documentation site via pkgdown; maintain CI/CD via GitHub Actions.

##### File structure
Top-level directories/files:
- R/ – core R source modules (catalog, dap, shortcuts, utilities, viz, zarr, netrc).
- man/ – Rd reference pages.
- data–raw/ + data/ + inst/ – packaged example data, built catalog.
- vignettes/ + docs/ – tutorials and pkgdown-built website.
- tests/ – testthat unit tests.
- .gitignore, DESCRIPTION, NAMESPACE, README.Rmd, pkgdown config, GitHub workflows (.github/workflows).
Architectural hints: single holistic package, but internally subdivided into three functional layers:
1. Catalog management (metadata registry)
2. Data access primitives (dap, read_dap_file, zarr, etc.)
3. User-facing shortcuts (getGridMET, getMODIS, getNLCD, etc.)

##### Key insights from README.md
- Three pillars: federated catalog (monthly auto-rebuild), general data-access API, high-level shortcuts.
- Integration points: AOI package for geometries; zonal for areal summaries; terra for raster handling; netrc for authentication.
- External dependencies: OPeNDAP servers, ERDDAP, COG, VRT, remote HTTP.

##### Main components and interactions
A. Core climateR Package (inside the R process)
– Catalog Module (R/catalog.R, data/catalog.rda, data-raw)
– Data-Access Module (R/dap.R, R/zarr.R, R/extract-sites.R)
– Shortcuts Module (R/shortcuts.R)
– Utilities (auth via netrc, wgt via meta_tools, visualization via viz)
B. External R Packages
– AOI (defines spatial extents)
– terra (raster handling)
– zonal (future summaries)
– OPeNDAP endpoints (GridMET, MACA, MODIS, etc.)
– COG endpoints (NLCD, soils)
– VRT endpoints (USGS 3DEP)
– ERDDAP servers (CHIRPS, etc.)
D. User/Client
– R script or interactive session calls climateR functions.
E. CI/CD and Documentation
– GitHub Actions (R-CMD-check, test-coverage)
– pkgdown build (docs/ → docs site)

1. User → climateR API (catalog, data-access, shortcuts)
2. climateR → AOI (geometry definitions)
3. climateR data-access → remote services (OPeNDAP, COG, VRT, ERDDAP) over HTTP/OPeNDAP
4. Remote service → climateR (SpatRaster or array)
5. climateR → terra / into R objects → back to user
6. Optional: climateR output → zonal for summaries → back to user
7. CI/CD pipeline triggers: push → GitHub Actions → run tests → build pkgdown site → deploy docs

##### Architectural patterns and design principles
- Modular layering: separate catalog, low-level API, high-level shortcuts.
- Dependency inversion: user code depends on high-level shortcuts; shortcuts rely on low-level API, which talk to external services.
- Single-responsibility: each R file/module has a narrow focus.
- Federated metadata: catalog is external but packaged; monthly auto-update via data-raw script.
- Stateless client: climateR does not host a server; all remote calls are live, no local server component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user

    subgraph "Internal Modules"
      subgraph "Catalog Module"
        Cat1["catalog.R"]:::catalog
        Cat2["update_catalog.R"]:::catalog
        Cat3["climateR-catalog.R"]:::catalog
        Cat4["catalog.rda"]:::catalog
      end
      subgraph "Data-Access Module"
        DA1["dap.R"]:::dataaccess
        DA2["zarr.R"]:::dataaccess
        DA3["extract-sites.R"]:::dataaccess
        DA4["climater_filter.R"]:::dataaccess
        DA5["meta_tools.R"]:::dataaccess
        DA6["netrc_utils.R"]:::dataaccess
      end
      subgraph "Shortcuts Module"
        SC["shortcuts.R"]:::shortcuts
      end
      subgraph "Utilities"
        U1["utils.R"]:::util
        U2["viz.R"]:::util
        U3["netrc_utils.R"]:::util
        U4["meta_tools.R"]:::util
      end
    end

    subgraph "External R Packages"
        AOI["AOI"]:::external
        Terra["terra"]:::external
        Zonal["zonal"]:::external
    end

    subgraph "Remote Data Services"
        OPeNDAP["OPeNDAP Endpoints"]:::remote
        COG["COG Endpoints"]:::remote
        VRT["VRT Endpoints"]:::remote
        ERDDAP["ERDDAP Servers"]:::remote
    end

    subgraph "CI/CD & Documentation"
        GH1["R-CMD-check.yaml"]:::ci
        GH2["test-coverage.yaml"]:::ci
        CC["codecov.yml"]:::ci
        PKG1["_pkgdown.yml"]:::doc
        PKG2["vignettes/*.Rmd"]:::doc
        PKG3["docs/"]:::doc
    end

    subgraph "Tests"
      Test1["test-climateR.R"]:::test
      Test2["test-earthdata.R"]:::test
      Test3["test-netrc.R"]:::test
      Test4["testthat.R"]:::test
    end

    User -->|"calls"| SC
    User -->|"queries"| Cat1
    SC -->|"usesAPI"| DA1
    SC -->|"metadataLookup"| Cat1
    DA1 -->|"authViaNetrc"| DA6
    DA1 -->|"dataOpsViaMetaTools"| DA5
    DA1 -->|"fetches"| OPeNDAP
    DA1 -->|"fetches"| COG
    DA1 -->|"fetches"| VRT
    DA1 -->|"fetches"| ERDDAP
    OPeNDAP -->|"data"| DA1
    COG -->|"data"| DA1
    VRT -->|"data"| DA1
    ERDDAP -->|"data"| DA1
    DA1 -->|"createsRaster"| Terra
    Terra -->|"returnsSpatRaster"| User
    User -->|"optionalSummary"| Zonal
    Zonal -->|"returnsSummary"| User

    GH1 -.->|"runsTests"| Test1
    GH1 --> Test1
    GH1 --> Test2
    GH1 --> Test3
    GH1 --> Test4
    GH2 -->|"coverage"| CC
    GH1 -->|"buildSite"| PKG1
    PKG1 --> PKG3

    click Cat1 "https://github.com/mikejohnson51/climater/blob/master/R/catalog.R"
    click Cat2 "https://github.com/mikejohnson51/climater/blob/master/R/update_catalog.R"
    click Cat3 "https://github.com/mikejohnson51/climater/blob/master/data-raw/climateR-catalog.R"
    click Cat4 "https://github.com/mikejohnson51/climater/blob/master/data/catalog.rda"
    click DA1 "https://github.com/mikejohnson51/climater/blob/master/R/dap.R"
    click DA2 "https://github.com/mikejohnson51/climater/blob/master/R/zarr.R"
    click DA3 "https://github.com/mikejohnson51/climater/blob/master/R/extract-sites.R"
    click DA4 "https://github.com/mikejohnson51/climater/blob/master/R/climater_filter.R"
    click DA5 "https://github.com/mikejohnson51/climater/blob/master/R/meta_tools.R"
    click DA6 "https://github.com/mikejohnson51/climater/blob/master/R/netrc_utils.R"
    click SC "https://github.com/mikejohnson51/climater/blob/master/R/shortcuts.R"
    click U1 "https://github.com/mikejohnson51/climater/blob/master/R/utils.R"
    click U2 "https://github.com/mikejohnson51/climater/blob/master/R/viz.R"
    click U3 "https://github.com/mikejohnson51/climater/blob/master/R/netrc_utils.R"
    click U4 "https://github.com/mikejohnson51/climater/blob/master/R/meta_tools.R"
    click Test1 "https://github.com/mikejohnson51/climater/blob/master/tests/testthat/test-climateR.R"
    click Test2 "https://github.com/mikejohnson51/climater/blob/master/tests/testthat/test-earthdata.R"
    click Test3 "https://github.com/mikejohnson51/climater/blob/master/tests/testthat/test-netrc.R"
    click Test4 "https://github.com/mikejohnson51/climater/blob/master/tests/testthat.R"
    click PKG1 "https://github.com/mikejohnson51/climater/blob/master/_pkgdown.yml"
    click PKG2 "https://github.com/mikejohnson51/climater/tree/master/vignettes"
    click PKG3 "https://github.com/mikejohnson51/climater/tree/master/docs/"
    click GH1 "https://github.com/mikejohnson51/climater/blob/master/.github/workflows/R-CMD-check.yaml"
    click GH2 "https://github.com/mikejohnson51/climater/blob/master/.github/workflows/test-coverage.yaml"
    click CC "https://github.com/mikejohnson51/climater/blob/master/codecov.yml"

    classDef catalog fill:#FFD700,stroke:#333,stroke-width:1px
    classDef dataaccess fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef shortcuts fill:#90EE90,stroke:#333,stroke-width:1px
    classDef util fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray:5 5
    classDef remote fill:#FFFFFF,stroke:#000,stroke-width:2px,stroke-dasharray:2 2
    classDef ci fill:#F5DEB3,stroke:#333,stroke-width:1px,stroke-dasharray:2 2
    classDef doc fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef test fill:#FFE4E1,stroke:#333,stroke-width:1px
    classDef user fill:#98FB98,stroke:#333,stroke-width:2px

    subgraph Legend
      A["Catalog Module"]:::catalog
      B["Data-Access Module"]:::dataaccess
      C["Shortcuts Module"]:::shortcuts
      D["Utilities"]:::util
      E["External R Packages"]:::external
      F["Remote Data Services"]:::remote
      G["CI/CD"]:::ci
      H["Documentation"]:::doc
      I["Tests"]:::test
      J["User"]:::user
    end
```
