# mawandu/assistant-web-educatif architecture

> Architecture diagram of the GitHub repository mawandu/assistant-web-educatif, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mawandu/assistant-web-educatif
- Repository: https://github.com/mawandu/assistant-web-educatif

## Overview

This is a full-stack educational assistant: students ask questions about uploaded course PDFs and receive answers with document/page citations; teachers and administrators manage access and documents. The main path runs from the React chat through the questions API, retrieval, and answer generation. A separate teacher upload path extracts and indexes PDF text. Authentication, feedback, and document metadata support these workflows. The README describes local Ollama, while the sampled answer-generation service uses Groq/OpenAI/Google; the exact runtime wiring for Ollama is not established by the excerpts.

Main entry points: [`backend/api/routes/documents.py`](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/documents.py) (Documents API), [`backend/services/question_handler.py`](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/question_handler.py) (Question handler), [`backend/api/routes/users.py`](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/users.py) (Users API), [`frontend/src/main.jsx`](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/main.jsx) (Web routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_web["Chat interface<br/>[App.jsx]"]
  node_admin["Admin panel<br/>[Admin.jsx]"]
  node_login["Login page<br/>[LoginPage.jsx]"]
  node_auth_ui["Auth context<br/>[AuthContext.jsx]"]
  node_web_routes["Web routing<br/>[main.jsx]"]
end

subgraph group_api["API and access"]
  node_api_app["API application<br/>[main.py]"]
  node_questions_api["Questions API<br/>[questions.py]"]
  node_documents_api["Documents API<br/>[documents.py]"]
  node_users_api["Users API<br/>[users.py]"]
  node_feedback_api["Feedback API<br/>[feedback.py]"]
  node_access["Auth dependencies<br/>[dependencies.py]"]
  node_security["Token security<br/>[security.py]"]
end

subgraph group_knowledge["Document knowledge"]
  node_processor["PDF processing"]
  node_vectors["Vector retrieval<br/>[vector_store.py]"]
end

subgraph group_answering["Answer generation"]
  node_handler["Question handler"]
  node_cache["Answer cache<br/>[cache_manager.py]"]
  node_llm["Answer generation<br/>[llm_service.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
end

subgraph group_state["Persistent state"]
  node_document_model["Document metadata<br/>[document.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_feedback_model["Feedback records<br/>[feedback.py]"]
  node_question_model["Question records<br/>[question.py]"]
  node_sql_db[("PostgreSQL metadata<br/>[database.py]")]
end

node_student(("Student"))
node_teacher(("Teacher"))
node_chroma[("ChromaDB vectors")]
node_llm_providers{{"LLM providers"}}

node_student -->|"asks questions"| node_web
node_teacher -->|"manages content"| node_admin
node_web_routes -->|"routes to"| node_web
node_web_routes -->|"routes to"| node_admin
node_web_routes -->|"routes to"| node_login
node_web_routes -->|"provides auth"| node_auth_ui
node_login -->|"logs in through"| node_auth_ui
node_web -->|"posts questions"| node_questions_api
node_web -->|"posts ratings"| node_feedback_api
node_auth_ui -->|"requests token"| node_users_api
node_api_app -->|"registers route"| node_questions_api
node_api_app -->|"registers route"| node_documents_api
node_api_app -->|"registers route"| node_users_api
node_api_app -->|"registers route"| node_feedback_api
node_questions_api -->|"delegates questions"| node_handler
node_documents_api -->|"extracts and splits"| node_processor
node_documents_api -->|"indexes chunks"| node_vectors
node_documents_api -->|"creates metadata"| node_document_model
node_documents_api -->|"checks access"| node_access
node_users_api -->|"manages accounts"| node_user_model
node_users_api -->|"uses password security"| node_security
node_feedback_api -->|"stores feedback"| node_feedback_model
node_questions_api -->|"uses question model"| node_question_model
node_access -->|"loads user"| node_user_model
node_access -->|"decodes token"| node_security
node_handler -->|"checks and saves"| node_cache
node_handler -->|"retrieves chunks"| node_vectors
node_handler -->|"generates answer"| node_llm
node_handler -->|"resolves citations"| node_document_model
node_llm -->|"calls provider"| node_llm_providers
node_vectors -->|"reads and writes vectors"| node_chroma
node_documents_api -->|"uses database session"| node_sql_db
node_users_api -->|"uses database session"| node_sql_db
node_feedback_api -->|"uses database session"| node_sql_db
node_handler -->|"queries metadata"| node_sql_db
node_ollama_client -.->|"provider integration"| node_llm_providers

click node_web "https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/App.jsx"
click node_admin "https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/Admin.jsx"
click node_login "https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/pages/LoginPage.jsx"
click node_auth_ui "https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/context/AuthContext.jsx"
click node_web_routes "https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/main.jsx"
click node_api_app "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/main.py"
click node_questions_api "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/questions.py"
click node_documents_api "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/documents.py"
click node_users_api "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/users.py"
click node_feedback_api "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/feedback.py"
click node_access "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/dependencies.py"
click node_security "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/utils/security.py"
click node_processor "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/document_processor.py"
click node_vectors "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/vector_store.py"
click node_handler "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/question_handler.py"
click node_cache "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/cache_manager.py"
click node_llm "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/llm_service.py"
click node_ollama_client "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/ollama_client.py"
click node_document_model "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/document.py"
click node_user_model "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/user.py"
click node_feedback_model "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/feedback.py"
click node_question_model "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/question.py"
click node_sql_db "https://github.com/mawandu/assistant-web-educatif/blob/main/backend/config/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,node_admin,node_login,node_auth_ui,node_web_routes toneBlue
class node_api_app,node_questions_api,node_documents_api,node_users_api,node_feedback_api,node_access,node_security,node_chroma toneAmber
class node_processor,node_vectors toneMint
class node_handler,node_cache,node_llm,node_ollama_client toneRose
class node_document_model,node_user_model,node_feedback_model,node_question_model,node_sql_db,node_student,node_teacher,node_llm_providers toneIndigo
```

## Components

### Web interface

- [Chat interface](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Admin panel](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/Admin.jsx): `frontend/src/Admin.jsx`
- [Login page](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`
- [Auth context](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Web routing](https://github.com/mawandu/assistant-web-educatif/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### API and access

- [API application](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/main.py): `backend/main.py`
- [Questions API](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/questions.py): `backend/api/routes/questions.py`
- [Documents API](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/documents.py): `backend/api/routes/documents.py`
- [Users API](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/users.py): `backend/api/routes/users.py`
- [Feedback API](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/routes/feedback.py): `backend/api/routes/feedback.py`
- [Auth dependencies](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/api/dependencies.py): `backend/api/dependencies.py`
- [Token security](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/utils/security.py): `backend/utils/security.py`

### Document knowledge

- [PDF processing](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/document_processor.py): `backend/services/document_processor.py`
- [Vector retrieval](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/vector_store.py): `backend/services/vector_store.py`

### Answer generation

- [Question handler](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/question_handler.py): `backend/services/question_handler.py`
- [Answer cache](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/cache_manager.py): `backend/services/cache_manager.py`
- [Answer generation](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/llm_service.py): `backend/services/llm_service.py`
- [Ollama client](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/services/ollama_client.py): `backend/services/ollama_client.py`

### Persistent state

- [Document metadata](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/document.py): `backend/models/document.py`
- [User records](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/user.py): `backend/models/user.py`
- [Feedback records](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/feedback.py): `backend/models/feedback.py`
- [Question records](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/models/question.py): `backend/models/question.py`
- [PostgreSQL metadata](https://github.com/mawandu/assistant-web-educatif/blob/main/backend/config/database.py): `backend/config/database.py`

### Other components

- **Student**
- **Teacher**
- **ChromaDB vectors**
- **LLM providers**

## Connections

- Student → Chat interface: asks questions (evidence: `frontend/src/App.jsx`)
- Teacher → Admin panel: manages content (evidence: `README.md`)
- Web routing → Chat interface: routes to (evidence: `frontend/src/main.jsx`)
- Web routing → Admin panel: routes to (evidence: `frontend/src/main.jsx`)
- Web routing → Login page: routes to (evidence: `frontend/src/main.jsx`)
- Web routing → Auth context: provides auth (evidence: `frontend/src/main.jsx`)
- Login page → Auth context: logs in through (evidence: `frontend/src/pages/LoginPage.jsx`)
- Chat interface → Questions API: posts questions (evidence: `frontend/src/App.jsx`)
- Chat interface → Feedback API: posts ratings (evidence: `frontend/src/App.jsx`)
- Auth context → Users API: requests token (evidence: `frontend/src/context/AuthContext.jsx`)
- API application → Questions API: registers route (evidence: `backend/main.py`)
- API application → Documents API: registers route (evidence: `backend/main.py`)
- API application → Users API: registers route (evidence: `backend/main.py`)
- API application → Feedback API: registers route (evidence: `backend/main.py`)
- Questions API → Question handler: delegates questions (evidence: `backend/api/routes/questions.py`)
- Documents API → PDF processing: extracts and splits (evidence: `backend/api/routes/documents.py`)
- Documents API → Vector retrieval: indexes chunks (evidence: `backend/api/routes/documents.py`)
- Documents API → Document metadata: creates metadata (evidence: `backend/api/routes/documents.py`)
- Documents API → Auth dependencies: checks access (evidence: `backend/api/routes/documents.py`)
- Users API → User records: manages accounts (evidence: `backend/api/routes/users.py`)
- Users API → Token security: uses password security (evidence: `backend/api/routes/users.py`)
- Feedback API → Feedback records: stores feedback (evidence: `backend/api/routes/feedback.py`)
- Questions API → Question records: uses question model (evidence: `backend/api/routes/questions.py`)
- Auth dependencies → User records: loads user (evidence: `backend/api/dependencies.py`)
- Auth dependencies → Token security: decodes token (evidence: `backend/api/dependencies.py`)
- Question handler → Answer cache: checks and saves (evidence: `backend/services/question_handler.py`)
- Question handler → Vector retrieval: retrieves chunks (evidence: `backend/services/question_handler.py`)
- Question handler → Answer generation: generates answer (evidence: `backend/services/question_handler.py`)
- Question handler → Document metadata: resolves citations (evidence: `backend/services/question_handler.py`)
- Answer generation → LLM providers: calls provider (evidence: `backend/services/llm_service.py`)
- Vector retrieval → ChromaDB vectors: reads and writes vectors (evidence: `backend/services/vector_store.py`)
- Documents API → PostgreSQL metadata: uses database session
- Users API → PostgreSQL metadata: uses database session
- Feedback API → PostgreSQL metadata: uses database session
- Question handler → PostgreSQL metadata: queries metadata (evidence: `backend/services/question_handler.py`)
- Ollama client → LLM providers: provider integration
