# nipunbatra/stt-ai-teaching architecture

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

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

## Overview

1. **What this repository is**
   - This is a **course-materials monorepo** for CS 203, not a runtime application.
   - Its main job is to **author, generate, and publish** slides, labs, demos, diagrams, and reference artifacts for a semester-long AI software engineering course.

2. **Primary boundary: source content vs generated output**
   - The repo cleanly separates **authoring sources** from **rendered deliverables**.
   - Source lives in places like `slides/`, `labs/`, `lecture-demos/`, `diagrams/`, `diagram-generators/`, `datasets/`, and `prompts/`.
   - Generated or published artifacts live in `html/`, `pdf/`, `backup/`, `theme-previews/`, and some checked-in notebook HTML outputs.

3. **Course website / publication layer**
   - The top-level site is driven by **Quarto**: `index.qmd`, `_quarto.yml`, `themes.qmd`, `site_libs/`, and the GitHub Actions workflow `.github/workflows/quarto-publish.yml`.
   - This layer produces the public course website and ties together the various lecture/lab assets into a browsable static site.
   - Hosting appears to be via **GitHub Pages** or a similar static publish flow.

4. **Slides subsystem**
   - Weekly lecture slides are authored as markdown in `slides/`.
   - Rendered slide outputs are committed under `html/` and `pdf/`.
   - The repo also keeps theme-related artifacts such as `custom.scss`, `slides/iitgn-modern.css`, `theme-previews/`, and build helpers like `build-all-themes.sh`.
   - Slide assets include figures and generated images under `slides/images/` and `slides/audio/`.

5. **Lab subsystem**
   - Labs are delivered as notebooks and rendered HTML in `labs/`.
   - Each week’s lab is a self-contained teaching artifact, usually pairing hands-on code with a pre-rendered HTML version for viewing.
   - This subsystem is distinct from slides: labs are interactive/experimental, while slides are presentation-oriented.

6. **Lecture demos / executable examples**
   - `lecture-demos/` holds week-specific runnable scripts, notebooks, and small app examples.
   - These demos illustrate APIs, validation, labeling, augmentation, Docker, web apps, drift, profiling, and CI/CD concepts.
   - They often depend on local sample data in subfolders like `lecture-demos/week02/data/` or generated model files such as the Docker demo’s `spam_model.pkl`.

7. **Diagram generation pipeline**
   - There are two related diagram areas: `diagram-generators/` and `diagrams/`.
   - `diagram-generators/` contains standalone Python scripts and some `.d2` / `.bob` files for producing explanatory figures.
   - `diagrams/weekXX/` contains more curated week-specific drawing scripts, and `diagrams/figures/` stores outputs.
   - These diagrams feed the teaching materials rather than any application runtime.

8. **Dataset and annotation assets**
   - `datasets/week03/` and `data/` provide example data used in labs and demos.
   - The week 3 dataset subtree includes subdomains like image classification, object detection, text classification, and NER, along with Label Studio configs and JSON manifests.
   - `data/movies.db` looks like a local teaching database used in examples or exercises.
   - This is a support layer for data-centric teaching workflows, not a production datastore.

9. **Assignments and guided exercises**
   - `assignments/` and `lab01/` contain course exercises and teaching guides.
   - These are small pedagogical units designed to reinforce the weekly topics.
   - They sit alongside the larger slide/lab/demo materials rather than forming a separate application.

10. **Archive and preservation layer**
   - `backup/` preserves older rendered slide versions in HTML, PDF, and source markdown form.
   - `outputs/` and some checked-in notebook outputs similarly store generated results for reference.
   - This suggests a “publish, then archive” workflow where historical versions are retained for continuity.

11. **Automation and build orchestration**
   - `Makefile` is the main local build entry point.
   - `build-all-themes.sh` and `generate-theme-previews.sh` support bulk rendering and theme comparison.
   - `package.json` / `package-lock.json` and the checked-in `site_libs/` indicate a front-end/rendering toolchain is also part of the build environment.

12. **External tool ecosystem reflected in the content**
   - The teaching materials reference and demonstrate tools such as Quarto/Reveal.js, Marp-style slide rendering, GitHub Actions, Docker, FastAPI, Streamlit, Gradio, Label Studio, and various ML libraries.
   - These tools matter architecturally because they explain why the repo has multiple output formats and many generated assets.
   - The repo is organized around **teaching workflows** that move from raw examples to rendered course deliverables.

13. **End-to-end data flow**
   - Typical flow: source markdown/notebooks/scripts/data → diagrams and generated figures → rendered slides/labs/demo pages → published static site.
   - The course website aggregates the outputs, while the generated artifacts remain versioned in the repository for reproducibility and archival access.

14. **How to diagram it**
   - A useful architecture diagram would center on three source domains: **content authoring**, **asset/data generation**, and **publication**.
   - Show `slides/`, `labs/`, `lecture-demos/`, `diagram-generators/`, and `datasets/` feeding into `html/`, `pdf/`, and the Quarto-published site, with `backup/` as an archival sink.

Main entry points: [`Makefile`](https://github.com/nipunbatra/stt-ai-teaching/tree/master/Makefile) (Build tools), [`index.qmd`](https://github.com/nipunbatra/stt-ai-teaching/blob/master/index.qmd) (Course site), [`slides/week09-git-lecture.md`](https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/week09-git-lecture.md) (Slides source), [`html/week10-web-apps-lecture.html`](https://github.com/nipunbatra/stt-ai-teaching/blob/master/html/week10-web-apps-lecture.html) (HTML output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring"]
  node_slides_src["Slides source<br/>lecture markdown"]
  node_labs_src["Labs"]
  node_demos_src["Lecture demos<br/>example code<br/>[app.py]"]
  node_assignments["Assignments<br/>exercise markdown"]
  node_lab01["Lab guide<br/>exercise guide"]
end

subgraph group_generation["Generation"]
  node_slides_theme["Theme assets<br/>slide theme<br/>[iitgn-modern.css]"]
  node_slides_media["Slide media<br/>media assets"]
  node_diagrams_gen["Diagram generators<br/>figure scripts<br/>[llm_pipeline.py]"]
  node_diagrams_curated["Week diagrams<br/>diagram scripts"]
end

subgraph group_publication["Publication"]
  node_site["Course site<br/>quarto site<br/>[index.qmd]"]
  node_quarto_config["Quarto config<br/>site config<br/>[_quarto.yml]"]
  node_publish_workflow["Publish workflow<br/>ci workflow<br/>[quarto-publish.yml]"]
  node_html_out["HTML output<br/>rendered html"]
  node_pdf_out["PDF output<br/>rendered pdf"]
  node_backup["Archive<br/>preserved builds"]
  node_site_libs["Site libs<br/>frontend assets<br/>[reveal.js]"]
end

subgraph group_support["Support"]
  node_datasets["Datasets<br/>teaching data<br/>[create_datasets.py]"]
  node_shared_data[("Local data<br/>sample data<br/>[movies.db]")]
  node_prompts["Prompts<br/>prompt bank"]
  node_build_tools["Build tools<br/>make and scripts"]
end

node_build_tools -->|"build"| node_slides_src
node_build_tools -->|"build"| node_labs_src
node_build_tools -->|"generate"| node_diagrams_gen
node_build_tools -->|"generate"| node_diagrams_curated
node_build_tools -->|"render"| node_html_out
node_build_tools -->|"render"| node_pdf_out
node_slides_src -->|"uses"| node_slides_theme
node_slides_src -->|"uses"| node_slides_media
node_diagrams_gen -->|"produces"| node_slides_media
node_diagrams_curated -->|"produces"| node_slides_media
node_datasets -->|"supports"| node_labs_src
node_shared_data -->|"supports"| node_demos_src
node_prompts -->|"informs"| node_site
node_site_libs -->|"enables"| node_site
node_quarto_config -->|"configures"| node_site
node_publish_workflow -->|"publishes"| node_site
node_html_out -->|"served by"| node_site
node_pdf_out -->|"linked by"| node_site
node_backup -.->|"archives"| node_html_out
node_backup -.->|"archives"| node_pdf_out
node_assignments -->|"published on"| node_site
node_lab01 -->|"extends"| node_labs_src

click node_site "https://github.com/nipunbatra/stt-ai-teaching/blob/master/index.qmd"
click node_quarto_config "https://github.com/nipunbatra/stt-ai-teaching/blob/master/_quarto.yml"
click node_publish_workflow "https://github.com/nipunbatra/stt-ai-teaching/blob/master/.github/workflows/quarto-publish.yml"
click node_slides_src "https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/week09-git-lecture.md"
click node_slides_theme "https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/iitgn-modern.css"
click node_slides_media "https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/images/week10/generate_concept_drift_cases.py"
click node_labs_src "https://github.com/nipunbatra/stt-ai-teaching/blob/master/labs/week01-data-collection-lab.ipynb"
click node_demos_src "https://github.com/nipunbatra/stt-ai-teaching/blob/master/lecture-demos/week10/web-apps/4-fastapi/app.py"
click node_diagrams_gen "https://github.com/nipunbatra/stt-ai-teaching/blob/master/diagram-generators/llm_pipeline.py"
click node_diagrams_curated "https://github.com/nipunbatra/stt-ai-teaching/blob/master/diagrams/week03/labeling_workflow.py"
click node_datasets "https://github.com/nipunbatra/stt-ai-teaching/blob/master/datasets/week03/create_datasets.py"
click node_shared_data "https://github.com/nipunbatra/stt-ai-teaching/blob/master/data/movies.db"
click node_prompts "https://github.com/nipunbatra/stt-ai-teaching/blob/master/prompts/docker_concepts.txt"
click node_assignments "https://github.com/nipunbatra/stt-ai-teaching/blob/master/assignments/week1-assignment.md"
click node_lab01 "https://github.com/nipunbatra/stt-ai-teaching/blob/master/lab01/cpcb_api_teaching_guide.md"
click node_html_out "https://github.com/nipunbatra/stt-ai-teaching/blob/master/html/week10-web-apps-lecture.html"
click node_pdf_out "https://github.com/nipunbatra/stt-ai-teaching/blob/master/pdf/week10-web-apps-lecture.pdf"
click node_backup "https://github.com/nipunbatra/stt-ai-teaching/blob/master/backup/html/week14-rag-vector-db-lecture.html"
click node_site_libs "https://github.com/nipunbatra/stt-ai-teaching/blob/master/site_libs/revealjs/dist/reveal.js"
click node_build_tools "https://github.com/nipunbatra/stt-ai-teaching/tree/master/Makefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_slides_src,node_labs_src,node_demos_src,node_assignments,node_lab01 toneBlue
class node_slides_theme,node_slides_media,node_diagrams_gen,node_diagrams_curated toneAmber
class node_site,node_quarto_config,node_publish_workflow,node_html_out,node_pdf_out,node_backup,node_site_libs toneMint
class node_datasets,node_shared_data,node_prompts,node_build_tools toneRose
```

## Components

### Authoring

Source teaching materials and course content

- [Slides source](https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/week09-git-lecture.md): lecture markdown · Weekly lecture slide source files · `slides/week09-git-lecture.md`
- [Labs](https://github.com/nipunbatra/stt-ai-teaching/blob/master/labs/week01-data-collection-lab.ipynb): notebook labs · Weekly lab notebooks and rendered lab pages · `labs/week01-data-collection-lab.ipynb`
- [Lecture demos](https://github.com/nipunbatra/stt-ai-teaching/blob/master/lecture-demos/week10/web-apps/4-fastapi/app.py): example code · Runnable scripts, notebooks, and small app examples for lectures · `lecture-demos/week10/web-apps/4-fastapi/app.py`
- [Assignments](https://github.com/nipunbatra/stt-ai-teaching/blob/master/assignments/week1-assignment.md): exercise markdown · Course assignments and guided exercises · `assignments/week1-assignment.md`
- [Lab guide](https://github.com/nipunbatra/stt-ai-teaching/blob/master/lab01/cpcb_api_teaching_guide.md): exercise guide · Standalone lab and teaching guide materials · `lab01/cpcb_api_teaching_guide.md`

### Generation

Scripts and assets that create figures and rendered artifacts

- [Theme assets](https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/iitgn-modern.css): slide theme · Shared slide styling, previews, and theme helpers · `slides/iitgn-modern.css`
- [Slide media](https://github.com/nipunbatra/stt-ai-teaching/blob/master/slides/images/week10/generate_concept_drift_cases.py): media assets · Generated images and audio used by slides · `slides/images/week10/generate_concept_drift_cases.py`
- [Diagram generators](https://github.com/nipunbatra/stt-ai-teaching/blob/master/diagram-generators/llm_pipeline.py): figure scripts · Standalone scripts and diagram sources for explanatory visuals · `diagram-generators/llm_pipeline.py`
- [Week diagrams](https://github.com/nipunbatra/stt-ai-teaching/blob/master/diagrams/week03/labeling_workflow.py): diagram scripts · Week-specific diagram sources and shared figure outputs · `diagrams/week03/labeling_workflow.py`

### Publication

Static site, rendered outputs, and archived builds

- [Course site](https://github.com/nipunbatra/stt-ai-teaching/blob/master/index.qmd): quarto site · Top-level Quarto publication for the course website · `index.qmd`
- [Quarto config](https://github.com/nipunbatra/stt-ai-teaching/blob/master/_quarto.yml): site config · Site-wide Quarto settings and navigation · `_quarto.yml`
- [Publish workflow](https://github.com/nipunbatra/stt-ai-teaching/blob/master/.github/workflows/quarto-publish.yml): ci workflow · GitHub Actions pipeline that builds and publishes the site · `.github/workflows/quarto-publish.yml`
- [HTML output](https://github.com/nipunbatra/stt-ai-teaching/blob/master/html/week10-web-apps-lecture.html): rendered html · Committed rendered lecture and lab HTML artifacts · `html/week10-web-apps-lecture.html`
- [PDF output](https://github.com/nipunbatra/stt-ai-teaching/blob/master/pdf/week10-web-apps-lecture.pdf): rendered pdf · Committed rendered lecture slide PDFs · `pdf/week10-web-apps-lecture.pdf`
- [Archive](https://github.com/nipunbatra/stt-ai-teaching/blob/master/backup/html/week14-rag-vector-db-lecture.html): preserved builds · Archived prior rendered versions of slides and outputs · `backup/html/week14-rag-vector-db-lecture.html`
- [Site libs](https://github.com/nipunbatra/stt-ai-teaching/blob/master/site_libs/revealjs/dist/reveal.js): frontend assets · Checked-in Quarto and Reveal.js runtime assets · `site_libs/revealjs/dist/reveal.js`

### Support

Shared data, prompts, and build orchestration

- [Datasets](https://github.com/nipunbatra/stt-ai-teaching/blob/master/datasets/week03/create_datasets.py): teaching data · Prepared datasets and annotation manifests used in labs and demos · `datasets/week03/create_datasets.py`
- [Local data](https://github.com/nipunbatra/stt-ai-teaching/blob/master/data/movies.db): sample data · Shared local data used by teaching examples · `data/movies.db`
- [Prompts](https://github.com/nipunbatra/stt-ai-teaching/blob/master/prompts/docker_concepts.txt): prompt bank · Reusable prompt text for AI and concept explanations · `prompts/docker_concepts.txt`
- [Build tools](https://github.com/nipunbatra/stt-ai-teaching/tree/master/Makefile): make and scripts · Local build entry points and theme generation helpers · `Makefile`

## Connections

- Build tools → Slides source: build · Renders lecture sources into site and slide outputs
- Build tools → Labs: build · Renders lab notebooks and pages
- Build tools → Diagram generators: generate · Runs figure and diagram generation scripts
- Build tools → Week diagrams: generate · Builds week-specific diagrams and shared figures
- Build tools → HTML output: render · Produces checked-in HTML deliverables
- Build tools → PDF output: render · Produces checked-in PDF deliverables
- Slides source → Theme assets: uses · Slides rely on theme styling and preview artifacts
- Slides source → Slide media: uses · Slides embed generated figures and audio
- Diagram generators → Slide media: produces · Diagram scripts generate figures used across the course
- Week diagrams → Slide media: produces · Curated diagram scripts contribute shared visual assets
- Datasets → Labs: supports · Prepared datasets back the lab notebooks
- Local data → Lecture demos: supports · Local sample data and databases power demos
- Prompts → Course site: informs · Prompt artifacts are part of the course content exposed on the site
- Site libs → Course site: enables · Quarto and Reveal.js assets support site rendering
- Quarto config → Course site: configures · Global site configuration drives publication behavior
- Publish workflow → Course site: publishes · CI workflow builds and deploys the site
- HTML output → Course site: served by · Rendered HTML artifacts are integrated into the course website
- PDF output → Course site: linked by · PDF slide artifacts are exposed through the site
- Archive → HTML output: archives · Preserves prior HTML builds
- Archive → PDF output: archives · Preserves prior PDF builds
- Assignments → Course site: published on · Assignments are surfaced through the course site
- Lab guide → Labs: extends · Standalone lab guide complements notebook-based labs
