# karbartolome/workshops architecture

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

- Interactive diagram: https://gitdiagram.com/karbartolome/workshops
- Repository: https://github.com/karbartolome/workshops

## Overview

##### Project Type and Purpose
- This is a **static site** / **slide deck** project built with **Quarto**, incorporating Jupyter notebooks and custom extensions.
- Its purpose is to author and publish interactive workshop slides (HTML) using .qmd and .ipynb sources, plus custom CSS/SASS and an extension for FontAwesome.

##### File Structure
- **Top-level items**
- README.md – project overview & setup instructions
- .gitignore – Git config
- 20240513-uba-calibracion/ – Quarto project directory
- testing/ – sandbox examples
- **Inside the Quarto folder**
- slides.qmd – primary Quarto markdown for slides
- ejemplo.ipynb – supplemental Jupyter notebook
- functions.py & df_german_credit.csv – Python code & data used in code chunks
- custom.scss – styling overrides
- slides.html – generated output
- requirements.txt – Python dependencies

##### README
- Describes the workshop title, link to published slides, and Conda/Jupyter kernel setup.

##### Main Components & Their Relationships
- **Authoring Environment**
- Developer’s IDE (VS Code / JupyterLab)
- Conda environment (quarto-env) with Python, Jupyter, Quarto CLI
- **Source Artifacts**
- .qmd files (slides.qmd, testing-stuff.qmd)
- .ipynb notebooks (ejemplo.ipynb)
- Python modules & data (functions.py, df_german_credit.csv)
- Custom assets (custom.scss, FontAwesome extension)
- **Build System**
- Quarto CLI (core)
- Pandoc under the hood
- Extension loader (fontawesome)
- **Output**
- slides.html (static HTML slide deck)
- ancillary assets (CSS, webfonts)
- **Hosting/Publishing**
- GitHub Pages (via karbartolome.github.io/workshops)

##### Architectural Patterns & Principles
- **Separation of concerns**:
- Content (QMD / IPYNB)
- Style (custom.scss, extension CSS)
- Code & data (functions.py, CSV)
- **Plugin architecture**: Quarto extensions loaded from `_extensions`
- **Static-site generator pipeline**: transform → render → publish

##### Putting It All Together
- Below, group **Source Files** (QMD, IPYNB, Python, CSV, custom.scss, extension).
- To the right of the build engine, show the **Generated HTML + Asset Bundle**.
- A small side-branch to represent the **testing/** folder feeding into a parallel “Experimental Slides” build.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Environment
    Developer["Developer Workstation\n(VS Code / JupyterLab)"]:::tool
    Env["Conda/Quarto Environment\n(Python 3.10, Quarto CLI, Jupyter Kernel)"]:::tool

    %% Source Artifacts
    subgraph "Source Artifacts"
        slides["Source Slides\n(slides.qmd)"]:::source
        notebook["Supplemental Notebook\n(ejemplo.ipynb)"]:::source
        code["Python Module\n(functions.py)"]:::source
        data["Sample Data\n(df_german_credit.csv)"]:::data
        bib["Citation Database\n(bib.bib)"]:::data
        styles["Custom Styles\n(custom.scss)"]:::source
        req["Env Spec\n(requirements.txt)"]:::source
        metadata["Project Metadata\n(README.md)"]:::source
        gitignore["Git Config\n(.gitignore)"]:::source
        subgraph "FontAwesome Extension"
            extDesc["Descriptor\n(_extension.yml)"]:::source
            extLogic["Extension Logic\n(fontawesome.lua)"]:::source
            extCSS["CSS Assets\n(all.css)"]:::source
            extFonts["Webfonts\n(webfonts/)"]:::source
        end
    end

    %% Build Engine
    subgraph "Quarto Build Engine"
        plugin["Extension Loader"]:::build
        engine["Quarto CLI + Pandoc"]:::build
    end

    %% Generated Output
    subgraph "Generated Output"
        output["HTML Slides\n(slides.html)"]:::output
        assets["Ancillary Assets\nCSS & Webfonts"]:::output
    end

    %% Hosting
    host["GitHub Pages\n(karbartolome.github.io/workshops)"]:::hosting

    %% Testing Branch
    testing["Experimental Slides Source\n(testing-stuff.qmd)"]:::source
    testBuild["Testing Build"]:::build
    testOutput["Experimental HTML"]:::output

    %% Connections
    Developer --> Env
    Env --> slides
    Env --> notebook
    Env --> code
    Env --> data
    Env --> bib
    Env --> styles
    Env --> req
    Env --> metadata
    Env --> gitignore

    slides --> engine
    notebook --> engine
    code --> engine
    data --> engine
    bib --> engine
    styles --> engine
    req --> engine

    extDesc --> plugin
    extLogic --> plugin
    extCSS --> plugin
    extFonts --> plugin
    plugin --> engine

    engine --> output
    engine --> assets
    output --> host
    assets --> host

    testing --> testBuild
    testBuild --> testOutput
    testOutput --> host

    %% Click Events
    click slides "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/slides.qmd"
    click notebook "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/ejemplo.ipynb"
    click code "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/functions.py"
    click data "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/df_german_credit.csv"
    click bib "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/bib.bib"
    click styles "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/custom.scss"
    click extDesc "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/_extensions/quarto-ext/fontawesome/_extension.yml"
    click extLogic "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/_extensions/quarto-ext/fontawesome/fontawesome.lua"
    click extCSS "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/_extensions/quarto-ext/fontawesome/assets/css/all.css"
    click extFonts "https://github.com/karbartolome/workshops/tree/main/20240513-uba-calibracion/_extensions/quarto-ext/fontawesome/assets/webfonts"
    click req "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/requirements.txt"
    click output "https://github.com/karbartolome/workshops/blob/main/20240513-uba-calibracion/slides.html"

    %% Styles
    classDef tool fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef source fill:#ABEBC6,stroke:#1E8449,color:#145A32;
    classDef data fill:#D5F5E3,stroke:#117A65,color:#0B5345;
    classDef build fill:#F9E79F,stroke:#B9770E,color:#7E5109;
    classDef output fill:#FAD7A0,stroke:#B9770E,color:#7E5109;
    classDef hosting fill:#D7BDE2,stroke:#76448A,color:#4A235A
```
