# rspatial/terra architecture

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

- Interactive diagram: https://gitdiagram.com/rspatial/terra
- Repository: https://github.com/rspatial/terra

## Overview

This project is the “terra” package for R, which is designed for spatial data analysis. The package replaces “raster” and aims to provide a simpler, faster, and more powerful tool for handling spatial data. The package architecture reflects several layers including an R API layer, native C++ implementations for performance‐critical operations, command-line utilities, and extensive testing and documentation infrastructure.

##### Main Components
- User / R Interface Layer:
– Represent the R scripts (from the “R” directory) that provide the user-facing functions.
– Include the “app.R” and other function files that users interact with, as well as the auto-generated R wrappers (e.g. RcppExports.R).

- Native Engine / C++ Layer:
– Represent the “src” directory. This layer contains numerous C++ files (e.g. raster, vector, geometry, GDAL integration, spatial processing functions) which optimize performance and handle heavy computations.
– Show the use of “Rcpp” to bridge between the R-layer and the C++ engine.

- Command-Line and Auxiliary Tools:
– Represent the “cmdapp” directory that contains C++ command-line utilities for compilation, testing, and possibly demonstration.

- Documentation and Testing:
– Include the “man” directory for manual pages and help files.
– Include “inst/tinytest” and “tests” directories as components responsible for testing and ensuring quality.
– Represent the “README.md” and related configuration files (e.g. _pkgdown.yml) that help generate online documentation.

- Build, CI/CD, and Packaging Infrastructure:
– Represent workflows and configuration files in the “.github” directory (GitHub actions for continuous integration such as rcmdcheck).
– Include build scripts (like “configure”, “Makevars.in”).

- External Dependencies:
– Represent external libraries and system dependencies like GDAL, GEOS, PROJ, and others used by the C++ layer.

##### Defining Relationships & Interactions
- Command-line tools (cmdapp) as a separate interaction point that also communicates with the native engine.
- That the testing infrastructure (tinytest scripts) and documentation are “side components” ensuring correctness and maintainability.
- Interactions with CI/CD pipelines (through GitHub Actions) that automatically trigger tests and package checks during deployment.

##### Highlighting Architectural Patterns & Design Principles
- The layered architecture pattern is evident, with a clear separation between high-level R functions and low-level C++ implementations.
- The use of wrappers (RcppExports and similar files) indicates a bridging design pattern where Rcpp acts as the interface between R and C++.
- The modular organization also supports extensibility, enabling developers to add new spatial operations without affecting the whole framework.
- The inclusion of extensive testing and documentation infrastructure demonstrates adherence to best software engineering practices.

##### Technologies, Frameworks, and Libraries
- R, which serves as the primary interface.
- C++ for performance-critical functions.
- Rcpp, bridging R and C++.
- External geospatial libraries like GDAL, GEOS, and PROJ (implied from the build notes in the README).
- GitHub Actions for CI/CD.
- pkgdown for generating package websites from the documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User / R Interface Layer"
        RAPI["R API (terra R functions)"]:::rLayer
    end

    subgraph "Native Engine / C++ Layer"
        CPP["C++ Engine (src)"]:::cppLayer
    end

    subgraph "Command-Line Utilities"
        CMD["Command-Line Utilities (cmdapp)"]:::cmdLayer
    end

    subgraph "Documentation & Testing"
        DOC["Documentation (man, README, _pkgdown)"]:::docLayer
        TEST["Testing (inst/tinytest, tests)"]:::testLayer
    end

    subgraph "CI/CD and Build Infrastructure"
        CICD["CI/CD & Build (.github, configure, Makevars.in)"]:::ciLayer
    end

    subgraph "External Dependencies"
        EXT["GDAL, GEOS, PROJ, etc."]:::extLayer
    end

    RAPI -->|"calls_via_Rcpp"| CPP
    CMD -->|"invokes"| CPP
    CICD -->|"triggers_tests"| TEST
    CICD -->|"updates_docs"| DOC
    CPP -->|"uses"| EXT

    click RAPI "https://github.com/rspatial/terra/tree/master/R/"
    click CPP "https://github.com/rspatial/terra/tree/master/src/"
    click CMD "https://github.com/rspatial/terra/tree/master/cmdapp/"
    click DOC "https://github.com/rspatial/terra/tree/master/man/"
    click TEST "https://github.com/rspatial/terra/tree/master/inst/tinytest/"
    click CICD "https://github.com/rspatial/terra/tree/master/.github/"

    classDef rLayer fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef cppLayer fill:#F5B041,stroke:#D35400,stroke-width:2px;
    classDef cmdLayer fill:#7FB3D5,stroke:#2471A3,stroke-width:2px;
    classDef docLayer fill:#82E0AA,stroke:#27AE60,stroke-width:2px;
    classDef testLayer fill:#58D68D,stroke:#229954,stroke-width:2px;
    classDef ciLayer fill:#BB8FCE,stroke:#8E44AD,stroke-width:2px;
    classDef extLayer fill:#F1948A,stroke:#C0392B,stroke-width:2px;
```
