# pratham-mishra225/quizcraft architecture

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

- Interactive diagram: https://gitdiagram.com/pratham-mishra225/quizcraft
- Repository: https://github.com/pratham-mishra225/quizcraft

## Overview

QuizCraft is a full-stack quiz platform: users authenticate, author quizzes manually or generate them from a topic or PDF, take quizzes, and review scored attempts. Its document-grounded path extracts, cleans, chunks, embeds, and stores PDF content before retrieval and quiz generation with source citations. The README describes public sharing, attempt snapshots, and MongoDB/Gemini integration; those capabilities are represented at documented route or subsystem level where implementation excerpts were not sampled.

Main entry points: [`artifacts/api-server/src/app.ts`](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/app.ts) (Express API), [`artifacts/api-server/src/routes/pdf-generate.ts`](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/pdf-generate.ts) (PDF generation), [`artifacts/api-server/src/models/Quiz.ts`](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/models/Quiz.ts) (Domain models), [`artifacts/quiz-app/src/App.tsx`](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Quiz experience"]
  node_spa["React application<br/>[App.tsx]"]
  node_authpage["Sign in / register<br/>[auth.tsx]"]
  node_quizsetup["Quiz setup<br/>[quiz-setup.tsx]"]
  node_quiztake["Take quiz<br/>[quiz-take.tsx]"]
  node_results["Results and history<br/>[results.tsx]"]
  node_resultdetail["Attempt review<br/>[results-detail.tsx]"]
end

subgraph group_api["API and identity"]
  node_server["Express API<br/>[app.ts]"]
  node_authroutes["Authentication<br/>[auth.ts]"]
  node_authmw["Cookie auth<br/>[auth.ts]"]
end

subgraph group_quiz["Quiz workflows"]
  node_quizroutes["Quiz management<br/>[quizzes.ts]"]
  node_topicroutes["Topic generation<br/>[generate.ts]"]
  node_publicroutes["Public sharing<br/>[public-quizzes.ts]"]
  node_attempts["Attempt scoring<br/>[attempts.ts]"]
end

subgraph group_rag["Document RAG"]
  node_pdfroutes["PDF generation<br/>[pdf-generate.ts]"]
  node_quizgen["Context quiz synthesis"]
  node_extract["PDF extraction<br/>[extract.ts]"]
  node_clean["Text cleaning<br/>[clean.ts]"]
  node_chunk["Page chunking<br/>[chunk.ts]"]
  node_embed["Text embeddings<br/>[embed.ts]"]
  node_retrieve["Context retrieval<br/>[retrieve.ts]"]
  node_vectorstore["Vector search<br/>[vectorStore.ts]"]
end

subgraph group_data["Persistence and AI"]
  node_models["Domain models<br/>[Quiz.ts]"]
  node_mongodb[("MongoDB<br/>[mongodb.ts]")]
end

node_user(("Quiz participant"))
node_gemini{{"Google Gemini"}}

node_user -->|"uses"| node_spa
node_spa -->|"routes to"| node_authpage
node_spa -->|"routes to"| node_quizsetup
node_spa -->|"routes to"| node_quiztake
node_spa -->|"routes to"| node_results
node_spa -->|"routes to"| node_resultdetail
node_authpage -->|"sends auth requests"| node_server
node_quizsetup -->|"sends quiz requests"| node_server
node_quiztake -->|"submits answers"| node_server
node_results -->|"loads attempts"| node_server
node_resultdetail -->|"loads review"| node_server
node_server -->|"dispatches"| node_authroutes
node_server -->|"dispatches"| node_quizroutes
node_server -->|"dispatches"| node_topicroutes
node_server -->|"dispatches"| node_pdfroutes
node_server -->|"dispatches"| node_publicroutes
node_server -->|"dispatches"| node_attempts
node_authroutes -->|"guards profile"| node_authmw
node_authroutes -->|"reads and creates users"| node_models
node_quizroutes -->|"manages quizzes"| node_models
node_topicroutes -->|"generates quiz"| node_quizgen
node_pdfroutes -->|"extracts pages"| node_extract
node_pdfroutes -->|"cleans extracted text"| node_clean
node_pdfroutes -->|"chunks pages"| node_chunk
node_pdfroutes -->|"embeds chunks"| node_embed
node_pdfroutes -->|"retrieves context"| node_retrieve
node_pdfroutes -->|"synthesizes quiz"| node_quizgen
node_retrieve -->|"embeds query"| node_embed
node_retrieve -->|"searches chunks"| node_vectorstore
node_vectorstore -->|"reads document chunks"| node_models
node_embed -->|"requests embeddings"| node_gemini
node_quizgen -->|"requests generation"| node_gemini
node_quizgen -->|"persists quiz"| node_models
node_attempts -->|"scores and records"| node_models
node_publicroutes -->|"loads shared quizzes"| node_models
node_models -->|"persists records"| node_mongodb

click node_spa "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/App.tsx"
click node_authpage "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/auth.tsx"
click node_quizsetup "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/quiz-setup.tsx"
click node_quiztake "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/quiz-take.tsx"
click node_results "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/results.tsx"
click node_resultdetail "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/results-detail.tsx"
click node_server "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/app.ts"
click node_authroutes "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/auth.ts"
click node_authmw "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/middlewares/auth.ts"
click node_quizroutes "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/quizzes.ts"
click node_topicroutes "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/generate.ts"
click node_pdfroutes "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/pdf-generate.ts"
click node_publicroutes "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/public-quizzes.ts"
click node_attempts "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/attempts.ts"
click node_quizgen "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/quiz/generateFromContext.ts"
click node_extract "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/extract.ts"
click node_clean "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/clean.ts"
click node_chunk "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/chunk.ts"
click node_embed "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/embeddings/embed.ts"
click node_retrieve "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/retrieval/retrieve.ts"
click node_vectorstore "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/retrieval/vectorStore.ts"
click node_models "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/models/Quiz.ts"
click node_mongodb "https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/db/mongodb.ts"

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_spa,node_authpage,node_quizsetup,node_quiztake,node_results,node_resultdetail toneBlue
class node_server,node_authroutes,node_authmw toneAmber
class node_quizroutes,node_topicroutes,node_publicroutes,node_attempts toneMint
class node_pdfroutes,node_quizgen,node_extract,node_clean,node_chunk,node_embed,node_retrieve,node_vectorstore toneRose
class node_models,node_mongodb,node_user,node_gemini toneIndigo
```

## Components

### Quiz experience

- [React application](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/App.tsx): `artifacts/quiz-app/src/App.tsx`
- [Sign in / register](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/auth.tsx): `artifacts/quiz-app/src/pages/auth.tsx`
- [Quiz setup](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/quiz-setup.tsx): `artifacts/quiz-app/src/pages/quiz-setup.tsx`
- [Take quiz](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/quiz-take.tsx): `artifacts/quiz-app/src/pages/quiz-take.tsx`
- [Results and history](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/results.tsx): `artifacts/quiz-app/src/pages/results.tsx`
- [Attempt review](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/quiz-app/src/pages/results-detail.tsx): `artifacts/quiz-app/src/pages/results-detail.tsx`

### API and identity

- [Express API](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/app.ts): `artifacts/api-server/src/app.ts`
- [Authentication](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/auth.ts): `artifacts/api-server/src/routes/auth.ts`
- [Cookie auth](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/middlewares/auth.ts): `artifacts/api-server/src/middlewares/auth.ts`

### Quiz workflows

- [Quiz management](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/quizzes.ts): `artifacts/api-server/src/routes/quizzes.ts`
- [Topic generation](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/generate.ts): `artifacts/api-server/src/routes/generate.ts`
- [Public sharing](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/public-quizzes.ts): `artifacts/api-server/src/routes/public-quizzes.ts`
- [Attempt scoring](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/attempts.ts): `artifacts/api-server/src/routes/attempts.ts`

### Document RAG

- [PDF generation](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/routes/pdf-generate.ts): `artifacts/api-server/src/routes/pdf-generate.ts`
- [Context quiz synthesis](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/quiz/generateFromContext.ts): `artifacts/api-server/src/services/quiz/generateFromContext.ts`
- [PDF extraction](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/extract.ts): `artifacts/api-server/src/services/pdf/extract.ts`
- [Text cleaning](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/clean.ts): `artifacts/api-server/src/services/pdf/clean.ts`
- [Page chunking](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/pdf/chunk.ts): `artifacts/api-server/src/services/pdf/chunk.ts`
- [Text embeddings](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/embeddings/embed.ts): `artifacts/api-server/src/services/embeddings/embed.ts`
- [Context retrieval](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/retrieval/retrieve.ts): `artifacts/api-server/src/services/retrieval/retrieve.ts`
- [Vector search](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/services/retrieval/vectorStore.ts): `artifacts/api-server/src/services/retrieval/vectorStore.ts`

### Persistence and AI

- [Domain models](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/models/Quiz.ts): `artifacts/api-server/src/models/Quiz.ts`
- [MongoDB](https://github.com/pratham-mishra225/quizcraft/blob/main/artifacts/api-server/src/db/mongodb.ts): `artifacts/api-server/src/db/mongodb.ts`

### Other components

- **Quiz participant**
- **Google Gemini**

## Connections

- Quiz participant → React application: uses
- React application → Sign in / register: routes to
- React application → Quiz setup: routes to
- React application → Take quiz: routes to
- React application → Results and history: routes to
- React application → Attempt review: routes to
- Sign in / register → Express API: sends auth requests
- Quiz setup → Express API: sends quiz requests
- Take quiz → Express API: submits answers
- Results and history → Express API: loads attempts
- Attempt review → Express API: loads review
- Express API → Authentication: dispatches
- Express API → Quiz management: dispatches
- Express API → Topic generation: dispatches
- Express API → PDF generation: dispatches
- Express API → Public sharing: dispatches
- Express API → Attempt scoring: dispatches
- Authentication → Cookie auth: guards profile
- Authentication → Domain models: reads and creates users
- Quiz management → Domain models: manages quizzes
- Topic generation → Context quiz synthesis: generates quiz
- PDF generation → PDF extraction: extracts pages
- PDF generation → Text cleaning: cleans extracted text
- PDF generation → Page chunking: chunks pages
- PDF generation → Text embeddings: embeds chunks
- PDF generation → Context retrieval: retrieves context
- PDF generation → Context quiz synthesis: synthesizes quiz
- Context retrieval → Text embeddings: embeds query
- Context retrieval → Vector search: searches chunks
- Vector search → Domain models: reads document chunks
- Text embeddings → Google Gemini: requests embeddings
- Context quiz synthesis → Google Gemini: requests generation
- Context quiz synthesis → Domain models: persists quiz
- Attempt scoring → Domain models: scores and records
- Public sharing → Domain models: loads shared quizzes
- Domain models → MongoDB: persists records