# julescinc/mathutrice architecture

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

## Overview

MATHutrice is a role-based web tutor for first-year mathematics practice. A student signs in, selects a notion, receives generated exercises, submits answers for correction, and builds competence scores used to recommend further practice. The application also offers free chat and teacher/admin pages, including PDF upload. The graph includes the documented product branches, but source excerpts are partial; edges rely on shown calls, SOURCE INDEX references, or README statements, and unsampled details are not inferred.

Main entry points: [`mathutrice/app.py`](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py) (Web routes), [`mathutrice/fonctions_python/main.py`](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py) (Exercise orchestration), [`mathutrice/fonctions_python/base_generator.py`](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py) (Generation core), [`mathutrice/fonctions_python/session_generator.py`](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/session_generator.py) (Practice sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Web routes<br/>[app.py]"]
  node_student_pages["Student pages"]
  node_teacher_pages["Teacher pages"]
  node_chat["Free chat<br/>[chatbot.py]"]
  node_pdf_upload["PDF upload<br/>[app.py]"]
end

subgraph group_learning["Practice and assessment"]
  node_session["Practice sessions"]
  node_exercise_flow["Exercise orchestration<br/>[main.py]"]
  node_base_gen["Generation core<br/>[base_generator.py]"]
  node_qcm["Multiple choice<br/>[qcm_generator.py]"]
  node_qro["Open answer<br/>[qro_generator.py]"]
  node_steps["Step exercises<br/>[steps_generator.py]"]
  node_holes["Fill blanks<br/>[trous_generator.py]"]
  node_verifier["Math verification<br/>[verifier.py]"]
  node_gap_eval["Gap diagnosis"]
end

subgraph group_knowledge["Learning domain"]
  node_referentiel["Notions and skills<br/>[referentiel.py]"]
end

subgraph group_persistence["Persistence and LLM"]
  node_models[("Learning records<br/>[models.py]")]
  node_database[("Database session<br/>[database.py]")]
  node_seed["Reference-data seed<br/>[seed.py]"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

node_student(("Student"))
node_teacher(("Teacher / admin"))
node_llm_service{{"OpenAI-compatible LLM"}}

node_student -->|"uses"| node_app
node_teacher -->|"uses"| node_app
node_app -->|"renders"| node_student_pages
node_app -->|"renders"| node_teacher_pages
node_app -->|"requests sessions"| node_session
node_app -->|"uses chat"| node_chat
node_app -->|"requests diagnosis"| node_gap_eval
node_app -->|"handles uploads"| node_pdf_upload
node_app -->|"gets sessions"| node_database
node_app -->|"queries records"| node_models
node_session -->|"reads and updates"| node_models
node_session -->|"uses skills"| node_referentiel
node_session -->|"generates exercises"| node_exercise_flow
node_exercise_flow -->|"dispatches"| node_qcm
node_exercise_flow -->|"dispatches"| node_qro
node_exercise_flow -->|"dispatches"| node_steps
node_exercise_flow -->|"diagnoses answers"| node_gap_eval
node_exercise_flow -->|"uses skills"| node_referentiel
node_qcm -->|"uses generation"| node_base_gen
node_qro -->|"uses generation"| node_base_gen
node_steps -->|"uses generation"| node_base_gen
node_holes -->|"uses generation"| node_base_gen
node_qcm -->|"checks answers"| node_verifier
node_base_gen -->|"calls"| node_llm_client
node_gap_eval -->|"uses skills"| node_referentiel
node_gap_eval -->|"calls"| node_llm_client
node_chat -->|"uses"| node_llm_client
node_llm_client -->|"sends prompts"| node_llm_service
node_seed -->|"inserts reference data"| node_models
node_seed -->|"loads reference data"| node_referentiel
node_app -->|"initializes data"| node_seed

click node_app "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py"
click node_student_pages "https://github.com/julescinc/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates"
click node_teacher_pages "https://github.com/julescinc/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates"
click node_chat "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/chatbot.py"
click node_session "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/session_generator.py"
click node_exercise_flow "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py"
click node_base_gen "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py"
click node_qcm "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qcm_generator.py"
click node_qro "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qro_generator.py"
click node_steps "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/steps_generator.py"
click node_holes "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/trous_generator.py"
click node_verifier "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/verifier.py"
click node_gap_eval "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/lacune_evaluation/LLM_as_Evaluator.py"
click node_referentiel "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/referentiel.py"
click node_models "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/models.py"
click node_database "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/database.py"
click node_seed "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/seed.py"
click node_llm_client "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/llm_client.py"
click node_pdf_upload "https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.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_student_pages,node_teacher_pages,node_chat,node_pdf_upload toneBlue
class node_session,node_exercise_flow,node_base_gen,node_qcm,node_qro,node_steps,node_holes,node_verifier,node_gap_eval toneAmber
class node_referentiel toneMint
class node_models,node_database,node_seed,node_llm_client toneRose
class node_student,node_teacher,node_llm_service toneIndigo
```

## Components

### Web application

- [Web routes](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py): `mathutrice/app.py`
- [Student pages](https://github.com/julescinc/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates): `mathutrice/templates`
- [Teacher pages](https://github.com/julescinc/mathutrice/tree/course-2026-fallback-clean-bench/mathutrice/templates): `mathutrice/templates`
- [Free chat](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/chatbot.py): `mathutrice/fonctions_python/chatbot.py`
- [PDF upload](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/app.py): `mathutrice/app.py`

### Practice and assessment

- [Practice sessions](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/session_generator.py): `mathutrice/fonctions_python/session_generator.py`
- [Exercise orchestration](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/main.py): `mathutrice/fonctions_python/main.py`
- [Generation core](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/base_generator.py): `mathutrice/fonctions_python/base_generator.py`
- [Multiple choice](https://github.com/julescinc/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/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/qro_generator.py): `mathutrice/fonctions_python/type_questions/qro_generator.py`
- [Step exercises](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/steps_generator.py): `mathutrice/fonctions_python/type_questions/steps_generator.py`
- [Fill blanks](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/type_questions/trous_generator.py): `mathutrice/fonctions_python/type_questions/trous_generator.py`
- [Math verification](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/fonctions_python/verifier.py): `mathutrice/fonctions_python/verifier.py`
- [Gap diagnosis](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/lacune_evaluation/LLM_as_Evaluator.py): `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`

### Learning domain

- [Notions and skills](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/referentiel.py): `mathutrice/referentiel.py`

### Persistence and LLM

- [Learning records](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/models.py): `mathutrice/models.py`
- [Database session](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/database.py): `mathutrice/database.py`
- [Reference-data seed](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/seed.py): `mathutrice/seed.py`
- [LLM client](https://github.com/julescinc/mathutrice/blob/course-2026-fallback-clean-bench/mathutrice/llm_client.py): `mathutrice/llm_client.py`

### Other components

- **Student**
- **Teacher / admin**
- **OpenAI-compatible LLM**

## Connections

- Student → Web routes: uses (evidence: `README.md`)
- Teacher / admin → Web routes: uses (evidence: `README.md`)
- Web routes → Student pages: renders (evidence: `mathutrice/app.py`)
- Web routes → Teacher pages: renders (evidence: `mathutrice/app.py`)
- Web routes → Practice sessions: requests sessions (evidence: `mathutrice/app.py`)
- Web routes → Free chat: uses chat (evidence: `mathutrice/app.py`)
- Web routes → Gap diagnosis: requests diagnosis (evidence: `mathutrice/app.py`)
- Web routes → PDF upload: handles uploads (evidence: `README.md`)
- Web routes → Database session: gets sessions (evidence: `mathutrice/app.py`)
- Web routes → Learning records: queries records (evidence: `mathutrice/app.py`)
- Practice sessions → Learning records: reads and updates (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Practice sessions → Notions and skills: uses skills (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Practice sessions → Exercise orchestration: generates exercises (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Exercise orchestration → Multiple choice: dispatches (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Open answer: dispatches (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Step exercises: dispatches (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Gap diagnosis: diagnoses answers (evidence: `mathutrice/fonctions_python/main.py`)
- Exercise orchestration → Notions and skills: uses skills (evidence: `mathutrice/fonctions_python/main.py`)
- Multiple choice → Generation core: uses generation (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Open answer → Generation core: uses generation (evidence: `mathutrice/fonctions_python/type_questions/qro_generator.py`)
- Step exercises → Generation core: uses generation (evidence: `mathutrice/fonctions_python/type_questions/steps_generator.py`)
- Fill blanks → Generation core: uses generation (evidence: `mathutrice/fonctions_python/type_questions/trous_generator.py`)
- Multiple choice → Math verification: checks answers (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Generation core → LLM client: calls (evidence: `mathutrice/fonctions_python/base_generator.py`)
- Gap diagnosis → Notions and skills: uses skills (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- Gap diagnosis → LLM client: calls (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- Free chat → LLM client: uses (evidence: `mathutrice/fonctions_python/chatbot.py`)
- LLM client → OpenAI-compatible LLM: sends prompts (evidence: `README.md`)
- Reference-data seed → Learning records: inserts reference data (evidence: `mathutrice/seed.py`)
- Reference-data seed → Notions and skills: loads reference data (evidence: `mathutrice/seed.py`)
- Web routes → Reference-data seed: initializes data (evidence: `mathutrice/app.py`)
