# m-clark/book-of-models architecture

> Architecture diagram of the GitHub repository m-clark/book-of-models, 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/m-clark/book-of-models
- Repository: https://github.com/m-clark/book-of-models

## Overview

##### Project type and purpose
- This is a **Quarto-based book** (“Models Demystified”) with intermixed R Markdown (.qmd), Jupyter notebooks (.ipynb), raw data, code demos, LaTeX templates and CSS.
- It generates a **static documentation website** (under /docs) and PDF via LaTeX. It combines tutorial content, data‐science demos (R & Python), and figures into a cohesive online book.

##### Main components
a. **Content sources**
- Quarto pages: .qmd files at repo root (e.g., introduction.qmd, machine_learning.qmd, etc.)
- Jupyter notebooks in chapter-notebooks and various ml/linear_models directories
- Markdown includes (.md), LaTeX snippets (latex/*.tex), CSS/Sass (css/style.scss)
b. **Data assets**
- /data (CSV, RData, pickle models), /ml/data, /linear_models/data, etc.
c. **Code libraries**
- R scripts: functions/utils.r, estimation/functions/*.R, ml/*.R, linear_models/functions/*.R
- Python support: setup.py, environment.yml, chapter-notebooks/python_chapter_notebooks/requirements.txt
d. **Build system**
- Quarto CLI invokes Pandoc, executes code chunks in R/Python, compiles Sass to CSS, uses LaTeX (krantz.cls) for PDF
e. **Output & deployment**
- Static HTML under /docs (GitHub Pages), PDF via Quarto’s LaTeX engine
- CI via .github workflows (issue templates present)

##### Relationships & interactions
- **Author/Contributor** edits source (.qmd, .ipynb, code, data).
- **Quarto build** reads _quarto.yml & quarto.yml, spins up R/Python kernels, runs code chunks in notebooks & .qmd, loads data assets, applies CSS/LaTeX templates.
- **Pandoc** converts executed notebooks & markdown into HTML (and PDF).
- **Assets** (img/, css/, latex/) are bundled.
- Final **/docs** folder is pushed to GitHub Pages for hosting.

##### Architectural patterns & design principles
- **Content–Build–Deploy pipeline** (a linear flow from source to static output)
- **Polyglot execution**: R and Python both supported, each via its own kernel
- **Modular content**: chapters living as independent units, reusable code/functions
- **Data as code inputs**: clear separation of data folder and processing scripts

##### Relevant technologies & frameworks
- Quarto (and underlying Pandoc)
- R (knitr, quarto-r, LaTeX via krantz.cls)
- Python (Jupyter, PyQuarto, dependencies in requirements.txt)
- Sass (via css/style.scss)
- GitHub Pages for static hosting
- CI/CD via .github workflows (implicit)

##### Final checklist
- Callouts for critical config files (_quarto.yml, environment.yml, setup.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Layer
    subgraph "Content Layer" 
        direction TB
        CP1["index.qmd"]:::content
        CP2["introduction.qmd"]:::content
        CP3["data.qmd"]:::content
        CP4["machine_learning.qmd"]:::content
        CP5["linear_models.qmd"]:::content
        CP6["generalized_linear_models.qmd"]:::content
        CP7["estimation.qmd"]:::content
        CP8["causal.qmd"]:::content
        CP9["models.qmd"]:::content
        CP10["more_models.qmd"]:::content
        CP11["ml_common_models.qmd"]:::content
        CP12["ml_more.qmd"]:::content
        CP13["pyr.qmd"]:::content
        CP14["uncertainty.qmd"]:::content
        CP15["understanding_models.qmd"]:::content
        CP16["understanding_features.qmd"]:::content
        CP17["matrix_operations.qmd"]:::content
        CP18["steps.qmd"]:::content
        CP19["conclusion.qmd"]:::content
        CP20["acknowledgments.qmd"]:::content
        CP21["abstracts.qmd"]:::content
        CP22["dataset_descriptions.qmd"]:::content
        CP23["danger_zone.qmd"]:::content
        CP24["appendix_placeholder.qmd"]:::content
        NB1["Python Notebooks (.ipynb)"]:::content
        NB2["R Notebooks (.qmd)"]:::content
        INC["cuts/*.qmd"]:::content
        LAT["LaTeX Templates"]:::content
        CSS["css/style.scss"]:::content
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        D1["data/*"]:::data
        D2["ml/data/*"]:::data
        D3["linear_models/data/*"]:::data
        D4["estimation/data/*"]:::data
    end

    %% Execution Layer
    subgraph "Execution Layer"
        direction TB
        R["R Kernel"]:::exec
        PY["Python Kernel"]:::exec
        SASS["Sass Compiler"]:::exec
        TEX["LaTeX Engine (krantz.cls)"]:::exec
    end

    %% Build Orchestration
    subgraph "Build Orchestration"
        direction TB
        QCLI["Quarto CLI"]:::orchestration
        PANDOC["Pandoc"]:::orchestration
    end

    %% Output
    subgraph "Output"
        direction TB
        HTML["docs/ (HTML)"]:::output
        PDF["PDF via LaTeX"]:::output
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        GH["GitHub Pages"]:::deployment
        CI[".github Workflows"]:::deployment
    end

    %% Relationships
    CP1 -->|reads| QCLI
    CP2 -->|reads| QCLI
    CP3 -->|reads| QCLI
    CP4 -->|reads| QCLI
    CP5 -->|reads| QCLI
    CP6 -->|reads| QCLI
    CP7 -->|reads| QCLI
    CP8 -->|reads| QCLI
    CP9 -->|reads| QCLI
    CP10 -->|reads| QCLI
    CP11 -->|reads| QCLI
    CP12 -->|reads| QCLI
    CP13 -->|reads| QCLI
    CP14 -->|reads| QCLI
    CP15 -->|reads| QCLI
    CP16 -->|reads| QCLI
    CP17 -->|reads| QCLI
    CP18 -->|reads| QCLI
    CP19 -->|reads| QCLI
    CP20 -->|reads| QCLI
    CP21 -->|reads| QCLI
    CP22 -->|reads| QCLI
    CP23 -->|reads| QCLI
    CP24 -->|reads| QCLI
    NB1 -->|executes code chunks| QCLI
    NB2 -->|executes code chunks| QCLI
    INC -->|includes| QCLI
    LAT -->|templates| QCLI
    CSS -->|compiles| SASS
    D1 -->|loads data| QCLI
    D2 -->|loads data| QCLI
    D3 -->|loads data| QCLI
    D4 -->|loads data| QCLI

    QCLI -->|spawns| R
    QCLI -->|spawns| PY
    QCLI -->|invokes| SASS
    QCLI -->|invokes| TEX
    QCLI -->|renders markdown| PANDOC

    PANDOC -->|generates| HTML
    PANDOC -->|generates| PDF

    HTML -->|deployed to| GH
    PDF -->|artifact| CI
    GH -->|hosts| HTML

    %% Click Events
    click CP1 "https://github.com/m-clark/book-of-models/blob/main/index.qmd"
    click CP2 "https://github.com/m-clark/book-of-models/blob/main/introduction.qmd"
    click CP3 "https://github.com/m-clark/book-of-models/blob/main/data.qmd"
    click CP4 "https://github.com/m-clark/book-of-models/blob/main/machine_learning.qmd"
    click CP5 "https://github.com/m-clark/book-of-models/blob/main/linear_models.qmd"
    click CP6 "https://github.com/m-clark/book-of-models/blob/main/generalized_linear_models.qmd"
    click CP7 "https://github.com/m-clark/book-of-models/blob/main/estimation.qmd"
    click CP8 "https://github.com/m-clark/book-of-models/blob/main/causal.qmd"
    click CP9 "https://github.com/m-clark/book-of-models/blob/main/models.qmd"
    click CP10 "https://github.com/m-clark/book-of-models/blob/main/more_models.qmd"
    click CP11 "https://github.com/m-clark/book-of-models/blob/main/ml_common_models.qmd"
    click CP12 "https://github.com/m-clark/book-of-models/blob/main/ml_more.qmd"
    click CP13 "https://github.com/m-clark/book-of-models/blob/main/pyr.qmd"
    click CP14 "https://github.com/m-clark/book-of-models/blob/main/uncertainty.qmd"
    click CP15 "https://github.com/m-clark/book-of-models/blob/main/understanding_models.qmd"
    click CP16 "https://github.com/m-clark/book-of-models/blob/main/understanding_features.qmd"
    click CP17 "https://github.com/m-clark/book-of-models/blob/main/matrix_operations.qmd"
    click CP18 "https://github.com/m-clark/book-of-models/blob/main/steps.qmd"
    click CP19 "https://github.com/m-clark/book-of-models/blob/main/conclusion.qmd"
    click CP20 "https://github.com/m-clark/book-of-models/blob/main/acknowledgments.qmd"
    click CP21 "https://github.com/m-clark/book-of-models/blob/main/abstracts.qmd"
    click CP22 "https://github.com/m-clark/book-of-models/blob/main/dataset_descriptions.qmd"
    click CP23 "https://github.com/m-clark/book-of-models/blob/main/danger_zone.qmd"
    click CP24 "https://github.com/m-clark/book-of-models/blob/main/appendix_placeholder.qmd"
    click NB1 "https://github.com/m-clark/book-of-models/tree/main/chapter-notebooks/python_chapter_notebooks/"
    click NB2 "https://github.com/m-clark/book-of-models/tree/main/chapter-notebooks/r_chapter_notebooks/"
    click INC "https://github.com/m-clark/book-of-models/tree/main/cuts/"
    click LAT "https://github.com/m-clark/book-of-models/blob/main/latex/preamble.tex"
    click CSS "https://github.com/m-clark/book-of-models/blob/main/css/style.scss"

    %% Styles
    classDef content fill:#f9f,stroke:#333,stroke-width:1px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px
    classDef exec fill:#bfb,stroke:#333,stroke-width:1px
    classDef orchestration fill:#fbf,stroke:#333,stroke-width:1px
    classDef output fill:#ffb,stroke:#333,stroke-width:1px
    classDef deployment fill:#fbb,stroke:#333,stroke-width:1px
```
