# genterist/bkt-jupyter architecture

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

- Interactive diagram: https://gitdiagram.com/genterist/bkt-jupyter
- Repository: https://github.com/genterist/bkt-jupyter

## Overview

1. **Project purpose**
   - This repository is a small, notebook-driven demonstration of **Bayesian Knowledge Tracing (BKT)**.
   - It is oriented around running experiments on student response data and exporting per-student results.

2. **Primary execution model**
   - The core workflow lives in **Jupyter/Colab notebooks**: `BKT_Implementation.ipynb` is the main runnable artifact.
   - `AboutColaboratory.ipynb` appears to be a supporting notebook or onboarding/example file for Google Colab usage.
   - `bkt_implementation.py` is likely a code extraction or reusable Python implementation backing the notebook.

3. **Main computational subsystem**
   - The central subsystem is the **BKT inference/estimation logic**.
   - From the filenames, the implementation likely models student learning states over time using the standard BKT parameters: probability of initial knowledge, learning, slipping, and guessing.
   - This logic is probably executed sequentially per student and per observation sequence.

4. **Input data boundary**
   - `data.csv` is the shared dataset input, likely containing the raw student interaction records used by the notebook.
   - Additional files such as `stu1.csv`, `stu10.csv`, `stu101.csv`, and `stu1_double_P_T.csv`, `stu1_double_S_G.csv` suggest student-specific datasets or parameter sweep inputs used for experiments.

5. **Per-student processing flow**
   - The architecture appears to be:
     - load student interaction data,
     - run BKT updates over the sequence,
     - produce a derived result file for each student.
   - The presence of many `exportedResults/stu*.csv` files indicates the output is partitioned by student identifier rather than aggregated into a single report.

6. **Output / reporting subsystem**
   - `exportedResults/` is the main results boundary.
   - Each generated CSV likely contains predicted mastery states, posterior probabilities, or other trace outputs for an individual student.
   - `BKT-Report.pdf` is a static deliverable summarizing the work, likely generated from the notebook content.

7. **Session/runtime assumptions**
   - The README is explicitly centered on **Google Colab** as the runtime environment.
   - Data files are uploaded into an ephemeral session store, so the workflow assumes a notebook runtime with manual file upload and transient local storage.

8. **Data persistence characteristics**
   - Inputs are treated as session-local in Colab, not as a durable backend service.
   - Outputs are also session-local unless manually downloaded, which means the repository functions more like a reproducible analysis bundle than a deployed application.

9. **Tooling and dependencies**
   - The repo is built around **Python + Jupyter notebooks**, with Colab as the execution host.
   - There is no sign of a separate package manager, API server, database, or frontend application.
   - The architecture is therefore computational and file-based, not service-oriented.

10. **Repository structure meaning**
   - The root contains the main code and data artifacts together, reflecting a compact research/demo project.
   - The large number of CSV outputs suggests the notebook was used to run experiments across many students and store each result independently.

11. **Likely diagram boundaries**
   - A useful architecture diagram would show:
     - notebook/runtime environment,
     - input CSV datasets,
     - BKT computation layer,
     - per-student exported CSV results,
     - optional report/documentation outputs.
   - The key boundary is between the **Colab notebook session** and the **file-based inputs/outputs**.

12. **Overall architecture summary**
   - This repository is a **single-workflow analytical pipeline**: notebook-driven BKT computation over CSV data, producing per-student CSV outputs and a report.
   - It is not a multi-service system; the important architecture is the flow of data through an interactive Python notebook into generated result files.

Main entry points: [`BKT_Implementation.ipynb`](https://github.com/genterist/bkt-jupyter/blob/master/BKT_Implementation.ipynb) (Main notebook), [`bkt_implementation.py`](https://github.com/genterist/bkt-jupyter/blob/master/bkt_implementation.py) (BKT code), [`exportedResults`](https://github.com/genterist/bkt-jupyter/tree/master/exportedResults) (Exports), [`README.md`](https://github.com/genterist/bkt-jupyter/blob/master/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Notebook runtime"]
  node_readme["README<br/>documentation<br/>[README.md]"]
  node_main_notebook["Main notebook"]
  node_colab_notebook["Colab notes<br/>notebook"]
  node_license["License"]
end

subgraph group_inputs["Input data"]
  node_master_data["Master data<br/>csv dataset<br/>[data.csv]"]
  node_stu1_data["Student sample<br/>csv dataset<br/>[stu1.csv]"]
  node_stu10_data["Student sample<br/>csv dataset<br/>[stu10.csv]"]
  node_stu101_data["Student sample<br/>csv dataset<br/>[stu101.csv]"]
  node_pt_sweep["P/T sweep<br/>csv experiment"]
  node_sg_sweep["S/G sweep<br/>csv experiment"]
end

subgraph group_core["BKT logic"]
  node_python_impl["BKT code<br/>python module"]
end

subgraph group_outputs["Results and report"]
  node_results_dir[("Exports<br/>results folder")]
  node_result_stu11["stu11 result<br/>result csv<br/>[stu11.csv]"]
  node_result_stu118["stu118 result<br/>result csv<br/>[stu118.csv]"]
  node_result_stu127["stu127 result<br/>result csv<br/>[stu127.csv]"]
  node_report["Report<br/>[BKT-Report.pdf]"]
end

node_readme -->|"explains run"| node_main_notebook
node_readme -->|"supports"| node_colab_notebook
node_main_notebook -->|"executes"| node_python_impl
node_colab_notebook -.->|"orients"| node_main_notebook
node_master_data -->|"loads"| node_main_notebook
node_stu1_data -->|"loads"| node_main_notebook
node_stu10_data -->|"loads"| node_main_notebook
node_stu101_data -->|"loads"| node_main_notebook
node_pt_sweep -.->|"tunes"| node_python_impl
node_sg_sweep -.->|"tunes"| node_python_impl
node_python_impl -->|"writes"| node_results_dir
node_results_dir -->|"contains"| node_result_stu11
node_results_dir -->|"contains"| node_result_stu118
node_results_dir -->|"contains"| node_result_stu127
node_main_notebook -->|"renders"| node_report
node_python_impl -.->|"supports"| node_report
node_license -.->|"governs"| node_readme

click node_readme "https://github.com/genterist/bkt-jupyter/blob/master/README.md"
click node_main_notebook "https://github.com/genterist/bkt-jupyter/blob/master/BKT_Implementation.ipynb"
click node_colab_notebook "https://github.com/genterist/bkt-jupyter/blob/master/AboutColaboratory.ipynb"
click node_python_impl "https://github.com/genterist/bkt-jupyter/blob/master/bkt_implementation.py"
click node_master_data "https://github.com/genterist/bkt-jupyter/blob/master/data.csv"
click node_stu1_data "https://github.com/genterist/bkt-jupyter/blob/master/stu1.csv"
click node_stu10_data "https://github.com/genterist/bkt-jupyter/blob/master/stu10.csv"
click node_stu101_data "https://github.com/genterist/bkt-jupyter/blob/master/stu101.csv"
click node_pt_sweep "https://github.com/genterist/bkt-jupyter/blob/master/stu1_double_P_T.csv"
click node_sg_sweep "https://github.com/genterist/bkt-jupyter/blob/master/stu1_double_S_G.csv"
click node_results_dir "https://github.com/genterist/bkt-jupyter/tree/master/exportedResults"
click node_result_stu11 "https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu11.csv"
click node_result_stu118 "https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu118.csv"
click node_result_stu127 "https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu127.csv"
click node_report "https://github.com/genterist/bkt-jupyter/blob/master/BKT-Report.pdf"
click node_license "https://github.com/genterist/bkt-jupyter/tree/master/LICENSE"

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_readme,node_main_notebook,node_colab_notebook,node_license toneBlue
class node_master_data,node_stu1_data,node_stu10_data,node_stu101_data,node_pt_sweep,node_sg_sweep toneAmber
class node_python_impl toneMint
class node_results_dir,node_result_stu11,node_result_stu118,node_result_stu127,node_report toneRose
```

## Components

### Notebook runtime

Interactive Colab/Jupyter execution and orchestration

- [README](https://github.com/genterist/bkt-jupyter/blob/master/README.md): documentation · Usage and Colab-oriented project overview · `README.md`
- [Main notebook](https://github.com/genterist/bkt-jupyter/blob/master/BKT_Implementation.ipynb): notebook · Primary runnable BKT experiment · `BKT_Implementation.ipynb`
- [Colab notes](https://github.com/genterist/bkt-jupyter/blob/master/AboutColaboratory.ipynb): notebook · Supporting Colaboratory notebook · `AboutColaboratory.ipynb`
- [License](https://github.com/genterist/bkt-jupyter/tree/master/LICENSE): license · Repository license boundary · `LICENSE`

### Input data

Source CSV datasets used by the notebook workflow

- [Master data](https://github.com/genterist/bkt-jupyter/blob/master/data.csv): csv dataset · Primary student interaction dataset · `data.csv`
- [Student sample](https://github.com/genterist/bkt-jupyter/blob/master/stu1.csv): csv dataset · Representative per-student input sequence · `stu1.csv`
- [Student sample](https://github.com/genterist/bkt-jupyter/blob/master/stu10.csv): csv dataset · Representative per-student input sequence · `stu10.csv`
- [Student sample](https://github.com/genterist/bkt-jupyter/blob/master/stu101.csv): csv dataset · Representative per-student input sequence · `stu101.csv`
- [P/T sweep](https://github.com/genterist/bkt-jupyter/blob/master/stu1_double_P_T.csv): csv experiment · Parameter sweep input for learning/transition behavior · `stu1_double_P_T.csv`
- [S/G sweep](https://github.com/genterist/bkt-jupyter/blob/master/stu1_double_S_G.csv): csv experiment · Parameter sweep input for slip/guess behavior · `stu1_double_S_G.csv`

### BKT logic

Bayesian Knowledge Tracing implementation and experiment flow

- [BKT code](https://github.com/genterist/bkt-jupyter/blob/master/bkt_implementation.py): python module · Reusable implementation extracted from the notebook · `bkt_implementation.py`

### Results and report

Generated per-student outputs and final deliverables

- [Exports](https://github.com/genterist/bkt-jupyter/tree/master/exportedResults): results folder · Session output boundary for per-student CSV exports · `exportedResults`
- [stu11 result](https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu11.csv): result csv · Representative per-student exported trace · `exportedResults/stu11.csv`
- [stu118 result](https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu118.csv): result csv · Representative per-student exported trace · `exportedResults/stu118.csv`
- [stu127 result](https://github.com/genterist/bkt-jupyter/blob/master/exportedResults/stu127.csv): result csv · Representative per-student exported trace · `exportedResults/stu127.csv`
- [Report](https://github.com/genterist/bkt-jupyter/blob/master/BKT-Report.pdf): pdf report · Static write-up of the BKT demonstration · `BKT-Report.pdf`

## Connections

- README → Main notebook: explains run · README points to the main notebook workflow
- README → Colab notes: supports · Colab guidance and onboarding material
- Main notebook → BKT code: executes · Notebook drives the reusable BKT implementation
- Colab notes → Main notebook: orients · Supporting notebook helps with notebook-based execution
- Master data → Main notebook: loads · Primary dataset is consumed by the notebook workflow
- Student sample → Main notebook: loads · Per-student input sequence used in experiments
- Student sample → Main notebook: loads · Per-student input sequence used in experiments
- Student sample → Main notebook: loads · Per-student input sequence used in experiments
- P/T sweep → BKT code: tunes · Parameter sweep input explores learning/transition settings
- S/G sweep → BKT code: tunes · Parameter sweep input explores slip/guess settings
- BKT code → Exports: writes · Implementation exports per-student CSV outputs
- Exports → stu11 result: contains · Representative exported result file
- Exports → stu118 result: contains · Representative exported result file
- Exports → stu127 result: contains · Representative exported result file
- Main notebook → Report: renders · Notebook content is summarized into the final PDF report
- BKT code → Report: supports · Core computations underpin the written report
- License → README: governs · Repository license applies to the documented workflow