# spurushothaman419/cs249r_book architecture

> Architecture diagram of the GitHub repository spurushothaman419/cs249r_book, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spurushothaman419/cs249r_book
- Repository: https://github.com/spurushothaman419/cs249r_book

## Overview

This is an integrated machine-learning-systems curriculum repository, not a single application. Its learner-facing path combines the textbook with interactive labs, modeling through MLSys·im, hands-on TinyTorch work, and assessment through StaffML; Socratiq adds reading support and quizzes. The graph also shows the Binder authoring/build CLI as an internal layer. Some companion capabilities are documented but not sampled, so those links rely on README statements rather than inspected implementation.

Main entry points: [`labs/vol1`](https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/vol1) (Interactive labs), [`binder/cli/main.py`](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/main.py) (Binder CLI), [`binder/cli/commands/build.py`](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/build.py) (Book build), [`labs/mlsysbook_labs`](https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/mlsysbook_labs) (Lab components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning content"]
  node_textbook["Textbook series"]
end

subgraph group_labsim["Labs and modeling"]
  node_labs["Interactive labs"]
  node_labhelpers["Lab components"]
  node_labdata["Data pipeline models<br/>[data_pipeline.py]"]
  node_evidence["Experiment evidence"]
  node_sim["MLSys·im"]
  node_simengine["Simulation engine<br/>[engine.py]"]
  node_simpipeline["Solver pipeline<br/>[pipeline.py]"]
  node_simunits["Unit system<br/>[units.py]"]
  node_labstate["Lab state<br/>[state.py]"]
  node_labstyle["Lab presentation<br/>[style.py]"]
end

subgraph group_practice["Hands-on practice"]
  node_tinytorch["TinyTorch"]
  node_tito["TinyTorch CLI<br/>[main.py]"]
  node_milestones["Learning milestones<br/>[milestone.py]"]
  node_kits["Hardware kits"]
end

subgraph group_assessment["Assessment and reading"]
  node_staffml["StaffML assessment"]
  node_socratiq["Socratiq learning"]
  node_quizstorage["Quiz persistence<br/>[quiz-storage.js]"]
  node_spacedstorage["Spaced repetition<br/>[storage-handler.js]"]
  node_browserdb[("Browser database<br/>[indexDb.js]")]
end

subgraph group_authoring["Authoring tools"]
  node_binder["Binder CLI<br/>[main.py]"]
  node_build["Book build<br/>[build.py]"]
  node_config["Build configuration<br/>[config.py]"]
  node_discovery["Book discovery<br/>[discovery.py]"]
  node_validation["Validation checks<br/>[validate.py]"]
  node_epubchecks["EPUB checks<br/>[_epub_checks.py]"]
  node_pdfchecks["PDF checks<br/>[_pdf_checks.py]"]
  node_bookinfo["Book information<br/>[info.py]"]
  node_layout["Layout tools<br/>[layout.py]"]
  node_maintenance["Maintenance tools<br/>[maintenance.py]"]
end

node_learner(("Learner"))

node_learner -->|"studies"| node_textbook
node_learner -->|"explores interactively"| node_labs
node_labs -->|"models infrastructure with"| node_sim
node_learner -->|"builds internals with"| node_tinytorch
node_learner -->|"practices deployment on"| node_kits
node_learner -->|"demonstrates understanding in"| node_staffml
node_textbook -.->|"supports guided reading"| node_socratiq
node_socratiq -->|"persists quiz results"| node_quizstorage
node_quizstorage -->|"uses database"| node_browserdb
node_socratiq -.->|"supports spaced repetition"| node_spacedstorage
node_spacedstorage -.->|"persists study data"| node_browserdb
node_labs -->|"uses lab components"| node_labhelpers
node_labhelpers -->|"captures experiment evidence"| node_evidence
node_labhelpers -->|"uses data pipeline models"| node_labdata
node_labs -->|"uses lab state"| node_labstate
node_labs -->|"uses shared presentation"| node_labstyle
node_labs -->|"runs modeling experiments"| node_simengine
node_simengine -->|"uses quantities"| node_simunits
node_sim -->|"provides solver pipeline"| node_simpipeline
node_tinytorch -.->|"offers learner workflow"| node_tito
node_tito -->|"tracks progress"| node_milestones
node_binder -->|"dispatches build"| node_build
node_binder -->|"dispatches validation"| node_validation
node_binder -->|"dispatches information"| node_bookinfo
node_binder -->|"dispatches layout"| node_layout
node_binder -->|"dispatches maintenance"| node_maintenance
node_build -->|"loads configuration"| node_config
node_build -->|"discovers book inputs"| node_discovery
node_build -->|"runs EPUB checks"| node_epubchecks
node_build -->|"runs PDF checks"| node_pdfchecks

click node_textbook "https://github.com/spurushothaman419/cs249r_book/tree/dev/books"
click node_labs "https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/vol1"
click node_labhelpers "https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/mlsysbook_labs"
click node_labdata "https://github.com/spurushothaman419/cs249r_book/blob/dev/labs/mlsysbook_labs/data_pipeline.py"
click node_evidence "https://github.com/spurushothaman419/cs249r_book/blob/dev/labs/mlsysbook_labs/experiment_evidence.py"
click node_sim "https://github.com/spurushothaman419/cs249r_book/tree/dev/mlsysim/mlsysim"
click node_simengine "https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/engine/engine.py"
click node_simpipeline "https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/engine/pipeline.py"
click node_simunits "https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/core/units.py"
click node_labstate "https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/labs/state.py"
click node_labstyle "https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/labs/style.py"
click node_tinytorch "https://github.com/spurushothaman419/cs249r_book/tree/dev/tinytorch"
click node_tito "https://github.com/spurushothaman419/cs249r_book/blob/dev/tinytorch/tito/main.py"
click node_milestones "https://github.com/spurushothaman419/cs249r_book/blob/dev/tinytorch/tito/commands/milestone.py"
click node_kits "https://github.com/spurushothaman419/cs249r_book/tree/dev/kits"
click node_staffml "https://github.com/spurushothaman419/cs249r_book/tree/dev/staffml/app/src/app"
click node_socratiq "https://github.com/spurushothaman419/cs249r_book/tree/dev/socratiq/src_shadow/js/components"
click node_quizstorage "https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/components/quiz/quiz-storage.js"
click node_spacedstorage "https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/components/spaced_repetition/handlers/storage-handler.js"
click node_browserdb "https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/libs/utils/indexDb.js"
click node_binder "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/main.py"
click node_build "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/build.py"
click node_config "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/core/config.py"
click node_discovery "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/core/discovery.py"
click node_validation "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/validate.py"
click node_epubchecks "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/_epub_checks.py"
click node_pdfchecks "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/_pdf_checks.py"
click node_bookinfo "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/info.py"
click node_layout "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/layout.py"
click node_maintenance "https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/maintenance.py"

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_textbook toneBlue
class node_labs,node_labhelpers,node_labdata,node_evidence,node_sim,node_simengine,node_simpipeline,node_simunits,node_labstate,node_labstyle toneAmber
class node_tinytorch,node_tito,node_milestones,node_kits toneMint
class node_staffml,node_socratiq,node_quizstorage,node_spacedstorage,node_browserdb toneRose
class node_binder,node_build,node_config,node_discovery,node_validation,node_epubchecks,node_pdfchecks,node_bookinfo,node_layout,node_maintenance,node_learner toneIndigo
```

## Components

### Learning content

- [Textbook series](https://github.com/spurushothaman419/cs249r_book/tree/dev/books): `books`

### Labs and modeling

- [Interactive labs](https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/vol1): `labs/vol1`
- [Lab components](https://github.com/spurushothaman419/cs249r_book/tree/dev/labs/mlsysbook_labs): `labs/mlsysbook_labs`
- [Data pipeline models](https://github.com/spurushothaman419/cs249r_book/blob/dev/labs/mlsysbook_labs/data_pipeline.py): `labs/mlsysbook_labs/data_pipeline.py`
- [Experiment evidence](https://github.com/spurushothaman419/cs249r_book/blob/dev/labs/mlsysbook_labs/experiment_evidence.py): `labs/mlsysbook_labs/experiment_evidence.py`
- [MLSys·im](https://github.com/spurushothaman419/cs249r_book/tree/dev/mlsysim/mlsysim): `mlsysim/mlsysim`
- [Simulation engine](https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/engine/engine.py): `mlsysim/mlsysim/engine/engine.py`
- [Solver pipeline](https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/engine/pipeline.py): `mlsysim/mlsysim/engine/pipeline.py`
- [Unit system](https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/core/units.py): `mlsysim/mlsysim/core/units.py`
- [Lab state](https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/labs/state.py): `mlsysim/mlsysim/labs/state.py`
- [Lab presentation](https://github.com/spurushothaman419/cs249r_book/blob/dev/mlsysim/mlsysim/labs/style.py): `mlsysim/mlsysim/labs/style.py`

### Hands-on practice

- [TinyTorch](https://github.com/spurushothaman419/cs249r_book/tree/dev/tinytorch): `tinytorch`
- [TinyTorch CLI](https://github.com/spurushothaman419/cs249r_book/blob/dev/tinytorch/tito/main.py): `tinytorch/tito/main.py`
- [Learning milestones](https://github.com/spurushothaman419/cs249r_book/blob/dev/tinytorch/tito/commands/milestone.py): `tinytorch/tito/commands/milestone.py`
- [Hardware kits](https://github.com/spurushothaman419/cs249r_book/tree/dev/kits): `kits`

### Assessment and reading

- [StaffML assessment](https://github.com/spurushothaman419/cs249r_book/tree/dev/staffml/app/src/app): `staffml/app/src/app`
- [Socratiq learning](https://github.com/spurushothaman419/cs249r_book/tree/dev/socratiq/src_shadow/js/components): `socratiq/src_shadow/js/components`
- [Quiz persistence](https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/components/quiz/quiz-storage.js): `socratiq/src_shadow/js/components/quiz/quiz-storage.js`
- [Spaced repetition](https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/components/spaced_repetition/handlers/storage-handler.js): `socratiq/src_shadow/js/components/spaced_repetition/handlers/storage-handler.js`
- [Browser database](https://github.com/spurushothaman419/cs249r_book/blob/dev/socratiq/src_shadow/js/libs/utils/indexDb.js): `socratiq/src_shadow/js/libs/utils/indexDb.js`

### Authoring tools

- [Binder CLI](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/main.py): `binder/cli/main.py`
- [Book build](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/build.py): `binder/cli/commands/build.py`
- [Build configuration](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/core/config.py): `binder/cli/core/config.py`
- [Book discovery](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/core/discovery.py): `binder/cli/core/discovery.py`
- [Validation checks](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/validate.py): `binder/cli/commands/validate.py`
- [EPUB checks](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/_epub_checks.py): `binder/cli/commands/_epub_checks.py`
- [PDF checks](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/_pdf_checks.py): `binder/cli/commands/_pdf_checks.py`
- [Book information](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/info.py): `binder/cli/commands/info.py`
- [Layout tools](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/layout.py): `binder/cli/commands/layout.py`
- [Maintenance tools](https://github.com/spurushothaman419/cs249r_book/blob/dev/binder/cli/commands/maintenance.py): `binder/cli/commands/maintenance.py`

### Other components

- **Learner**

## Connections

- Learner → Textbook series: studies (evidence: `README.md`)
- Learner → Interactive labs: explores interactively (evidence: `README.md`)
- Interactive labs → MLSys·im: models infrastructure with (evidence: `README.md`)
- Learner → TinyTorch: builds internals with (evidence: `README.md`)
- Learner → Hardware kits: practices deployment on (evidence: `README.md`)
- Learner → StaffML assessment: demonstrates understanding in (evidence: `README.md`)
- Textbook series → Socratiq learning: supports guided reading (evidence: `README.md`)
- Socratiq learning → Quiz persistence: persists quiz results (evidence: `socratiq/src_shadow/js/components/quiz/quiz-storage.js`)
- Quiz persistence → Browser database: uses database (evidence: `socratiq/src_shadow/js/components/quiz/quiz-storage.js`)
- Socratiq learning → Spaced repetition: supports spaced repetition (evidence: `README.md`)
- Spaced repetition → Browser database: persists study data
- Interactive labs → Lab components: uses lab components
- Lab components → Experiment evidence: captures experiment evidence (evidence: `labs/vol2/lab_04_data_storage.py`)
- Lab components → Data pipeline models: uses data pipeline models (evidence: `labs/mlsysbook_labs/data_pipeline.py`)
- Interactive labs → Lab state: uses lab state
- Interactive labs → Lab presentation: uses shared presentation
- Interactive labs → Simulation engine: runs modeling experiments
- Simulation engine → Unit system: uses quantities (evidence: `mlsysim/mlsysim/engine/engine.py`)
- MLSys·im → Solver pipeline: provides solver pipeline (evidence: `mlsysim/mlsysim/engine/pipeline.py`)
- TinyTorch → TinyTorch CLI: offers learner workflow (evidence: `README.md`)
- TinyTorch CLI → Learning milestones: tracks progress (evidence: `tinytorch/tito/main.py`)
- Binder CLI → Book build: dispatches build (evidence: `binder/cli/main.py`)
- Binder CLI → Validation checks: dispatches validation (evidence: `binder/cli/main.py`)
- Binder CLI → Book information: dispatches information (evidence: `binder/cli/main.py`)
- Binder CLI → Layout tools: dispatches layout (evidence: `binder/cli/main.py`)
- Binder CLI → Maintenance tools: dispatches maintenance (evidence: `binder/cli/main.py`)
- Book build → Build configuration: loads configuration (evidence: `binder/cli/commands/build.py`)
- Book build → Book discovery: discovers book inputs (evidence: `binder/cli/commands/build.py`)
- Book build → EPUB checks: runs EPUB checks (evidence: `binder/cli/commands/build.py`)
- Book build → PDF checks: runs PDF checks (evidence: `binder/cli/commands/build.py`)
