# nipunbatra/ml-teaching architecture

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

- Interactive diagram: https://gitdiagram.com/nipunbatra/ml-teaching
- Repository: https://github.com/nipunbatra/ml-teaching

## Overview

##### Project type and purpose
- This is a content-centric repository for an educational Machine Learning course. It is not a runtime application but a _static site_ and _document build_ pipeline.
- Primary functions:
- Host and serve lecture slides (LaTeX → PDF)
- Host and serve interactive notebooks (Jupyter)
- Provide a static website via Quarto/Markdown
- Run quality-control scripts and CI checks

##### File structure
- Top-level directories:
- slides/navigation: .qmd files (index.qmd, slides.qmd, tutorials.qmd, notebooks.qmd)
- content topics: basics/, maths/, supervised/, neural-networks/, optimization/, unsupervised/, advanced/
- notebooks/: Jupyter .ipynb files
- scripts/: Python utilities for auditing, link-checking, metadata injection
- docs/: design and build documentation
- shared/: common assets (datasets, styles, fonts, notation)
- tests/: automated tests for link and path validation
- build-temp/: transient build artifacts
- Makefile and per-topic Makefiles
- CI workflows: .github/workflows/check-links.yml, publish.yml, validate.yml

##### README for insights
- Static site generation via Quarto (quarto preview)
- Slide build via Make (make in each folder)
- CI workflows for link validation, content audit, and publishing
- Modular, topic-based approach: each topic folder is self-contained

1. Content Sources
– Markdown/Quarto (.qmd) files (index.qmd, slides.qmd, tutorials.qmd…)
– LaTeX slide sources (.tex) in each topic’s slides/
– Jupyter notebooks (.ipynb)
– Assets (figures, PDFs, datasets) under each topic’s assets/ and shared/
2. Build & Processing Layer
– Makefiles (root Makefile, per-topic Makefile) orchestrating:
- LaTeX compilation → PDFs
- Quarto conversion → HTML site pages
– Python scripts (scripts/*.py) for: link checking, metadata tagging, content auditing
– compile_all_slides.py for batch slide generation
3. Continuous Integration / Deployment (CI/CD)
– GitHub Actions:
- check-links.yml: validate notebook & hyperlink integrity
- validate.yml: run tests/ suite
- publish.yml: deploy built site to GitHub Pages or other hosting
4. Test Suite
– tests/: unit tests to ensure correct paths, slide conventions, asset existence
5. Website / Hosting
– Quarto-generated static site
– Deployed to GitHub Pages (or netlify) using publish CI workflow
6. External Services / Integrations
– Google Colab support for notebooks
– CDN for shared fonts & styles
– GitHub repository hosting

b. Relationships and interactions
- Build outputs PDFs, HTML pages to an “Artifacts” node.
- CI/CD monitors code changes, runs builds & tests, then on success pushes artifacts to Website/Hosting.
- End users consume the Website & PDF slides; instructors clone the repo and run builds locally.

c. Architectural patterns & design principles
- Monorepo with _modular, topic-based_ separation
- _Declarative builds_ via Make + Quarto configuration
- _Separation of concerns_: content vs build vs tests vs deployment
- _Idempotent pipelines_: reproducible outputs from sources
- _CI-driven quality gates_ for links and conventions

d. Key technologies & libraries
- Quarto / Pandoc for static site generation
- LaTeX / Beamer for slide compilation
- Jupyter Notebook for interactive content
- Python scripts for automation and audit
- GitHub Actions for CI/CD
- SCSS/CSS for web styling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Sources
    subgraph "Content Sources" 
        direction TB
        QMD1["index.qmd"]:::content
        QMD2["slides.qmd"]:::content
        QMD3["tutorials.qmd"]:::content
        QMD4["notebooks.qmd"]:::content
        QMD5["courses.qmd"]:::content
        QMD6["assignments.qmd"]:::content
        QMD7["acknowledgments.qmd"]:::content

        subgraph "LaTeX Slide Sources"
            direction TB
            TEX1["basics/slides/*.tex"]:::content
            TEX2["maths/slides/*.tex"]:::content
            TEX3["supervised/slides/*.tex"]:::content
            TEX4["neural-networks/slides/*.tex"]:::content
            TEX5["optimization/slides/*.tex"]:::content
            TEX6["advanced/slides/*.tex"]:::content
            TEX7["unsupervised/slides/*.tex"]:::content
        end

        NB["Jupyter Notebooks"]:::content
        AssetsTopic["Topic Assets (*/assets/)"]:::content
        SharedAssets["Shared Assets"]:::content
    end

    %% Build & Processing Layer
    subgraph "Build & Processing" 
        direction TB
        MakeRoot["Makefile (root)"]:::build
        MakeTopics["Makefiles (per-topic)"]:::build
        QuartoCfg["_quarto.yml / _quarto-publish.yml / theme-config.yml"]:::build
        ScriptsAll["compile_all_slides.py / rebuild_all.sh"]:::build
        PyScripts["scripts/*.py"]:::build
    end

    %% Artifacts
    Artifacts["Build Artifacts\n(PDFs, HTML)"]:::artifact

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        T1["test_structure.py"]:::test
        T2["test_slide_conventions.py"]:::test
        T3["test_missing_pdfs.py"]:::test
        T4["test_notebook_paths.py"]:::test
        T5["test_notebook_conventions.py"]:::test
        T6["test_graphics_paths.py"]:::test
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        CI1["check-links.yml"]:::ci
        CI2["validate.yml"]:::ci
        CI3["publish.yml"]:::ci
    end

    %% Website / Hosting
    Website["Static Site / GitHub Pages"]:::hosting

    %% External Services
    subgraph "External Services"
        direction TB
        Colab["Google Colab"]:::external
        CDN["CDN (fonts & styles)"]:::external
        Repo["GitHub Repo"]:::external
    end

    %% Local Preview
    Preview["Local Preview\n(quarto preview / make)"]:::external

    %% Relationships
    QMD1 -->|"feeds into"| MakeRoot
    QMD2 --> MakeRoot
    QMD3 --> MakeRoot
    QMD4 --> MakeRoot
    QMD5 --> MakeRoot
    QMD6 --> MakeRoot
    QMD7 --> MakeRoot
    TEX1 --> MakeRoot
    TEX2 --> MakeRoot
    TEX3 --> MakeRoot
    TEX4 --> MakeRoot
    TEX5 --> MakeRoot
    TEX6 --> MakeRoot
    TEX7 --> MakeRoot
    NB --> PyScripts
    NB --> QuartoCfg
    AssetsTopic --> MakeRoot
    SharedAssets --> PyScripts

    MakeRoot -->|"orchestrates"| ScriptsAll
    MakeRoot --> QuartoCfg
    MakeTopics --> MakeRoot
    PyScripts --> Artifacts
    ScriptsAll --> Artifacts
    QuartoCfg --> Artifacts

    Artifacts ---|validate| T1
    Artifacts --- T2
    Artifacts --- T3
    Artifacts --- T4
    Artifacts --- T5
    Artifacts --- T6
    T1 --> Artifacts
    T2 --> Artifacts
    T3 --> Artifacts
    T4 --> Artifacts
    T5 --> Artifacts
    T6 --> Artifacts

    Repo -->|push events| CI1
    Repo --> CI2
    Repo --> CI3
    CI1 --> MakeRoot
    CI2 --> T1
    CI2 --> T2
    CI2 --> T3
    CI2 --> T4
    CI2 --> T5
    CI2 --> T6
    CI3 --> Artifacts
    CI3 --> Website

    Preview -.-> MakeRoot
    Colab --> NB
    CDN --> SharedAssets
    Repo --> QMD1

    Website -->|served to| Users["End Users / Students"]:::external
    Repo -->|cloned by| Instructors["Instructors"]:::external

    %% Click Events
    click QMD1 "https://github.com/nipunbatra/ml-teaching/blob/master/index.qmd"
    click QMD2 "https://github.com/nipunbatra/ml-teaching/blob/master/slides.qmd"
    click QMD3 "https://github.com/nipunbatra/ml-teaching/blob/master/tutorials.qmd"
    click QMD4 "https://github.com/nipunbatra/ml-teaching/blob/master/notebooks.qmd"
    click QMD5 "https://github.com/nipunbatra/ml-teaching/blob/master/courses.qmd"
    click QMD6 "https://github.com/nipunbatra/ml-teaching/blob/master/assignments.qmd"
    click QMD7 "https://github.com/nipunbatra/ml-teaching/blob/master/acknowledgments.qmd"
    click TEX1 "https://github.com/nipunbatra/ml-teaching/tree/master/basics/slides/"
    click TEX2 "https://github.com/nipunbatra/ml-teaching/tree/master/maths/slides/"
    click TEX3 "https://github.com/nipunbatra/ml-teaching/tree/master/supervised/slides/"
    click TEX4 "https://github.com/nipunbatra/ml-teaching/tree/master/neural-networks/slides/"
    click TEX5 "https://github.com/nipunbatra/ml-teaching/tree/master/optimization/slides/"
    click TEX6 "https://github.com/nipunbatra/ml-teaching/tree/master/advanced/slides/"
    click TEX7 "https://github.com/nipunbatra/ml-teaching/tree/master/unsupervised/slides/"
    click NB "https://github.com/nipunbatra/ml-teaching/tree/master/notebooks/"
    click AssetsTopic "https://github.com/nipunbatra/ml-teaching/tree/master/basics/assets/"
    click SharedAssets "https://github.com/nipunbatra/ml-teaching/tree/master/shared/styles/"

    %% Styles
    classDef content fill:#FFD580,stroke:#F39C12,color:#000
    classDef build fill:#AED6F1,stroke:#2471A3,color:#000
    classDef artifact fill:#ABEBC6,stroke:#27AE60,color:#000
    classDef test fill:#F5B7B1,stroke:#C0392B,color:#000
    classDef ci fill:#D7BDE2,stroke:#8E44AD,color:#000
    classDef hosting fill:#D5DBDB,stroke:#566573,color:#000
    classDef external fill:#F9E79F,stroke:#B7950B,color:#000
```
