# chen2mg/python_learning_repo architecture

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

- Interactive diagram: https://gitdiagram.com/chen2mg/python_learning_repo
- Repository: https://github.com/chen2mg/python_learning_repo

## Overview

This is a self-hosted learning platform: students sign in to JupyterHub, open their isolated JupyterLab workspace, study stage-and-chapter notebooks, and can take quizzes whose scored attempts are saved; admins can review results. User accounts are provisioned from a CSV, while Hub configuration determines access and mounts student folders at spawn time. The graph reflects the README and sampled configuration and service code; notebook contents and the omitted quiz-service routes were not inspected, so their internal behavior is not expanded.

Main entry points: [`jupyterhub/jupyterhub_config.py`](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py) (JupyterHub), [`jupyterhub/quiz_service.py`](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_service.py) (Quiz Service), [`jupyterhub/bootstrap_users.py`](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/bootstrap_users.py) (Account Bootstrap), [`app/Bella/stage1/chapter01.ipynb`](https://github.com/chen2mg/python_learning_repo/blob/main/app/Bella/stage1/chapter01.ipynb) (Student Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hub["Hub and Access"]
  node_hub_service["JupyterHub"]
  node_auth["NativeAuthenticator"]
  node_bootstrap["Account Bootstrap<br/>[bootstrap_users.py]"]
end

subgraph group_learning["Learning Workspaces"]
  node_workspace[("Student Workspace<br/>[chapter01.ipynb]")]
  node_lab["JupyterLab"]
  node_curriculum["Stage Chapters<br/>[chapter01.ipynb]"]
end

subgraph group_quizzes["Quiz System"]
  node_quiz_service["Quiz Service<br/>[quiz_service.py]"]
end

subgraph group_state["Platform State"]
  node_credentials["Credentials CSV<br/>[users.csv.example]"]
  node_hub_db[("Hub Database")]
  node_quiz_data["Quiz Questions<br/>[s1c1.json]"]
  node_quiz_results[("Attempt History<br/>[quiz_service.py]")]
end

node_student(("Student"))
node_admin(("Admin"))
node_tunnel["Cloudflare Tunnel"]

node_admin -->|"maintains accounts"| node_credentials
node_bootstrap -->|"reads credentials"| node_credentials
node_bootstrap -->|"creates or updates users"| node_hub_db
node_hub_service -->|"uses Hub database"| node_hub_db
node_hub_service -->|"authenticates users"| node_auth
node_hub_service -->|"scans user folders"| node_workspace
node_student -->|"signs in"| node_hub_service
node_hub_service -->|"spawns workspace"| node_lab
node_lab -->|"mounts folder"| node_workspace
node_student -->|"opens lessons"| node_lab
node_lab -->|"reads notebooks"| node_curriculum
node_hub_service -->|"starts and proxies"| node_quiz_service
node_student -->|"takes quiz"| node_quiz_service
node_quiz_service -->|"loads questions"| node_quiz_data
node_quiz_service -->|"scores and saves attempts"| node_quiz_results
node_admin -->|"views results"| node_quiz_service
node_quiz_service -->|"reads and manages attempts"| node_quiz_results
node_tunnel -.->|"provides public access"| node_hub_service

click node_hub_service "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py"
click node_auth "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py"
click node_bootstrap "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/bootstrap_users.py"
click node_credentials "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/credentials/users.csv.example"
click node_workspace "https://github.com/chen2mg/python_learning_repo/blob/main/app/Bella/stage1/chapter01.ipynb"
click node_lab "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py"
click node_curriculum "https://github.com/chen2mg/python_learning_repo/blob/main/app/Bella/stage1/chapter01.ipynb"
click node_quiz_service "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_service.py"
click node_quiz_data "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_data/s1c1.json"
click node_quiz_results "https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_service.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_hub_service,node_auth,node_bootstrap toneBlue
class node_workspace,node_lab,node_curriculum toneAmber
class node_quiz_service toneMint
class node_credentials,node_hub_db,node_quiz_data,node_quiz_results toneRose
class node_student,node_admin,node_tunnel toneIndigo
```

## Components

### Hub and Access

- [JupyterHub](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py): `jupyterhub/jupyterhub_config.py`
- [NativeAuthenticator](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py): `jupyterhub/jupyterhub_config.py`
- [Account Bootstrap](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/bootstrap_users.py): `jupyterhub/bootstrap_users.py`

### Learning Workspaces

- [Student Workspace](https://github.com/chen2mg/python_learning_repo/blob/main/app/Bella/stage1/chapter01.ipynb): `app/Bella/stage1/chapter01.ipynb`
- [JupyterLab](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/jupyterhub_config.py): `jupyterhub/jupyterhub_config.py`
- [Stage Chapters](https://github.com/chen2mg/python_learning_repo/blob/main/app/Bella/stage1/chapter01.ipynb): `app/Bella/stage1/chapter01.ipynb`

### Quiz System

- [Quiz Service](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_service.py): `jupyterhub/quiz_service.py`

### Platform State

- [Credentials CSV](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/credentials/users.csv.example): `jupyterhub/credentials/users.csv.example`
- **Hub Database**
- [Quiz Questions](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_data/s1c1.json): `jupyterhub/quiz_data/s1c1.json`
- [Attempt History](https://github.com/chen2mg/python_learning_repo/blob/main/jupyterhub/quiz_service.py): `jupyterhub/quiz_service.py`

### Other components

- **Student**
- **Admin**
- **Cloudflare Tunnel**

## Connections

- Admin → Credentials CSV: maintains accounts
- Account Bootstrap → Credentials CSV: reads credentials
- Account Bootstrap → Hub Database: creates or updates users
- JupyterHub → Hub Database: uses Hub database
- JupyterHub → NativeAuthenticator: authenticates users
- JupyterHub → Student Workspace: scans user folders
- Student → JupyterHub: signs in
- JupyterHub → JupyterLab: spawns workspace
- JupyterLab → Student Workspace: mounts folder
- Student → JupyterLab: opens lessons
- JupyterLab → Stage Chapters: reads notebooks
- JupyterHub → Quiz Service: starts and proxies
- Student → Quiz Service: takes quiz
- Quiz Service → Quiz Questions: loads questions
- Quiz Service → Attempt History: scores and saves attempts
- Admin → Quiz Service: views results
- Quiz Service → Attempt History: reads and manages attempts
- Cloudflare Tunnel → JupyterHub: provides public access