# genentech/bayeserbook architecture

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

## Overview

This project is a book that serves as a hands‐on tutorial on exposure–response analysis using Bayesian methods. It’s built entirely within the R ecosystem and uses Quarto for authoring and publishing, leveraging the BayesERtools package along with related Bayesian modeling packages like rstanarm and rstanemax. The project not only houses the source content (in the form of .qmd notebooks and R scripts) but also retains execution outputs (in the “_freeze” and “output” directories) and includes continuous integration workflows for publishing updates.

##### Main components
- Source Repository & Project Management:
- Git repository containing the full file tree, including the R project file (BayesERbook.Rproj), build/configuration files (.github/workflows, .gitignore, quarto.yml), and style resources (custom.scss).
- Content & Analysis Notebooks:
- “notebook” directory with two subdivisions: “binary” and “emax”. Each contains several .qmd (Quarto) files illustrating analytical workflows (e.g., basic_workflow, simulation, model_diagnostics).
- Execution & Freeze Artifacts:
- The “_freeze” directory contains executed notebook versions including rendered outputs (HTML results, figure directories, etc.), ensuring reproducibility.
- R Scripts & Modules:
- The “R” directory (e.g., R/cli_color_text.R) for utility functions and additional code behind the scenes.
- Data Handling:
- “data” directory with example CSV files that serve as inputs for the exposure–response analyses.
- Output & Artifacts:
- “output” directory holding serialized model objects and computed metrics (RDS files) generated during the analytical processes.
- Continuous Integration & Deployment:
- The “.github” directory (notably the publish.yml workflow) demonstrates how the project is built, tested, and published automatically.
- External Dependencies:
- The project relies on external packages (BayesERtools, rstanarm, and rstanemax) as well as the Quarto rendering engine that converts .qmd files into a polished website or book.

##### Relationships and interactions
- Data Flow:
- How the raw data (from the “data” folder) is ingested by R scripts and notebooks.
- How notebooks consume these inputs, perform Bayesian model fitting (using rstanarm/rstanemax via BayesERtools), and finally generate output summaries (RDS files in “output”) and rendered HTML (in “_freeze”).
- Build & Execution Pipeline:
- Transformation of source notebooks (.qmd files) through the Quarto build process (guided by quarto.yml) to produce the final published book.
- That CI/CD (from GitHub workflows) is triggered upon commits, ensuring that code style (via usethis::use_tidy_style) and publishing are automatically enforced.
- External Services:
- Optionally denote the links to external documentation sites (BayesERtools website and GitHub repo) and the integration with R package repositories.

##### Important architectural patterns and design principles
- Separation of concerns is evident – the project clearly segments code (in the “R” folder), notebooks (in “notebook”), and data/results.
- Reproducibility is enforced with “freeze” folders that capture execution state and output.
- Continuous integration (“.github/workflows”) is used to maintain code quality and automate the publishing process.
- Modularity is supported via discrete notebooks for different analyses, enabling easy extension and reuse.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Source Code & Resources
    subgraph "Source Code & Resources"
        Repo["Source Repository & Project Management"]:::repo
        RScripts["R Scripts & Modules"]:::processing
        DataInputs["Data Inputs"]:::static
        NotebooksBinary["Notebooks (Binary Workflows)"]:::processing
        NotebooksEmax["Notebooks (Emax Workflows)"]:::processing
    end

    %% Subgraph: Build & Execution Pipeline
    subgraph "Build & Execution Pipeline"
        CI["CI/CD Pipeline"]:::ci
        Quarto["Quarto Build Engine"]:::processing
        Freeze["Execution & Freeze Artifacts"]:::output
        OutputArtifacts["Output Artifacts"]:::output
        Published["Published Book/Website"]:::published
    end

    %% Subgraph: External Dependencies
    subgraph "External Dependencies"
        External["External Dependencies (BayesERtools, rstanarm, rstanemax, Quarto)"]:::external
    end

    %% Data Flow & Interactions
    DataInputs -->|"ingested_by"| NotebooksBinary
    DataInputs -->|"ingested_by"| NotebooksEmax

    RScripts -->|"feeds"| NotebooksBinary
    RScripts -->|"feeds"| NotebooksEmax

    External -->|"supports"| NotebooksBinary
    External -->|"supports"| NotebooksEmax
    External -->|"supports"| Quarto

    NotebooksBinary -->|"executes to"| Freeze
    NotebooksEmax -->|"executes to"| Freeze

    NotebooksBinary -->|"generates"| OutputArtifacts
    NotebooksEmax -->|"generates"| OutputArtifacts

    NotebooksBinary -->|"renders via"| Quarto
    NotebooksEmax -->|"renders via"| Quarto

    Quarto -->|"produces"| Published

    Repo -->|"triggers"| CI
    CI -->|"initiates"| Quarto
    CI -->|"publishes to"| Published

    %% Additional connections from repository to components
    Repo -->|"contains"| RScripts
    Repo -->|"contains"| DataInputs
    Repo -->|"contains"| NotebooksBinary
    Repo -->|"contains"| NotebooksEmax

    %% Click Events
    click Repo "https://github.com/genentech/bayeserbook/blob/main/BayesERbook.Rproj"
    click NotebooksBinary "https://github.com/genentech/bayeserbook/blob/main/notebook/binary/basic_workflow.qmd"
    click NotebooksEmax "https://github.com/genentech/bayeserbook/blob/main/notebook/emax/basic_workflow.qmd"
    click RScripts "https://github.com/genentech/bayeserbook/blob/main/R/cli_color_text.R"
    click DataInputs "https://github.com/genentech/bayeserbook/tree/main/data"
    click Freeze "https://github.com/genentech/bayeserbook/tree/main/_freeze"
    click OutputArtifacts "https://github.com/genentech/bayeserbook/tree/main/output"
    click CI "https://github.com/genentech/bayeserbook/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef repo fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef processing fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef static fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef output fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef ci fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef published fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#fefefe,stroke:#6c757d,stroke-width:2px;
```
