# lrondal/mathutrice architecture

> Architecture diagram of the GitHub repository lrondal/mathutrice, 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/lrondal/mathutrice
- Repository: https://github.com/lrondal/mathutrice

## Overview

MATHutrice is a web-based mathematics tutor for EPF first-year students. Students sign in, choose a notion, practise generated exercises, receive answer feedback, and build competence scores that inform recommendations; free chat is also available. Teachers and admins have separate pages, including PDF upload. The map distinguishes session orchestration, question formats, evaluation, and persistence. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; some route-level details and PDF processing are not sampled.

Main entry points: [`mathutrice/app.py`](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py) (FastAPI routes), [`mathutrice/fonctions_python/main.py`](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/main.py) (Exercise workflow), [`mathutrice/fonctions_python/session_generator.py`](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/session_generator.py) (Session orchestration), [`mathutrice/fonctions_python/base_generator.py`](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/base_generator.py) (Shared generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["FastAPI routes<br/>[app.py]"]
  node_pages["Web pages"]
  node_auth["Sign-in flows<br/>[app.py]"]
  node_teacher_upload["Teacher PDF upload<br/>[app.py]"]
end

subgraph group_learning["Practice and sessions"]
  node_chat["Free chat<br/>[chatbot.py]"]
  node_session["Session orchestration"]
  node_exercise_main["Exercise workflow<br/>[main.py]"]
  node_base_generator["Shared generation<br/>[base_generator.py]"]
  node_qcm["Multiple choice<br/>[qcm_generator.py]"]
  node_qro["Open answer<br/>[qro_generator.py]"]
  node_steps["Step-by-step<br/>[steps_generator.py]"]
  node_fill_blanks["Fill blanks<br/>[trous_generator.py]"]
end

subgraph group_assessment["Assessment and guidance"]
  node_answer_check["Answer checking<br/>[verifier.py]"]
  node_gap_eval["Competence gap evaluation"]
  node_recommend["Weakness recommendations"]
end

subgraph group_data["Reference and persistence"]
  node_reference["Notions and competences<br/>[referentiel.py]"]
  node_seed["Reference data seeding<br/>[seed.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

subgraph group_integrations["External services"]
  node_entra{{"Microsoft Entra ID"}}
  node_llm{{"LLM endpoint"}}
  node_llm_client["Shared LLM client<br/>[llm_client.py]"]
end

node_student(("Student"))
node_teacher(("Teacher / admin"))

node_student -->|"uses"| node_app
node_teacher -->|"uses"| node_app
node_app -->|"renders"| node_pages
node_app -->|"handles sign-in"| node_auth
node_auth -.->|"authenticates"| node_entra
node_app -->|"routes uploads"| node_teacher_upload
node_student -->|"chooses notion"| node_session
node_app -->|"requests sessions"| node_session
node_session -->|"uses training logic"| node_exercise_main
node_exercise_main -->|"generates QCM"| node_qcm
node_exercise_main -->|"generates open answers"| node_qro
node_exercise_main -->|"generates steps"| node_steps
node_exercise_main -->|"generates blanks"| node_fill_blanks
node_qcm -->|"uses shared generation"| node_base_generator
node_qro -->|"uses shared generation"| node_base_generator
node_steps -->|"uses shared generation"| node_base_generator
node_fill_blanks -->|"uses shared generation"| node_base_generator
node_qcm -->|"verifies answers"| node_answer_check
node_qro -.->|"judges answers"| node_llm_client
node_base_generator -->|"calls"| node_llm_client
node_llm_client -->|"sends requests"| node_llm
node_app -->|"serves chat"| node_chat
node_chat -->|"calls"| node_llm_client
node_app -->|"requests diagnosis"| node_gap_eval
node_exercise_main -->|"diagnoses answers"| node_gap_eval
node_gap_eval -->|"calls"| node_llm_client
node_session -->|"selects next practice"| node_recommend
node_session -->|"reads competences"| node_reference
node_gap_eval -->|"reads competences"| node_reference
node_app -->|"opens sessions"| node_database
node_app -->|"queries domain records"| node_models
node_session -->|"reads and updates scores"| node_models
node_seed -->|"inserts records"| node_models
node_seed -->|"loads reference data"| node_reference

click node_app "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py"
click node_pages "https://github.com/lrondal/mathutrice/tree/course-2026-fallback-clean-branch/mathutrice/templates"
click node_auth "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py"
click node_teacher_upload "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py"
click node_chat "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/chatbot.py"
click node_session "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/session_generator.py"
click node_exercise_main "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/main.py"
click node_base_generator "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/base_generator.py"
click node_qcm "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/qcm_generator.py"
click node_qro "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/qro_generator.py"
click node_steps "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/steps_generator.py"
click node_fill_blanks "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/trous_generator.py"
click node_answer_check "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/verifier.py"
click node_gap_eval "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/lacune_evaluation/LLM_as_Evaluator.py"
click node_recommend "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/session_generator.py"
click node_reference "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/referentiel.py"
click node_seed "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/seed.py"
click node_models "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/models.py"
click node_database "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/database.py"
click node_llm_client "https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/llm_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_app,node_pages,node_auth,node_teacher_upload toneBlue
class node_chat,node_session,node_exercise_main,node_base_generator,node_qcm,node_qro,node_steps,node_fill_blanks toneAmber
class node_answer_check,node_gap_eval,node_recommend toneMint
class node_reference,node_seed,node_models,node_database toneRose
class node_entra,node_llm,node_llm_client,node_student,node_teacher toneIndigo
```

## Components

### Web application

- [FastAPI routes](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py): `mathutrice/app.py`
- [Web pages](https://github.com/lrondal/mathutrice/tree/course-2026-fallback-clean-branch/mathutrice/templates): `mathutrice/templates`
- [Sign-in flows](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py): `mathutrice/app.py`
- [Teacher PDF upload](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/app.py): `mathutrice/app.py`

### Practice and sessions

- [Free chat](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/chatbot.py): `mathutrice/fonctions_python/chatbot.py`
- [Session orchestration](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/session_generator.py): `mathutrice/fonctions_python/session_generator.py`
- [Exercise workflow](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/main.py): `mathutrice/fonctions_python/main.py`
- [Shared generation](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/base_generator.py): `mathutrice/fonctions_python/base_generator.py`
- [Multiple choice](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/qcm_generator.py): `mathutrice/fonctions_python/type_questions/qcm_generator.py`
- [Open answer](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/qro_generator.py): `mathutrice/fonctions_python/type_questions/qro_generator.py`
- [Step-by-step](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/steps_generator.py): `mathutrice/fonctions_python/type_questions/steps_generator.py`
- [Fill blanks](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/type_questions/trous_generator.py): `mathutrice/fonctions_python/type_questions/trous_generator.py`

### Assessment and guidance

- [Answer checking](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/verifier.py): `mathutrice/fonctions_python/verifier.py`
- [Competence gap evaluation](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/lacune_evaluation/LLM_as_Evaluator.py): `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`
- [Weakness recommendations](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/fonctions_python/session_generator.py): `mathutrice/fonctions_python/session_generator.py`

### Reference and persistence

- [Notions and competences](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/referentiel.py): `mathutrice/referentiel.py`
- [Reference data seeding](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/seed.py): `mathutrice/seed.py`
- [Domain models](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/models.py): `mathutrice/models.py`
- [SQL database](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/database.py): `mathutrice/database.py`

### External services

- **Microsoft Entra ID**
- **LLM endpoint**
- [Shared LLM client](https://github.com/lrondal/mathutrice/blob/course-2026-fallback-clean-branch/mathutrice/llm_client.py): `mathutrice/llm_client.py`

### Other components

- **Student**
- **Teacher / admin**

## Connections

- Student → FastAPI routes: uses (evidence: `README.md`)
- Teacher / admin → FastAPI routes: uses (evidence: `README.md`)
- FastAPI routes → Web pages: renders (evidence: `README.md`)
- FastAPI routes → Sign-in flows: handles sign-in (evidence: `mathutrice/app.py`)
- Sign-in flows → Microsoft Entra ID: authenticates (evidence: `README.md`)
- FastAPI routes → Teacher PDF upload: routes uploads (evidence: `mathutrice/app.py`)
- Student → Session orchestration: chooses notion (evidence: `README.md`)
- FastAPI routes → Session orchestration: requests sessions (evidence: `mathutrice/app.py`)
- Session orchestration → Exercise workflow: uses training logic (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Exercise workflow → Multiple choice: generates QCM (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise workflow → Open answer: generates open answers (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise workflow → Step-by-step: generates steps (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise workflow → Fill blanks: generates blanks (evidence: `mathutrice/fonctions_python/main.py`)
- Multiple choice → Shared generation: uses shared generation (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Open answer → Shared generation: uses shared generation (evidence: `mathutrice/fonctions_python/type_questions/qro_generator.py`)
- Step-by-step → Shared generation: uses shared generation (evidence: `mathutrice/fonctions_python/type_questions/steps_generator.py`)
- Fill blanks → Shared generation: uses shared generation (evidence: `mathutrice/fonctions_python/type_questions/trous_generator.py`)
- Multiple choice → Answer checking: verifies answers (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Open answer → Shared LLM client: judges answers
- Shared generation → Shared LLM client: calls (evidence: `mathutrice/fonctions_python/base_generator.py`)
- Shared LLM client → LLM endpoint: sends requests (evidence: `README.md`)
- FastAPI routes → Free chat: serves chat (evidence: `mathutrice/app.py`)
- Free chat → Shared LLM client: calls (evidence: `mathutrice/fonctions_python/chatbot.py`)
- FastAPI routes → Competence gap evaluation: requests diagnosis (evidence: `mathutrice/app.py`)
- Exercise workflow → Competence gap evaluation: diagnoses answers (evidence: `mathutrice/fonctions_python/main.py`)
- Competence gap evaluation → Shared LLM client: calls (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- Session orchestration → Weakness recommendations: selects next practice (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Session orchestration → Notions and competences: reads competences (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Competence gap evaluation → Notions and competences: reads competences (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- FastAPI routes → SQL database: opens sessions (evidence: `mathutrice/app.py`)
- FastAPI routes → Domain models: queries domain records (evidence: `mathutrice/app.py`)
- Session orchestration → Domain models: reads and updates scores (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Reference data seeding → Domain models: inserts records (evidence: `mathutrice/seed.py`)
- Reference data seeding → Notions and competences: loads reference data (evidence: `mathutrice/seed.py`)
