# epf-mde/mathutrice architecture

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

## Overview

MATHutrice is a web-based LLM tutor for first-year mathematics. Students navigate learning modules, practise through generated exercises, and build skill progression; teachers also have an upload interface. The graph separates web routing, training orchestration, question formats, evaluation, and persistence. The README documents the home/module experience; sampled app excerpts and the SOURCE INDEX support several runtime links. Upload and some UI capabilities are visible only in documentation or partial route excerpts, so their internal wiring is not expanded.

Main entry points: [`mathutrice/app.py`](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/app.py) (Web routes), [`mathutrice/fonctions_python/main.py`](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/main.py) (Training and scoring), [`mathutrice/fonctions_python/base_generator.py`](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/base_generator.py) (Generation core), [`mathutrice/fonctions_python/session_generator.py`](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/session_generator.py) (Session planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web routes<br/>[app.py]"]
  node_home["Home and modules<br/>[index.html]"]
  node_sessionui["Training interface<br/>[session.html]"]
  node_uploadui["Teacher upload<br/>[upload.html]"]
  node_chatui["Chat interface<br/>[chat.html]"]
end

subgraph group_training["Training and assessment"]
  node_chatbot["Tutor chat<br/>[chatbot.py]"]
  node_sessiongen["Session planning"]
  node_trainingcore["Training and scoring<br/>[main.py]"]
  node_gap_eval["Gap diagnosis"]
end

subgraph group_content["Question generation"]
  node_basegen["Generation core<br/>[base_generator.py]"]
  node_qcm["Multiple choice<br/>[qcm_generator.py]"]
  node_qro["Open response<br/>[qro_generator.py]"]
  node_steps["Step exercises<br/>[steps_generator.py]"]
  node_gaps["Fill-in exercises<br/>[trous_generator.py]"]
  node_verifier["Math verification<br/>[verifier.py]"]
end

subgraph group_data["State and integrations"]
  node_llmclient["LLM client<br/>[llm_client.py]"]
  node_dbsession["Database sessions<br/>[database.py]"]
  node_models[("Learning records<br/>[models.py]")]
end

node_student(("Student"))
node_teacher(("Teacher"))
node_llmservice{{"OpenAI-compatible LLM"}}

node_student -->|"uses"| node_webapp
node_teacher -->|"uses"| node_webapp
node_webapp -->|"renders"| node_home
node_webapp -->|"renders"| node_sessionui
node_webapp -->|"renders"| node_uploadui
node_webapp -.->|"serves"| node_chatui
node_webapp -->|"uses"| node_dbsession
node_webapp -->|"queries"| node_models
node_webapp -->|"dispatches"| node_sessiongen
node_webapp -->|"dispatches"| node_trainingcore
node_webapp -->|"dispatches"| node_chatbot
node_webapp -->|"dispatches"| node_gap_eval
node_webapp -->|"uses"| node_chatbot
node_chatbot -->|"calls"| node_llmclient
node_sessiongen -->|"calls"| node_trainingcore
node_sessiongen -->|"uses"| node_basegen
node_sessiongen -->|"reads and writes"| node_models
node_trainingcore -->|"generates"| node_qcm
node_trainingcore -->|"generates"| node_qro
node_trainingcore -->|"generates"| node_steps
node_trainingcore -->|"diagnoses"| node_gap_eval
node_trainingcore -->|"updates scores"| node_basegen
node_qcm -->|"delegates to"| node_basegen
node_qro -->|"delegates to"| node_basegen
node_steps -->|"delegates to"| node_basegen
node_gaps -->|"delegates to"| node_basegen
node_qcm -->|"verifies with"| node_verifier
node_basegen -->|"calls"| node_llmclient
node_gap_eval -->|"reads reference"| node_trainingcore
node_gap_eval -->|"calls"| node_llmclient
node_llmclient -->|"sends prompts"| node_llmservice
node_dbsession -->|"persists"| node_models

click node_webapp "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/app.py"
click node_home "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/index.html"
click node_sessionui "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/session.html"
click node_uploadui "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/upload.html"
click node_chatui "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/chat.html"
click node_chatbot "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/chatbot.py"
click node_sessiongen "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/session_generator.py"
click node_trainingcore "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/main.py"
click node_gap_eval "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/lacune_evaluation/LLM_as_Evaluator.py"
click node_basegen "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/base_generator.py"
click node_qcm "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/qcm_generator.py"
click node_qro "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/qro_generator.py"
click node_steps "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/steps_generator.py"
click node_gaps "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/trous_generator.py"
click node_verifier "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/verifier.py"
click node_llmclient "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/llm_client.py"
click node_dbsession "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/database.py"
click node_models "https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/models.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_webapp,node_home,node_sessionui,node_uploadui,node_chatui toneBlue
class node_chatbot,node_sessiongen,node_trainingcore,node_gap_eval toneAmber
class node_basegen,node_qcm,node_qro,node_steps,node_gaps,node_verifier toneMint
class node_llmclient,node_dbsession,node_models toneRose
class node_student,node_teacher,node_llmservice toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/app.py): `mathutrice/app.py`
- [Home and modules](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/index.html): `mathutrice/templates/index.html`
- [Training interface](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/session.html): `mathutrice/templates/session.html`
- [Teacher upload](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/upload.html): `mathutrice/templates/upload.html`
- [Chat interface](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/templates/chat.html): `mathutrice/templates/chat.html`

### Training and assessment

- [Tutor chat](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/chatbot.py): `mathutrice/fonctions_python/chatbot.py`
- [Session planning](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/session_generator.py): `mathutrice/fonctions_python/session_generator.py`
- [Training and scoring](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/main.py): `mathutrice/fonctions_python/main.py`
- [Gap diagnosis](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/lacune_evaluation/LLM_as_Evaluator.py): `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`

### Question generation

- [Generation core](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/base_generator.py): `mathutrice/fonctions_python/base_generator.py`
- [Multiple choice](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/qcm_generator.py): `mathutrice/fonctions_python/type_questions/qcm_generator.py`
- [Open response](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/qro_generator.py): `mathutrice/fonctions_python/type_questions/qro_generator.py`
- [Step exercises](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/steps_generator.py): `mathutrice/fonctions_python/type_questions/steps_generator.py`
- [Fill-in exercises](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/type_questions/trous_generator.py): `mathutrice/fonctions_python/type_questions/trous_generator.py`
- [Math verification](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/verifier.py): `mathutrice/fonctions_python/verifier.py`

### State and integrations

- [LLM client](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/fonctions_python/llm_client.py): `mathutrice/fonctions_python/llm_client.py`
- [Database sessions](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/database.py): `mathutrice/database.py`
- [Learning records](https://github.com/epf-mde/mathutrice/blob/course-2026/mathutrice/models.py): `mathutrice/models.py`

### Other components

- **Student**
- **Teacher**
- **OpenAI-compatible LLM**

## Connections

- Student → Web routes: uses (evidence: `README.md`)
- Teacher → Web routes: uses (evidence: `mathutrice/app.py`)
- Web routes → Home and modules: renders (evidence: `README.md`)
- Web routes → Training interface: renders (evidence: `mathutrice/app.py`)
- Web routes → Teacher upload: renders (evidence: `mathutrice/app.py`)
- Web routes → Chat interface: serves
- Web routes → Database sessions: uses (evidence: `mathutrice/app.py`)
- Web routes → Learning records: queries (evidence: `mathutrice/app.py`)
- Web routes → Session planning: dispatches (evidence: `mathutrice/app.py`)
- Web routes → Training and scoring: dispatches (evidence: `mathutrice/app.py`)
- Web routes → Tutor chat: dispatches (evidence: `mathutrice/app.py`)
- Web routes → Gap diagnosis: dispatches (evidence: `mathutrice/app.py`)
- Web routes → Tutor chat: uses (evidence: `mathutrice/fonctions_python/chatbot.py`)
- Tutor chat → LLM client: calls (evidence: `mathutrice/fonctions_python/chatbot.py`)
- Session planning → Training and scoring: calls (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Session planning → Generation core: uses (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Session planning → Learning records: reads and writes (evidence: `mathutrice/fonctions_python/session_generator.py`)
- Training and scoring → Multiple choice: generates (evidence: `mathutrice/fonctions_python/main.py`)
- Training and scoring → Open response: generates (evidence: `mathutrice/fonctions_python/main.py`)
- Training and scoring → Step exercises: generates (evidence: `mathutrice/fonctions_python/main.py`)
- Training and scoring → Gap diagnosis: diagnoses (evidence: `mathutrice/fonctions_python/main.py`)
- Training and scoring → Generation core: updates scores (evidence: `mathutrice/fonctions_python/main.py`)
- Multiple choice → Generation core: delegates to (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Open response → Generation core: delegates to (evidence: `mathutrice/fonctions_python/type_questions/qro_generator.py`)
- Step exercises → Generation core: delegates to (evidence: `mathutrice/fonctions_python/type_questions/steps_generator.py`)
- Fill-in exercises → Generation core: delegates to (evidence: `mathutrice/fonctions_python/type_questions/trous_generator.py`)
- Multiple choice → Math verification: verifies with (evidence: `mathutrice/fonctions_python/type_questions/qcm_generator.py`)
- Generation core → LLM client: calls (evidence: `mathutrice/fonctions_python/base_generator.py`)
- Gap diagnosis → Training and scoring: reads reference (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- Gap diagnosis → LLM client: calls (evidence: `mathutrice/lacune_evaluation/LLM_as_Evaluator.py`)
- LLM client → OpenAI-compatible LLM: sends prompts (evidence: `mathutrice/fonctions_python/llm_client.py`)
- Database sessions → Learning records: persists (evidence: `mathutrice/app.py`)
