# abdelhak-elgo/quizgen architecture

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

- Interactive diagram: https://gitdiagram.com/abdelhak-elgo/quizgen
- Repository: https://github.com/abdelhak-elgo/quizgen

## Overview

QuizGen turns teacher-uploaded course PDFs into editable quizzes, then supports publishing sessions for students, grading attempts, analytics, and LMS exports. The principal path is document ingestion → asynchronous NLP generation → teacher review/publication → student session and results. The README documents these product flows; source excerpts substantiate selected backend session, quiz-export, and NLP internals. Other unsampled subsystem connections are omitted rather than inferred.

Main entry points: [`nlp-service/app/tasks.py`](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/tasks.py) (Generation tasks), [`backend/src/main/java/ma/quizgen/controller/QuizController.java`](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/QuizController.java) (Quiz API), [`backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java`](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java) (Session workflow), [`artifacts/frontend/src/App.tsx`](https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/App.tsx) (Role-based app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Role-based web app"]
  node_web["Role-based app<br/>[App.tsx]"]
  node_login["Authentication UI<br/>[auth-provider.tsx]"]
  node_teacher_ui["Quiz authoring<br/>[quiz-editor.tsx]"]
  node_student_ui["Student exams<br/>[exam.tsx]"]
end

subgraph group_api["Quiz platform API"]
  node_quiz_api["Quiz API"]
  node_quiz_service["Quiz workflow<br/>[QuizService.java]"]
  node_documents["Document management"]
  node_exports["LMS exports"]
  node_quiz_entity["Quiz state<br/>[Quiz.java]"]
end

subgraph group_generation["Async NLP generation"]
  node_nlp_api["NLP service API<br/>[main.py]"]
  node_generation_tasks["Generation tasks<br/>[tasks.py]"]
  node_pdf_processing["PDF and NLP analysis<br/>[nlp_pipeline.py]"]
  node_rag[("Semantic retrieval<br/>[rag_store.py]")]
  node_llm["LLM generation<br/>[llm_client.py]"]
end

subgraph group_learning["Sessions and assessment"]
  node_session_api["Session API"]
  node_session_service["Session workflow"]
  node_session_entity["Session state<br/>[Session.java]"]
  node_attempt_entity["Attempt state<br/>[Attempt.java]"]
end

subgraph group_integrations["Identity and services"]
  node_keycloak["Keycloak identity"]
  node_minio[("MinIO document storage")]
  node_redis["Redis task broker"]
  node_llm_provider["Configured LLM provider"]
  node_postgres[("PostgreSQL")]
end

node_teacher(("Teacher"))
node_student(("Student"))

node_teacher -->|"uses"| node_web
node_student -->|"uses"| node_web
node_web -.->|"authenticates"| node_login
node_teacher -->|"uploads PDF"| node_documents
node_teacher -->|"authors quiz"| node_teacher_ui
node_student -->|"takes exam"| node_student_ui
node_teacher_ui -.->|"creates and edits"| node_quiz_api
node_student_ui -->|"joins session"| node_session_api
node_quiz_api -->|"delegates to"| node_quiz_service
node_quiz_api -->|"dispatches export"| node_exports
node_quiz_service -.->|"manages"| node_quiz_entity
node_quiz_api -.->|"requests generation"| node_nlp_api
node_documents -.->|"stores files"| node_minio
node_nlp_api -->|"dispatches tasks"| node_generation_tasks
node_generation_tasks -->|"downloads PDF"| node_minio
node_generation_tasks -->|"extracts and analyzes"| node_pdf_processing
node_generation_tasks -->|"indexes chunks"| node_rag
node_generation_tasks -->|"generates questions"| node_llm
node_generation_tasks -.->|"queues work"| node_redis
node_llm -->|"calls provider"| node_llm_provider
node_session_api -->|"delegates to"| node_session_service
node_session_service -->|"creates sessions"| node_session_entity
node_session_service -->|"creates attempts"| node_attempt_entity
node_login -.->|"authenticates"| node_keycloak
node_quiz_api -.->|"persists data"| node_postgres

click node_web "https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/App.tsx"
click node_login "https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/components/auth-provider.tsx"
click node_teacher_ui "https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/pages/enseignant/quiz-editor.tsx"
click node_student_ui "https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/pages/etudiant/exam.tsx"
click node_quiz_api "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/QuizController.java"
click node_quiz_service "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/QuizService.java"
click node_documents "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/DocumentService.java"
click node_exports "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/QuizController.java"
click node_quiz_entity "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Quiz.java"
click node_session_api "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/SessionController.java"
click node_session_service "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java"
click node_session_entity "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Session.java"
click node_attempt_entity "https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Attempt.java"
click node_nlp_api "https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/main.py"
click node_generation_tasks "https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/tasks.py"
click node_pdf_processing "https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/nlp_pipeline.py"
click node_rag "https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/rag_store.py"
click node_llm "https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/llm_client.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_login,node_teacher_ui,node_student_ui toneBlue
class node_quiz_api,node_quiz_service,node_documents,node_exports,node_quiz_entity toneAmber
class node_nlp_api,node_generation_tasks,node_pdf_processing,node_rag,node_llm toneMint
class node_session_api,node_session_service,node_session_entity,node_attempt_entity toneRose
class node_keycloak,node_minio,node_redis,node_llm_provider,node_postgres,node_teacher,node_student toneIndigo
```

## Components

### Role-based web app

- [Role-based app](https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/App.tsx): `artifacts/frontend/src/App.tsx`
- [Authentication UI](https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/components/auth-provider.tsx): `artifacts/frontend/src/components/auth-provider.tsx`
- [Quiz authoring](https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/pages/enseignant/quiz-editor.tsx): `artifacts/frontend/src/pages/enseignant/quiz-editor.tsx`
- [Student exams](https://github.com/abdelhak-elgo/quizgen/blob/main/artifacts/frontend/src/pages/etudiant/exam.tsx): `artifacts/frontend/src/pages/etudiant/exam.tsx`

### Quiz platform API

- [Quiz API](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/QuizController.java): `backend/src/main/java/ma/quizgen/controller/QuizController.java`
- [Quiz workflow](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/QuizService.java): `backend/src/main/java/ma/quizgen/service/QuizService.java`
- [Document management](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/DocumentService.java): `backend/src/main/java/ma/quizgen/service/DocumentService.java`
- [LMS exports](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/QuizController.java): `backend/src/main/java/ma/quizgen/controller/QuizController.java`
- [Quiz state](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Quiz.java): `backend/src/main/java/ma/quizgen/entity/Quiz.java`

### Async NLP generation

- [NLP service API](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/main.py): `nlp-service/app/main.py`
- [Generation tasks](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/tasks.py): `nlp-service/app/tasks.py`
- [PDF and NLP analysis](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/nlp_pipeline.py): `nlp-service/app/nlp_pipeline.py`
- [Semantic retrieval](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/rag_store.py): `nlp-service/app/rag_store.py`
- [LLM generation](https://github.com/abdelhak-elgo/quizgen/blob/main/nlp-service/app/llm_client.py): `nlp-service/app/llm_client.py`

### Sessions and assessment

- [Session API](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/controller/SessionController.java): `backend/src/main/java/ma/quizgen/controller/SessionController.java`
- [Session workflow](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java): `backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java`
- [Session state](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Session.java): `backend/src/main/java/ma/quizgen/entity/Session.java`
- [Attempt state](https://github.com/abdelhak-elgo/quizgen/blob/main/backend/src/main/java/ma/quizgen/entity/Attempt.java): `backend/src/main/java/ma/quizgen/entity/Attempt.java`

### Identity and services

- **Keycloak identity**
- **MinIO document storage**
- **Redis task broker**
- **Configured LLM provider**
- **PostgreSQL**

### Other components

- **Teacher**
- **Student**

## Connections

- Teacher → Role-based app: uses
- Student → Role-based app: uses
- Role-based app → Authentication UI: authenticates
- Teacher → Document management: uploads PDF
- Teacher → Quiz authoring: authors quiz
- Student → Student exams: takes exam
- Quiz authoring → Quiz API: creates and edits
- Student exams → Session API: joins session
- Quiz API → Quiz workflow: delegates to (evidence: `backend/src/main/java/ma/quizgen/controller/QuizController.java`)
- Quiz API → LMS exports: dispatches export (evidence: `backend/src/main/java/ma/quizgen/controller/QuizController.java`)
- Quiz workflow → Quiz state: manages
- Quiz API → NLP service API: requests generation
- Document management → MinIO document storage: stores files
- NLP service API → Generation tasks: dispatches tasks (evidence: `nlp-service/app/main.py`)
- Generation tasks → MinIO document storage: downloads PDF (evidence: `nlp-service/app/tasks.py`)
- Generation tasks → PDF and NLP analysis: extracts and analyzes (evidence: `nlp-service/app/tasks.py`)
- Generation tasks → Semantic retrieval: indexes chunks (evidence: `nlp-service/app/tasks.py`)
- Generation tasks → LLM generation: generates questions (evidence: `nlp-service/app/tasks.py`)
- Generation tasks → Redis task broker: queues work
- LLM generation → Configured LLM provider: calls provider
- Session API → Session workflow: delegates to (evidence: `backend/src/main/java/ma/quizgen/controller/SessionController.java`)
- Session workflow → Session state: creates sessions (evidence: `backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java`)
- Session workflow → Attempt state: creates attempts (evidence: `backend/src/main/java/ma/quizgen/service/impl/SessionServiceImpl.java`)
- Authentication UI → Keycloak identity: authenticates
- Quiz API → PostgreSQL: persists data
