# eyadalahmad/interactive-qm-exercises architecture

> Architecture diagram of the GitHub repository eyadalahmad/interactive-qm-exercises, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eyadalahmad/interactive-qm-exercises
- Repository: https://github.com/eyadalahmad/interactive-qm-exercises

## Overview

Interactive Streamlit QM exercises serve student groups and administrators. The main workflow is group-code login, exercise selection and timed participation, then saving up to three attempts per group, exercise and session; administrators manage groups and exercises and compare results. The graph includes both documented exercise types, timing, session preparation and Supabase persistence. Relationships are limited to calls visible in excerpts or references in the source index; unsampled implementation details are not inferred.

Main entry points: [`database/supabase_client.py`](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/database/supabase_client.py) (Supabase client), [`ui/main_view.py`](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/main_view.py) (Application routing), [`ui/student_dashboard.py`](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/student_dashboard.py) (Student dashboard), [`services/exercise_service.py`](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/exercise_service.py) (Exercise service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_main["Application routing<br/>[main_view.py]"]
end

subgraph group_access["Access and administration"]
  node_admin_login["Admin login<br/>[admin_login.py]"]
  node_admin_dashboard["Admin dashboard<br/>[admin_dashboard.py]"]
  node_group_management["Group management"]
  node_exercise_management["Exercise controls"]
  node_results_view["Results comparison"]
end

subgraph group_exercise["Student exercises"]
  node_countdown["Countdown timer<br/>[countdown_timer.py]"]
  node_student_dashboard["Student dashboard"]
  node_color_view["Color mixing"]
  node_printing_view["3D printing exercise"]
  node_printing_visualizer["3D visualizer"]
end

subgraph group_services["Domain services"]
  node_admin_auth["Admin authentication<br/>[admin_auth.py]"]
  node_group_service["Group service<br/>[group_service.py]"]
  node_results_service["Results service<br/>[results_service.py]"]
  node_printing_simulation["Printing simulation"]
  node_exercise_service["Exercise service"]
  node_attempt_service["Attempt service<br/>[attempt_service.py]"]
  node_session_service["Session service<br/>[session_service.py]"]
end

subgraph group_storage["Persistence"]
  node_supabase_client["Supabase client<br/>[supabase_client.py]"]
  node_supabase[("Supabase database")]
end

node_user(("Student or admin"))

node_user -->|"opens"| node_main
node_main -->|"routes admin"| node_admin_dashboard
node_main -->|"routes student"| node_student_dashboard
node_main -->|"opens login"| node_admin_login
node_main -->|"authenticates group"| node_group_service
node_admin_login -->|"checks credentials"| node_admin_auth
node_admin_dashboard -->|"renders"| node_group_management
node_admin_dashboard -->|"renders"| node_exercise_management
node_admin_dashboard -->|"renders"| node_results_view
node_group_management -->|"manages groups"| node_group_service
node_group_service -->|"checks access"| node_admin_auth
node_exercise_management -->|"checks access"| node_admin_auth
node_exercise_management -->|"controls exercises"| node_exercise_service
node_exercise_management -->|"renders timer"| node_countdown
node_results_view -->|"loads exercises"| node_exercise_service
node_results_view -->|"loads results"| node_results_service
node_student_dashboard -->|"loads status"| node_exercise_service
node_student_dashboard -->|"renders timer"| node_countdown
node_student_dashboard -->|"dispatches color"| node_color_view
node_student_dashboard -->|"dispatches printing"| node_printing_view
node_color_view -->|"loads and saves attempts"| node_attempt_service
node_color_view -->|"loads target color"| node_exercise_service
node_printing_view -->|"loads and saves attempts"| node_attempt_service
node_printing_view -->|"calculates quality"| node_printing_simulation
node_printing_view -->|"renders model"| node_printing_visualizer
node_attempt_service -->|"gets session"| node_session_service
node_group_service -->|"uses client"| node_supabase_client
node_exercise_service -->|"uses client"| node_supabase_client
node_attempt_service -->|"uses client"| node_supabase_client
node_session_service -->|"uses client"| node_supabase_client
node_results_service -->|"uses client"| node_supabase_client
node_supabase_client -->|"queries and updates"| node_supabase

click node_main "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/main_view.py"
click node_admin_login "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/admin_login.py"
click node_admin_dashboard "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/admin_dashboard.py"
click node_admin_auth "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/admin_auth.py"
click node_group_management "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/group_management.py"
click node_group_service "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/group_service.py"
click node_exercise_management "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercise_management.py"
click node_countdown "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/countdown_timer.py"
click node_results_view "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/results_comparison.py"
click node_results_service "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/results_service.py"
click node_student_dashboard "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/student_dashboard.py"
click node_color_view "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/color_mixing_view.py"
click node_printing_view "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/printing_3d_view.py"
click node_printing_simulation "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/printing_simulation_service.py"
click node_printing_visualizer "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/printing_3d_visualizer.py"
click node_exercise_service "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/exercise_service.py"
click node_attempt_service "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/attempt_service.py"
click node_session_service "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/session_service.py"
click node_supabase_client "https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/database/supabase_client.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_main toneBlue
class node_admin_login,node_admin_dashboard,node_group_management,node_exercise_management,node_results_view toneAmber
class node_countdown,node_student_dashboard,node_color_view,node_printing_view,node_printing_visualizer toneMint
class node_admin_auth,node_group_service,node_results_service,node_printing_simulation,node_exercise_service,node_attempt_service,node_session_service toneRose
class node_supabase_client,node_supabase,node_user toneIndigo
```

## Components

### App entry

- [Application routing](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/main_view.py): `ui/main_view.py`

### Access and administration

- [Admin login](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/admin_login.py): `ui/admin_login.py`
- [Admin dashboard](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/admin_dashboard.py): `ui/admin_dashboard.py`
- [Group management](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/group_management.py): `ui/group_management.py`
- [Exercise controls](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercise_management.py): `ui/exercise_management.py`
- [Results comparison](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/results_comparison.py): `ui/results_comparison.py`

### Student exercises

- [Countdown timer](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/countdown_timer.py): `ui/countdown_timer.py`
- [Student dashboard](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/student_dashboard.py): `ui/student_dashboard.py`
- [Color mixing](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/color_mixing_view.py): `ui/exercises/color_mixing_view.py`
- [3D printing exercise](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/printing_3d_view.py): `ui/exercises/printing_3d_view.py`
- [3D visualizer](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/ui/exercises/printing_3d_visualizer.py): `ui/exercises/printing_3d_visualizer.py`

### Domain services

- [Admin authentication](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/admin_auth.py): `services/admin_auth.py`
- [Group service](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/group_service.py): `services/group_service.py`
- [Results service](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/results_service.py): `services/results_service.py`
- [Printing simulation](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/printing_simulation_service.py): `services/printing_simulation_service.py`
- [Exercise service](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/exercise_service.py): `services/exercise_service.py`
- [Attempt service](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/attempt_service.py): `services/attempt_service.py`
- [Session service](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/services/session_service.py): `services/session_service.py`

### Persistence

- [Supabase client](https://github.com/eyadalahmad/interactive-qm-exercises/blob/main/database/supabase_client.py): `database/supabase_client.py`
- **Supabase database**

### Other components

- **Student or admin**

## Connections

- Student or admin → Application routing: opens
- Application routing → Admin dashboard: routes admin (evidence: `ui/main_view.py`)
- Application routing → Student dashboard: routes student (evidence: `ui/main_view.py`)
- Application routing → Admin login: opens login (evidence: `ui/main_view.py`)
- Application routing → Group service: authenticates group (evidence: `ui/main_view.py`)
- Admin login → Admin authentication: checks credentials (evidence: `ui/admin_login.py`)
- Admin dashboard → Group management: renders (evidence: `ui/admin_dashboard.py`)
- Admin dashboard → Exercise controls: renders (evidence: `ui/admin_dashboard.py`)
- Admin dashboard → Results comparison: renders (evidence: `ui/admin_dashboard.py`)
- Group management → Group service: manages groups (evidence: `ui/group_management.py`)
- Group service → Admin authentication: checks access (evidence: `services/group_service.py`)
- Exercise controls → Admin authentication: checks access (evidence: `ui/exercise_management.py`)
- Exercise controls → Exercise service: controls exercises (evidence: `ui/exercise_management.py`)
- Exercise controls → Countdown timer: renders timer (evidence: `ui/exercise_management.py`)
- Results comparison → Exercise service: loads exercises (evidence: `ui/results_comparison.py`)
- Results comparison → Results service: loads results (evidence: `ui/results_comparison.py`)
- Student dashboard → Exercise service: loads status (evidence: `ui/student_dashboard.py`)
- Student dashboard → Countdown timer: renders timer (evidence: `ui/student_dashboard.py`)
- Student dashboard → Color mixing: dispatches color (evidence: `ui/student_dashboard.py`)
- Student dashboard → 3D printing exercise: dispatches printing (evidence: `ui/student_dashboard.py`)
- Color mixing → Attempt service: loads and saves attempts (evidence: `ui/exercises/color_mixing_view.py`)
- Color mixing → Exercise service: loads target color (evidence: `ui/exercises/color_mixing_view.py`)
- 3D printing exercise → Attempt service: loads and saves attempts (evidence: `ui/exercises/printing_3d_view.py`)
- 3D printing exercise → Printing simulation: calculates quality (evidence: `ui/exercises/printing_3d_view.py`)
- 3D printing exercise → 3D visualizer: renders model (evidence: `ui/exercises/printing_3d_view.py`)
- Attempt service → Session service: gets session (evidence: `services/attempt_service.py`)
- Group service → Supabase client: uses client (evidence: `services/group_service.py`)
- Exercise service → Supabase client: uses client (evidence: `services/exercise_service.py`)
- Attempt service → Supabase client: uses client (evidence: `services/attempt_service.py`)
- Session service → Supabase client: uses client (evidence: `services/session_service.py`)
- Results service → Supabase client: uses client (evidence: `services/results_service.py`)
- Supabase client → Supabase database: queries and updates (evidence: `database/supabase_client.py`)
