# owp-spatial/hfsubsetr architecture

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

- Interactive diagram: https://gitdiagram.com/owp-spatial/hfsubsetr
- Repository: https://github.com/owp-spatial/hfsubsetr

## Overview

##### Project type and purpose
- hfsubsetR is an R package focused on providing tools to download and subset hydrofabric datasets. Its purpose is to offer functions like get_hydrofabric, get_vpu_fabric, and get_subset that allow users to interact with geospatial data (stored in geopackage file formats) and extract specific hydrofabric subsets.

##### File structure
- The “R” directory contains the core engine. Files like OGRSQLConnection.R, OGRSQLDriver.R, and OGRSQLResult.R indicate that the package uses a form of database connectivity or SQL-like queries on spatial data.
- The “man” directory and pkgdown/docs folders contain auto-generated documentation, while the “tests” folder holds unit tests to ensure functionality.
- Configuration and build files (DESCRIPTION, NAMESPACE, Rbuildignore, README.Rmd, etc.) indicate standard R package structure.

##### README for additional insights
- The README emphasizes basic use cases (downloading a hydrofabric, extracting VPU-based subsets, and subsetting by identifier).
- It clarifies that functionality is centered on processing local states (with a note “remote coming soon…”), and it highlights the core functions a user would call.

a. Main Components
– User/Application: Represents the R user or script that calls the package’s functions.
- Data Ingestion Module: Responsible for downloading/loading the hydrofabric (see get_hydrofabric and related utilities).
- Query Engine: Contains the query functions (query.R, query_*, etc.) and classes (OGRSQLConnection, OGRSQLDriver, OGRSQLResult) that abstract the execution of SQL-like operations on spatial data.
- Subsetting & Extraction Module: Functions like get_vpu_fabric and get_subset that derive or filter the desired outputs from the full dataset.
- Utilities: Auxiliary functions such as find_origin and other helper mechanisms found in utils.R.

b. Relationships and Data Flow:
– Within the package, the Data Ingestion Module passes the raw data (local geopackage files or potentially remote inputs in the future) to the Query Engine.
– The Query Engine interacts with the database abstraction layer using the OGRSQL* classes, which in turn, use external spatial libraries.
– Results flow into the Subsetting Module which then outputs the filtered hydrofabric subset.
– Internal Utilities support these modules with common routines.

##### Architectural Patterns and Design Principles
- Separation of concerns: The project is modularly divided into distinct layers (data ingestion, query processing, subsetting, utilities), which helps maintain clear boundaries between functionalities.
- Extensibility: The separate modules (evident from functions like query_source_arrow and query_source_sf) suggest that the package is designed to adapt to different data sources or formats.
- Documentation-Driven: With comprehensive man pages and pkgdown documentation, it is clear that the system relies on tight integration between code and documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User/Application"):::user

    subgraph "hfsubsetR Core Library"
        DI("Data Ingestion Module"):::core
        subgraph "Query Engine"
            QC1("OGRSQLConnection"):::core
            QC2("OGRSQLDriver"):::core
            QC3("OGRSQLResult"):::core
            QG("Query"):::core
            QSArrow("Query Source Arrow"):::core
            QSSF("Query Source SF"):::core
            QSub("Query Subset"):::core
        end
        SE("Subsetting & Extraction Module"):::core
        UT("Utilities"):::core
    end

    ED("External Dependencies (sf,arrow,DBI,etc.)"):::external
    TEST("Testing"):::test

    A -->|"calls"| DI
    DI -->|"loadsData"| QG
    QC1 -->|"connectsTo"| QG
    QC2 -->|"drives"| QG
    QC3 -->|"returnsResult"| QG
    QG -->|"invokes"| QSArrow
    QG -->|"invokes"| QSSF
    QG -->|"invokes"| QSub
    QG -->|"processes"| SE
    SE -->|"producesSubset"| A
    ED -->|"providesLibs"| QG
    DI ---|"supportedBy"| UT
    QG ---|"supportedBy"| UT
    SE ---|"supportedBy"| UT
    TEST -->|"verifies"| DI

    click DI "https://github.com/owp-spatial/hfsubsetr/blob/main/docs/reference/get_hydrofabric.html"
    click QC1 "https://github.com/owp-spatial/hfsubsetr/blob/main/R/OGRSQLConnection.R"
    click QC2 "https://github.com/owp-spatial/hfsubsetr/blob/main/R/OGRSQLDriver.R"
    click QC3 "https://github.com/owp-spatial/hfsubsetr/blob/main/R/OGRSQLResult.R"
    click QG "https://github.com/owp-spatial/hfsubsetr/blob/main/R/query.R"
    click QSArrow "https://github.com/owp-spatial/hfsubsetr/blob/main/R/query_source_arrow.R"
    click QSSF "https://github.com/owp-spatial/hfsubsetr/blob/main/R/query_source_sf.R"
    click QSub "https://github.com/owp-spatial/hfsubsetr/blob/main/R/query_subset.R"
    click SE "https://github.com/owp-spatial/hfsubsetr/blob/main/docs/reference/get_vpu_fabric.html"
    click UT "https://github.com/owp-spatial/hfsubsetr/blob/main/R/utils.R"
    click TEST "https://github.com/owp-spatial/hfsubsetr/tree/main/tests/"

    classDef user fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef test fill:#ffccff,stroke:#333,stroke-width:2px;
```
