# mlambardi/trunclcdist architecture

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

- Interactive diagram: https://gitdiagram.com/mlambardi/trunclcdist
- Repository: https://github.com/mlambardi/trunclcdist

## Overview

##### Project Type and Purpose
- This is an open-source R package providing non-uniform random variate generation for truncated log-concave distributions.
- The core functionality is a generic acceptance–rejection sampler (`rtruncLC()`) plus built-in “plugins” for common distributions (normal, Poisson, binomial, etc.) and the ability for users to register their own.

##### High-Level Components
A. User API Layer
- Public functions (in `R/`):
– `rtruncLC()` – central entry point
– Distribution-specific wrappers (`rtruncLCcontinuous.R`, `rtruncLCdiscrete.R`)
– Utility helpers (e.g. `truncLCdistoptions.R`, `inverseTransform.R`)
- Vignettes (in `vignettes/`) – usage guides, examples
B. Core Engine
- Acceptance–rejection algorithm (Devroye’s method) implemented in R
- Interfaces to PMF/PDF (`f`), CDF (`F`), log-derivative (`d log f`), mode (`m`)
C. Distribution Modules
- Built-in specs under `R/` (e.g. `"norm"`, `"pois"`, etc.)
- Extensibility point: user-supplied distribution definitions
D. Packaging & Documentation
- `DESCRIPTION`, `NAMESPACE` – CRAN metadata
- `man/` – Rd documentation files auto-generated from roxygen comments
- `inst/` – CITATION and REFERENCES.bib
E. Testing & CI
- `tests/testthat/` – unit tests for core functions
- `.github/ISSUE_TEMPLATE` and pull-request workflows – contribution templates
F. Build Workflow
- R CMD build/check, devtools, roxygen2, R Markdown (vignettes)

##### Relationships & Data Flow
1. User calls `rtruncLC(n, spec, …, a, b)`
2. API layer parses arguments, sets up truncation bounds
3. Core engine loads distribution module (built-in or user-provided)
4. Core invokes PMF/PDF, CDF, log-derivative, mode functions in a loop
5. Acceptance–rejection logic generates variates until count `n` met
6. Results returned to user environment
7. (Offline) Documentation and vignettes guide the user
8. Tests validate each component; CI runs on push/PR

##### Architectural Patterns & Principles
- Plugin/Strategy pattern: each distribution implements the same interface (`f`, `F`, `d log f`, `m`).
- Modular layering: clear separation between API, core engine, and distribution implementations.
- Convention-over-configuration: CRAN standard layout (`R/`, `man/`, `tests/`, `vignettes/`, `inst/`).

##### Technologies & Frameworks
- R language & base packages
- testthat for unit testing
- roxygen2 for documentation
- R Markdown for vignettes
- GitHub Actions (workflow templates under `.github/`)

##### Essential Elements Checklist
- Notes on architectural patterns (plugin strategy)
- External systems (R console, CRAN, GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["R Console"]:::external

    %% User API Layer
    subgraph "User API Layer"
        API["rtruncLC()"]:::runtime
        ContWrapper["rtruncLCcontinuous.R"]:::runtime
        DiscWrapper["rtruncLCdiscrete.R"]:::runtime
        Options["truncLCdistoptions.R"]:::runtime
        Inverse["inverseTransform.R"]:::runtime
    end

    %% Core Engine
    subgraph "Core Engine"
        Core["Acceptance–Rejection Sampler\n(Devroye's method)"]:::runtime
    end

    %% Distribution Modules
    subgraph "Distribution Modules"
        Continuous["Continuous Distributions\n(e.g. Normal)"]:::runtime
        Discrete["Discrete Distributions\n(e.g. Poisson)"]:::runtime
    end

    %% Packaging & Metadata
    subgraph "Packaging & Metadata"
        Description["DESCRIPTION"]:::pkg
        Namespace["NAMESPACE"]:::pkg
        Rbuildignore[".Rbuildignore"]:::pkg
        License["LICENSE.md"]:::pkg
        Readme["README.md"]:::pkg
        Citation["inst/CITATION"]:::pkg
        References["inst/REFERENCES.bib"]:::pkg
    end

    %% Documentation Outputs
    subgraph "Documentation Outputs"
        ManPages["man/*.Rd"]:::pkg
    end

    %% Vignettes
    subgraph "Vignettes"
        Vignettes["vignettes/*.Rmd"]:::dev
    end

    %% Testing & CI
    subgraph "Testing & CI"
        Tests["tests/testthat"]:::dev
        IssueTpl[".github/ISSUE_TEMPLATE"]:::dev
        PRTpl["pull_request_template.md"]:::dev
        GitHubActions["GitHub Actions"]:::external
    end

    %% CRAN External
    CRAN["CRAN"]:::external

    %% Data Flow
    User -->|calls| API
    API -->|invokes| Core
    Core -->|loads| Continuous
    Core -->|loads| Discrete
    Continuous -->|provides f, F, dlogf, m| Core
    Discrete -->|provides f, F, dlogf, m| Core
    Core -->|returns samples| User

    %% Packaging and Documentation Flow
    API & Core & Continuous & Discrete -->|roxygen2| ManPages
    API & Core -->|R CMD build/check| Vignettes
    ManPages & Vignettes -->|packaged with| Description
    Description & Namespace & Rbuildignore & License & Readme & Citation & References -->|submitted to| CRAN

    %% CI Flow
    GitHubActions -->|runs tests| Tests
    GitHubActions -->|builds docs| ManPages
    GitHubActions -->|validates| PRTpl & IssueTpl

    %% Click Events
    click API "https://github.com/mlambardi/trunclcdist/blob/main/R/rtruncLC.R"
    click ContWrapper "https://github.com/mlambardi/trunclcdist/blob/main/R/rtruncLCcontinuous.R"
    click DiscWrapper "https://github.com/mlambardi/trunclcdist/blob/main/R/rtruncLCdiscrete.R"
    click Options "https://github.com/mlambardi/trunclcdist/blob/main/R/truncLCdistoptions.R"
    click Inverse "https://github.com/mlambardi/trunclcdist/blob/main/R/inverseTransform.R"
    click Vignettes "https://github.com/mlambardi/trunclcdist/tree/main/vignettes/"
    click Tests "https://github.com/mlambardi/trunclcdist/tree/main/tests/testthat/"
    click IssueTpl "https://github.com/mlambardi/trunclcdist/tree/main/.github/ISSUE_TEMPLATE/"
    click PRTpl "https://github.com/mlambardi/trunclcdist/blob/main/pull_request_template.md"
    click Description "https://github.com/mlambardi/trunclcdist/tree/main/DESCRIPTION"
    click Namespace "https://github.com/mlambardi/trunclcdist/tree/main/NAMESPACE"
    click Rbuildignore "https://github.com/mlambardi/trunclcdist/blob/main/.Rbuildignore"
    click License "https://github.com/mlambardi/trunclcdist/blob/main/LICENSE.md"
    click Readme "https://github.com/mlambardi/trunclcdist/blob/main/README.md"
    click Citation "https://github.com/mlambardi/trunclcdist/tree/main/inst/CITATION"
    click References "https://github.com/mlambardi/trunclcdist/blob/main/inst/REFERENCES.bib"
    click ManPages "https://github.com/mlambardi/trunclcdist/tree/main/man/"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef dev fill:#90EE90,stroke:#333,stroke-width:1px
    classDef pkg fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFEFD5,stroke:#333,stroke-width:1px
```
