# lenarddome/psp architecture

> Architecture diagram of the GitHub repository lenarddome/psp, 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/lenarddome/psp
- Repository: https://github.com/lenarddome/psp

## Overview

##### Project type and purpose
- This is an R package (“psp”) that implements Parameter Space Partitioning MCMC for global model evaluation.
- It exposes a set of user-facing R functions (in R/*.R), backed by performance-critical routines in C++ (in src/*.cpp via Rcpp).
- The package includes manual documentation (man/*.Rd), vignettes/docs (docs/), and unit tests (tests/testthat).

##### File structure
- Top level
- DESCRIPTION, NAMESPACE, LICENSE: package metadata and exports
- README.md: overview, install instructions, philosophy
- .github/workflows/main.yml: CI pipeline on push/PR
- R/ directory
- RcppExports.R: glue code between R and C++
- Other .R files: R-only orchestration functions (e.g., psp_global.R)
- src/ directory
- RcppExports.cpp, pspGlobal.cpp: core algorithm implemented in C++
- man/ directory
- .Rd files for each exported function
- docs/ directory
- CHANGELOG.md, MASTERPLAN.md, logo, and site assets
- tests/testthat/
- test_psp_R.R, test_psp_cpp.R: unit tests for R and C++ paths

##### README for additional insights
- Confirms R + C++ hybrid architecture via Rcpp
- Mentions influences (Open Models Initiative, DEoptim) but no separate microservices
- Uses Google style guides for R and C++

a. Main components
1) User / Client (R console, scripts)
2) R API Layer (R/*.R)
3) Rcpp glue (RcppExports.R / .cpp)
4) C++ Core Engine (src/*.cpp)
5) Documentation subsystem (man/, docs/)
6) Test suite (tests/testthat)
7) CI/CD pipeline (GitHub Actions)
8) External dependencies (Rcpp, stats, CRAN ecosystem)
b. Relationships & data flow
- User invokes exported R functions → R API Layer
- R API calls RcppExports stubs → native C++ Core Engine
- C++ returns results → R data structures → user
- Test suite calls R API & C++ routines to validate outputs
- CI pipeline triggers build → run tests → R-CMD-CHECK → report status
- Documentation tools ingest R code (.Rd) and markdown (docs/) to build site/man pages
c. Architectural patterns & design principles
- Layered design: “Front” R interface separated from “back” C++ engine
- Rcpp bridging pattern for cross-language calls
- Clear separation of concerns: code vs. docs vs. tests vs. CI
- Conventions: manual Rd docs (no roxygen), Google style guides
d. Key technologies
- R (package infrastructure: DESCRIPTION, NAMESPACE)
- Rcpp (bindings between R and C++)
- C++ (performance-critical algorithms)
- testthat (unit testing)
- GitHub Actions (CI/CD)
- CRAN for distribution

##### Elements
- Blue: User-visible interface
- Green: Native code core
- Orange: Testing
- Purple: Documentation
- Grey: CI / infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User / Client Interface (README.md)"]:::user
    R_API["R API Layer\n(R/*.R)"]:::rapi
    subgraph "Rcpp Bridge"
        Rcpp_R["R/RcppExports.R"]:::bridge
        Rcpp_CPP["src/RcppExports.cpp"]:::bridge
    end
    CPP_Core["C++ Core Engine\n(src/pspGlobal.cpp)"]:::core
    Documentation_subsystem["Documentation Subsystem\n(man/, docs/)"]:::docs
    Test_Suite["Test Suite\n(tests/testthat)"]:::tests
    CI_Pipeline["CI/CD Pipeline\n(.github/workflows/main.yml)"]:::ci
    Metadata["Package Metadata & Dependencies\n(DESCRIPTION, NAMESPACE, LICENSE)"]:::infra

    User --> R_API
    R_API --> Rcpp_R
    Rcpp_R --> Rcpp_CPP
    Rcpp_CPP --> CPP_Core
    CPP_Core --> R_API

    CI_Pipeline --> Test_Suite
    CI_Pipeline --> Documentation_subsystem
    CI_Pipeline --> R_API

    Test_Suite --> R_API
    Test_Suite --> CPP_Core

    Documentation_subsystem --> User

    Metadata --> R_API
    Metadata --> Rcpp_R
    Metadata --> CPP_Core

    click User "https://github.com/lenarddome/psp/blob/main/README.md"
    click R_API "https://github.com/lenarddome/psp/blob/main/R/psp_global.R"
    click Rcpp_R "https://github.com/lenarddome/psp/blob/main/R/RcppExports.R"
    click Rcpp_CPP "https://github.com/lenarddome/psp/blob/main/src/RcppExports.cpp"
    click CPP_Core "https://github.com/lenarddome/psp/blob/main/src/pspGlobal.cpp"
    click Documentation_subsystem "https://github.com/lenarddome/psp/tree/main/man/"
    click Documentation_subsystem "https://github.com/lenarddome/psp/tree/main/docs/"
    click Test_Suite "https://github.com/lenarddome/psp/blob/main/tests/testthat/test_psp_R.R"
    click Test_Suite "https://github.com/lenarddome/psp/blob/main/tests/testthat/test_psp_cpp.R"
    click Test_Suite "https://github.com/lenarddome/psp/blob/main/tests/testthat.R"
    click CI_Pipeline "https://github.com/lenarddome/psp/blob/main/.github/workflows/main.yml"
    click Metadata "https://github.com/lenarddome/psp/tree/main/DESCRIPTION"
    click Metadata "https://github.com/lenarddome/psp/tree/main/NAMESPACE"
    click Metadata "https://github.com/lenarddome/psp/tree/main/LICENSE"

    classDef user fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef rapi fill:#B0E0E6,stroke:#000
    classDef bridge fill:#FFFACD,stroke:#000
    classDef core fill:#98FB98,stroke:#000
    classDef docs fill:#D8BFD8,stroke:#000
    classDef tests fill:#FFA500,stroke:#000
    classDef ci fill:#D3D3D3,stroke:#000
    classDef infra fill:#E0E0E0,stroke:#000
```
