# amandot/questai architecture

> Architecture diagram of the GitHub repository amandot/questai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amandot/questai
- Repository: https://github.com/amandot/questai

## Overview

QuEstAI takes an educator or learner from account access through quiz creation, answering, feedback, and printable export. The documented generation stages extract page-aware text, analyze it, and create question types with Bloom levels and source context; quizzes and user data are persisted with user isolation. The graph includes the API and UI entry points plus the key internal services. Quiz-router implementation was not sampled, so its documented responsibilities are shown without assuming its internal call sequence.

Main entry points: [`frontend/src/services/api.js`](https://github.com/amandot/questai/blob/main/frontend/src/services/api.js) (HTTP API client), [`backend/app/routers/quiz.py`](https://github.com/amandot/questai/blob/main/backend/app/routers/quiz.py) (Quiz endpoints), [`backend/app/core/database.py`](https://github.com/amandot/questai/blob/main/backend/app/core/database.py) (Relational database), [`backend/app/main.py`](https://github.com/amandot/questai/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["Route and access control<br/>[App.jsx]"]
  node_authui["Auth state and forms<br/>[AuthContext.jsx]"]
  node_dashboard["Quiz dashboard<br/>[DashboardPage.jsx]"]
  node_generator["Quiz setup<br/>[QuizGenerator.jsx]"]
  node_taker["Quiz answering<br/>[QuizTaker.jsx]"]
  node_results["Results and feedback<br/>[QuizResults.jsx]"]
  node_client["HTTP API client<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_entry["FastAPI application<br/>[main.py]"]
  node_authrouter["Auth endpoints<br/>[auth.py]"]
  node_quizrouter["Quiz endpoints<br/>[quiz.py]"]
  node_identity["Token identity checks<br/>[auth.py]"]
  node_security["Password and JWT security<br/>[security.py]"]
end

subgraph group_generation["Question generation"]
  node_nlp["PDF and NLP generation<br/>[nlp_service.py]"]
end

subgraph group_data["Quiz data and export"]
  node_models["User, quiz, question models"]
  node_database[("Relational database<br/>[database.py]")]
  node_export["Word exam export<br/>[export_service.py]"]
end

node_educator(("Educator / learner"))

node_educator -->|"uses"| node_app
node_app -->|"provides auth"| node_authui
node_authui -->|"requests auth"| node_client
node_dashboard -->|"loads quizzes"| node_client
node_generator -->|"submits source"| node_client
node_taker -->|"loads and submits"| node_client
node_results -->|"loads and exports"| node_client
node_client -->|"HTTP requests"| node_entry
node_entry -->|"dispatches auth"| node_authrouter
node_entry -->|"dispatches quizzes"| node_quizrouter
node_authrouter -->|"hashes and issues tokens"| node_security
node_authrouter -->|"reads and writes users"| node_database
node_quizrouter -->|"checks identity"| node_identity
node_identity -->|"verifies token"| node_security
node_identity -->|"loads user"| node_database
node_quizrouter -->|"generates questions"| node_nlp
node_quizrouter -->|"reads and writes quizzes"| node_database
node_quizrouter -->|"requests document"| node_export
node_export -->|"reads quiz questions"| node_models
node_database -->|"persists records"| node_models

click node_app "https://github.com/amandot/questai/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/amandot/questai/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_dashboard "https://github.com/amandot/questai/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_generator "https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizGenerator.jsx"
click node_taker "https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizTaker.jsx"
click node_results "https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizResults.jsx"
click node_client "https://github.com/amandot/questai/blob/main/frontend/src/services/api.js"
click node_entry "https://github.com/amandot/questai/blob/main/backend/app/main.py"
click node_authrouter "https://github.com/amandot/questai/blob/main/backend/app/routers/auth.py"
click node_quizrouter "https://github.com/amandot/questai/blob/main/backend/app/routers/quiz.py"
click node_identity "https://github.com/amandot/questai/blob/main/backend/app/core/auth.py"
click node_security "https://github.com/amandot/questai/blob/main/backend/app/core/security.py"
click node_nlp "https://github.com/amandot/questai/blob/main/backend/app/services/nlp_service.py"
click node_models "https://github.com/amandot/questai/tree/main/backend/app/models"
click node_database "https://github.com/amandot/questai/blob/main/backend/app/core/database.py"
click node_export "https://github.com/amandot/questai/blob/main/backend/app/services/export_service.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_authui,node_dashboard,node_generator,node_taker,node_results,node_client toneBlue
class node_entry,node_authrouter,node_quizrouter,node_identity,node_security toneAmber
class node_nlp toneMint
class node_models,node_database,node_export toneRose
class node_educator toneIndigo
```

## Components

### Web application

- [Route and access control](https://github.com/amandot/questai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state and forms](https://github.com/amandot/questai/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [Quiz dashboard](https://github.com/amandot/questai/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`
- [Quiz setup](https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizGenerator.jsx): `frontend/src/pages/QuizGenerator.jsx`
- [Quiz answering](https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizTaker.jsx): `frontend/src/pages/QuizTaker.jsx`
- [Results and feedback](https://github.com/amandot/questai/blob/main/frontend/src/pages/QuizResults.jsx): `frontend/src/pages/QuizResults.jsx`
- [HTTP API client](https://github.com/amandot/questai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and identity

- [FastAPI application](https://github.com/amandot/questai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth endpoints](https://github.com/amandot/questai/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Quiz endpoints](https://github.com/amandot/questai/blob/main/backend/app/routers/quiz.py): `backend/app/routers/quiz.py`
- [Token identity checks](https://github.com/amandot/questai/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Password and JWT security](https://github.com/amandot/questai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Question generation

- [PDF and NLP generation](https://github.com/amandot/questai/blob/main/backend/app/services/nlp_service.py): `backend/app/services/nlp_service.py`

### Quiz data and export

- [User, quiz, question models](https://github.com/amandot/questai/tree/main/backend/app/models): `backend/app/models`
- [Relational database](https://github.com/amandot/questai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Word exam export](https://github.com/amandot/questai/blob/main/backend/app/services/export_service.py): `backend/app/services/export_service.py`

### Other components

- **Educator / learner**

## Connections

- Educator / learner → Route and access control: uses
- Route and access control → Auth state and forms: provides auth
- Auth state and forms → HTTP API client: requests auth
- Quiz dashboard → HTTP API client: loads quizzes
- Quiz setup → HTTP API client: submits source
- Quiz answering → HTTP API client: loads and submits
- Results and feedback → HTTP API client: loads and exports
- HTTP API client → FastAPI application: HTTP requests
- FastAPI application → Auth endpoints: dispatches auth
- FastAPI application → Quiz endpoints: dispatches quizzes
- Auth endpoints → Password and JWT security: hashes and issues tokens
- Auth endpoints → Relational database: reads and writes users
- Quiz endpoints → Token identity checks: checks identity
- Token identity checks → Password and JWT security: verifies token
- Token identity checks → Relational database: loads user
- Quiz endpoints → PDF and NLP generation: generates questions
- Quiz endpoints → Relational database: reads and writes quizzes
- Quiz endpoints → Word exam export: requests document
- Word exam export → User, quiz, question models: reads quiz questions
- Relational database → User, quiz, question models: persists records