# lstiffel/mathutrice architecture

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

## Overview

MATHutrice is a web-based, LLM-assisted mathematics tutor. Students sign in, choose a notion, practise generated exercises, receive answer correction and feedback, and build per-competence scores used to recommend weaker areas; free chat is also available. Teachers and admins have separate pages, including PDF upload. The graph follows the documented route, generation, evaluation, and persistence responsibilities. Source excerpts are partial, so some feature links rely on README statements and the SOURCE INDEX rather than inspected route bodies.

Main entry points: [`mathutrice/app.py`](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py) (FastAPI routes), [`mathutrice/fonctions_python/main.py`](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py) (Exercise orchestration), [`mathutrice/fonctions_python/base_generator.py`](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py) (Generation core), [`mathutrice/referentiel.py`](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/referentiel.py) (Notions and competences)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_app["FastAPI routes<br/>[app.py]"]
  node_pages["Web pages"]
  node_teacher_upload["PDF upload<br/>[app.py]"]
end

subgraph group_learning["Learning workflow"]
  node_session_flow["Practice sessions"]
  node_test_flow["Exercise orchestration<br/>[main.py]"]
  node_chat["Free chat<br/>[chatbot.py]"]
end

subgraph group_content["Exercise generation"]
  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_gaps["Fill-in exercises<br/>[trous_generator.py]"]
  node_generator_core["Generation core<br/>[base_generator.py]"]
  node_answer_verifier["Math verification<br/>[verifier.py]"]
end

subgraph group_data["Reference and persistence"]
  node_referential["Notions and competences<br/>[referentiel.py]"]
  node_seed["Reference-data seeding<br/>[seed.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database["Database session<br/>[database.py]"]
end

subgraph group_integrations["LLM and evaluation"]
  node_gap_evaluator["Competency diagnosis"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

node_student(("Student"))
node_educator(("Teacher / admin"))
node_entra["Microsoft Entra ID"]
node_llm_endpoint["OpenAI-compatible endpoint"]
node_store[("Application database")]

node_student -->|"uses"| node_web_app
node_educator -->|"uses"| node_web_app
node_web_app -.->|"authenticates with"| node_entra
node_web_app -->|"renders"| node_pages
node_web_app -->|"serves upload"| node_teacher_upload
node_web_app -->|"gets sessions"| node_database
node_database -->|"connects to"| node_store
node_web_app -->|"queries"| node_models
node_web_app -->|"initializes data"| node_seed
node_seed -->|"inserts rows"| node_models
node_seed -->|"loads reference"| node_referential
node_web_app -->|"starts practice"| node_session_flow
node_session_flow -->|"reads and writes"| node_models
node_session_flow -->|"uses competencies"| node_referential
node_session_flow -->|"delegates generation"| node_test_flow
node_web_app -->|"generates exercises"| node_test_flow
node_test_flow -->|"dispatches to"| node_qcm
node_test_flow -->|"dispatches to"| node_qro
node_test_flow -->|"dispatches to"| node_steps
node_test_flow -->|"uses competencies"| node_referential
node_qcm -->|"uses"| node_generator_core
node_qro -->|"uses"| node_generator_core
node_steps -->|"uses"| node_generator_core
node_gaps -->|"uses"| node_generator_core
node_qcm -->|"verifies answers"| node_answer_verifier
node_generator_core -->|"calls"| node_llm_client
node_llm_client -->|"sends requests"| node_llm_endpoint
node_web_app -->|"handles chat"| node_chat
node_chat -->|"calls"| node_llm_client
node_web_app -->|"requests diagnosis"| node_gap_evaluator
node_test_flow -->|"diagnoses answers"| node_gap_evaluator
node_gap_evaluator -->|"uses competencies"| node_referential
node_gap_evaluator -->|"calls"| node_llm_client
node_web_app -->|"serves notion choices"| node_referential
node_web_app -->|"stores scores and history"| node_models
node_web_app -->|"accepts teacher PDFs"| node_teacher_upload

click node_web_app "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py"
click node_pages "https://github.com/lstiffel/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates"
click node_teacher_upload "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py"
click node_session_flow "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/session_generator.py"
click node_test_flow "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py"
click node_qcm "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qcm_generator.py"
click node_qro "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qro_generator.py"
click node_steps "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/steps_generator.py"
click node_gaps "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/trous_generator.py"
click node_generator_core "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py"
click node_answer_verifier "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/verifier.py"
click node_chat "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/chatbot.py"
click node_gap_evaluator "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/lacune_evaluation/LLM_as_Evaluator.py"
click node_llm_client "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/llm_client.py"
click node_referential "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/referentiel.py"
click node_seed "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/seed.py"
click node_models "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/models.py"
click node_database "https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/database.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_web_app,node_pages,node_teacher_upload toneBlue
class node_session_flow,node_test_flow,node_chat,node_store toneAmber
class node_qcm,node_qro,node_steps,node_gaps,node_generator_core,node_answer_verifier toneMint
class node_referential,node_seed,node_models,node_database toneRose
class node_gap_evaluator,node_llm_client,node_student,node_educator,node_entra,node_llm_endpoint toneIndigo
```

## Components

### Web application

- [FastAPI routes](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py): `mathutrice/app.py`
- [Web pages](https://github.com/lstiffel/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates): `mathutrice/templates`
- [PDF upload](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py): `mathutrice/app.py`

### Learning workflow

- [Practice sessions](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/session_generator.py): `mathutrice/fonctions_python/session_generator.py`
- [Exercise orchestration](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py): `mathutrice/fonctions_python/main.py`
- [Free chat](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/chatbot.py): `mathutrice/fonctions_python/chatbot.py`

### Exercise generation

- [Multiple choice](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qcm_generator.py): `mathutrice/fonctions_python/type_questions/qcm_generator.py`
- [Open answer](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qro_generator.py): `mathutrice/fonctions_python/type_questions/qro_generator.py`
- [Step-by-step](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/steps_generator.py): `mathutrice/fonctions_python/type_questions/steps_generator.py`
- [Fill-in exercises](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/trous_generator.py): `mathutrice/fonctions_python/type_questions/trous_generator.py`
- [Generation core](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py): `mathutrice/fonctions_python/base_generator.py`
- [Math verification](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/verifier.py): `mathutrice/fonctions_python/verifier.py`

### Reference and persistence

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

### LLM and evaluation

- [Competency diagnosis](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/lacune_evaluation/LLM_as_Evaluator.py): `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`
- [LLM client](https://github.com/lstiffel/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/llm_client.py): `mathutrice/llm_client.py`

### Other components

- **Student**
- **Teacher / admin**
- **Microsoft Entra ID**
- **OpenAI-compatible endpoint**
- **Application database**

## Connections

- Student → FastAPI routes: uses (evidence: `README.md`)
- Teacher / admin → FastAPI routes: uses (evidence: `README.md`)
- FastAPI routes → Microsoft Entra ID: authenticates with (evidence: `README.md`)
- FastAPI routes → Web pages: renders (evidence: `mathutrice/app.py`)
- FastAPI routes → PDF upload: serves upload (evidence: `mathutrice/app.py`)
- FastAPI routes → Database session: gets sessions (evidence: `mathutrice/app.py`)
- Database session → Application database: connects to (evidence: `mathutrice/database.py`)
- FastAPI routes → Domain models: queries (evidence: `mathutrice/app.py`)
- FastAPI routes → Reference-data seeding: initializes data (evidence: `mathutrice/app.py`)
- Reference-data seeding → Domain models: inserts rows (evidence: `mathutrice/seed.py`)
- Reference-data seeding → Notions and competences: loads reference (evidence: `mathutrice/seed.py`)
- FastAPI routes → Practice sessions: starts practice (evidence: `mathutrice/app.py`)
- Practice sessions → Domain models: reads and writes (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Practice sessions → Notions and competences: uses competencies (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Practice sessions → Exercise orchestration: delegates generation (evidence: `mathutrice/fonctions_python/session_generator.py`)
- FastAPI routes → Exercise orchestration: generates exercises (evidence: `mathutrice/app.py`)
- Exercise orchestration → Multiple choice: dispatches to (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Open answer: dispatches to (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Step-by-step: dispatches to (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Notions and competences: uses competencies (evidence: `mathutrice/fonctions_python/main.py`)
- Multiple choice → Generation core: uses (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Open answer → Generation core: uses (evidence: `mathutrice/fonctions_python/type_questions/qro_generator.py`)
- Step-by-step → Generation core: uses (evidence: `mathutrice/fonctions_python/type_questions/steps_generator.py`)
- Fill-in exercises → Generation core: uses (evidence: `mathutrice/fonctions_python/type_questions/trous_generator.py`)
- Multiple choice → Math verification: verifies answers (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Generation core → LLM client: calls (evidence: `mathutrice/fonctions_python/base_generator.py`)
- LLM client → OpenAI-compatible endpoint: sends requests (evidence: `README.md`)
- FastAPI routes → Free chat: handles chat (evidence: `mathutrice/app.py`)
- Free chat → LLM client: calls (evidence: `mathutrice/fonctions_python/chatbot.py`)
- FastAPI routes → Competency diagnosis: requests diagnosis (evidence: `mathutrice/app.py`)
- Exercise orchestration → Competency diagnosis: diagnoses answers (evidence: `mathutrice/fonctions_python/main.py`)
- Competency diagnosis → Notions and competences: uses competencies (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- Competency diagnosis → LLM client: calls (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- FastAPI routes → Notions and competences: serves notion choices (evidence: `mathutrice/app.py`)
- FastAPI routes → Domain models: stores scores and history (evidence: `README.md`)
- FastAPI routes → PDF upload: accepts teacher PDFs (evidence: `README.md`)
