# saulo-chaves/probbreed architecture

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

- Interactive diagram: https://gitdiagram.com/saulo-chaves/probbreed
- Repository: https://github.com/saulo-chaves/probbreed

## Overview

##### Project type and purpose
- This is an open-source R package (“ProbBreed”) for Bayesian analysis of multi-environment trial data, implemented as an R library with embedded Stan models and C++ wrappers. It provides high-level R functions (`bayes_met`, `extr_outs`, `prob_sup`, `plot`) that internally invoke compiled Stan models via Rcpp/Rstan for inference, and then post-process results in R.

##### File structure
- Top-level:
- DESCRIPTION, NAMESPACE, LICENSE.md, NEWS.md, CRAN-SUBMISSION → R package metadata
- configure, configure.win → custom build scripts for Unix/Windows to locate Stan and Rcpp
- _pkgdown.yml, docs/, GitHub workflows → automated documentation and CI
- R/ directory → all user-facing R functions, S3 methods, and package initialization (`ProbBreed-package.R`, `bayes_met.R`, etc.)
- src/ directory → auto-generated C++ files (`stanExports_*.cc/.h`, `RcppExports.cpp`) and Makevars controlling compilation
- inst/stan/ → raw Stan model definitions (`*.stan`) plus include headers
- data/ → example datasets for maize and soy (`.rda`)
- man/ → Rd files and figure assets for help pages and vignettes

##### README for additional insights
- The README describes the main workflow:
a. `bayes_met()` fits one of nine Stan models to data → returns a `stanfit` object
b. `extr_outs()` extracts posterior summaries, variance components, PPCs → returns an “extr” object
c. `prob_sup()` computes marginal/pairwise probabilities of performance/stability → returns a “probsup” object
- External dependencies: Rcpp, rstan (Stan C++ compiler), devtools, pkgdown for docs
- CI workflows for R-CMD-check, pkgdown site build, coverage

##### Detailed capture of essential architectural elements
- That src/ files are auto-generated wrappers—not hand-written C++—to reflect the code generation pattern
- Configure scripts and Makevars to illustrate cross-platform build complexity
- Pkgdown site build and man/ directory as the documentation subsystem

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entities
    U["User"]:::external

    %% R API Layer
    subgraph "R API Layer"
        BM["bayes_met()"]:::Rcode
        EO["extr_outs()"]:::Rcode
        PS["prob_sup()"]:::Rcode
        PL["plot()"]:::Rcode
    end

    %% Data Layer
    subgraph "Data Layer"
        maize["maize.rda"]:::data
        soy["soy.rda"]:::data
    end

    %% C++ / Rcpp Interface
    subgraph "C++ / Rcpp Interface"
        CppExp["RcppExports.cpp"]:::cpp
        SEcc["stanExports_*.cc"]:::cpp
        SEh["stanExports_*.h"]:::cpp
    end

    %% Stan Model Engine
    subgraph "Stan Model Engine"
        I1["IBD1.stan"]:::cpp
        I2["RCBD1.stan"]:::cpp
        I3["entrymean1.stan"]:::cpp
        lic["license.stan"]:::cpp
        mh["stan_meta_header.hpp"]:::cpp
    end

    %% Build System
    subgraph "Build System"
        conf["configure"]:::build
        confw["configure.win"]:::build
        mv["Makevars"]:::build
        mvw["Makevars.win"]:::build
    end

    %% Documentation Layer
    subgraph "Documentation Layer"
        man["man/"]:::doc
        docs["docs/"]:::doc
        pkgdowncfg["_pkgdown.yml"]:::doc
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        w1["R-CMD-check.yaml"]:::ci
        w2["check-release.yaml"]:::ci
        w3["pkgdown.yaml"]:::ci
        w4["test-coverage.yaml"]:::ci
    end

    %% Connections
    U --> BM
    U --> EO
    U --> PS
    U --> PL

    maize --> BM
    soy --> BM

    BM --> CppExp
    CppExp --> I1
    CppExp --> I2
    CppExp --> I3
    SEcc --> I1
    SEcc --> I2
    SEcc --> I3
    SEh --> lic
    SEh --> mh

    I1 --> SEcc
    I2 --> SEcc
    I3 --> SEcc
    lic --> SEh
    mh --> SEh

    I1 --> CppExp
    I2 --> CppExp
    I3 --> CppExp

    CppExp --> BM

    BM --> EO
    BM --> PS
    EO --> PL
    PS --> PL
    PL --> U

    conf --> CppExp
    confw --> CppExp
    mv --> CppExp
    mvw --> CppExp
    conf --> I1
    confw --> I2

    w1 --> conf
    w1 --> docs
    w2 --> conf
    w3 --> pkgdowncfg
    w4 --> conf

    %% Click Events
    click BM "https://github.com/saulo-chaves/probbreed/blob/main/R/bayes_met.R"
    click EO "https://github.com/saulo-chaves/probbreed/blob/main/R/extr_outs.R"
    click PS "https://github.com/saulo-chaves/probbreed/blob/main/R/prob_sup.R"
    click PL "https://github.com/saulo-chaves/probbreed/blob/main/R/ProbBreed-package.R"
    click maize "https://github.com/saulo-chaves/probbreed/blob/main/data/maize.rda"
    click soy "https://github.com/saulo-chaves/probbreed/blob/main/data/soy.rda"
    click CppExp "https://github.com/saulo-chaves/probbreed/blob/main/src/RcppExports.cpp"
    click SEcc "https://github.com/saulo-chaves/probbreed/blob/main/src/stanExports_*.cc"
    click SEh "https://github.com/saulo-chaves/probbreed/blob/main/src/stanExports_*.h"
    click I1 "https://github.com/saulo-chaves/probbreed/blob/main/inst/stan/IBD1.stan"
    click I2 "https://github.com/saulo-chaves/probbreed/blob/main/inst/stan/RCBD1.stan"
    click I3 "https://github.com/saulo-chaves/probbreed/blob/main/inst/stan/entrymean1.stan"
    click lic "https://github.com/saulo-chaves/probbreed/blob/main/inst/stan/include/license.stan"
    click mh "https://github.com/saulo-chaves/probbreed/blob/main/inst/include/stan_meta_header.hpp"
    click conf "https://github.com/saulo-chaves/probbreed/tree/main/configure"
    click confw "https://github.com/saulo-chaves/probbreed/blob/main/configure.win"
    click mv "https://github.com/saulo-chaves/probbreed/tree/main/src/Makevars"
    click mvw "https://github.com/saulo-chaves/probbreed/blob/main/src/Makevars.win"
    click man "https://github.com/saulo-chaves/probbreed/tree/main/man/"
    click docs "https://github.com/saulo-chaves/probbreed/tree/main/docs/"
    click pkgdowncfg "https://github.com/saulo-chaves/probbreed/blob/main/_pkgdown.yml"
    click w1 "https://github.com/saulo-chaves/probbreed/blob/main/.github/workflows/R-CMD-check.yaml"
    click w2 "https://github.com/saulo-chaves/probbreed/blob/main/.github/workflows/check-release.yaml"
    click w3 "https://github.com/saulo-chaves/probbreed/blob/main/.github/workflows/pkgdown.yaml"
    click w4 "https://github.com/saulo-chaves/probbreed/blob/main/.github/workflows/test-coverage.yaml"

    %% Styles
    classDef Rcode fill:#cce5ff,stroke:#004085,color:#004085
    classDef cpp fill:#ffe5b4,stroke:#a75d00,color:#a75d00
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef doc fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef build fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
