# helvetiche/quizche architecture

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

- Interactive diagram: https://gitdiagram.com/helvetiche/quizche
- Repository: https://github.com/helvetiche/quizche

## Overview

QuizChe is a web-based AI study platform for students and teachers. Its central workflow turns uploaded PDFs into editable flashcard sets or quizzes; students study cards and take assigned quizzes, while teachers organize sections, assign quizzes, monitor attempts, and review results. The graph also captures social sharing and the authentication, API, and persistence layers. README-documented capabilities are included, but unsampled routes and components are grouped at supported directory paths; edges without direct source evidence are omitted.

Main entry points: [`app/api`](https://github.com/helvetiche/quizche/tree/main/app/api) (API routes), [`lib/firebase-admin.ts`](https://github.com/helvetiche/quizche/blob/main/lib/firebase-admin.ts) (Firebase Admin), [`app/components/GoogleAuthButton.tsx`](https://github.com/helvetiche/quizche/blob/main/app/components/GoogleAuthButton.tsx) (Sign-in and roles), [`app/api/student/quizzes`](https://github.com/helvetiche/quizche/tree/main/app/api/student/quizzes) (Quiz attempts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Student learning"]
  node_flashcards["Flashcard features"]
  node_student_quizzes["Quiz attempts"]
  node_quiz_history["Quiz history and results<br/>[page.tsx]"]
end

subgraph group_teaching["Teacher tools"]
  node_quiz_drafts["Quiz drafts"]
  node_quiz_management["Quiz management"]
  node_sections["Class sections"]
  node_teacher_monitoring["Live monitoring<br/>[route.ts]"]
  node_anti_cheat["Anti-cheat tracking<br/>[useAntiCheat.ts]"]
end

subgraph group_creation["Content creation"]
  node_pdf_upload["PDF upload<br/>[PDFUploadModal.tsx]"]
  node_flashcard_creation["Flashcard authoring"]
  node_quiz_authoring["Quiz authoring<br/>[useQuizForm.ts]"]
end

subgraph group_social["Connections and sharing"]
  node_connections["Classmate connections"]
end

subgraph group_platform["Platform services"]
  node_auth_ui["Sign-in and roles"]
  node_profile_setup["Profile setup<br/>[ProfileSetup.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_service["Token verification<br/>[auth.ts]"]
  node_api_routes["API routes"]
  node_validation["Input validation<br/>[validation.ts]"]
  node_csrf["CSRF protection<br/>[csrf.ts]"]
  node_rate_limit["Rate limiting<br/>[rate-limit.ts]"]
  node_error_handling["Error handling<br/>[error-handler.ts]"]
  node_firebase_client["Firebase client<br/>[firebase.ts]"]
  node_firebase_admin["Firebase Admin<br/>[firebase-admin.ts]"]
  node_firestore[("Firestore data")]
  node_redis[("Redis")]
end

node_students(("Students"))
node_teachers(("Teachers"))

node_students -->|"sign in"| node_auth_ui
node_teachers -->|"sign in"| node_auth_ui
node_auth_ui -->|"register or log in"| node_api_client
node_auth_ui -->|"authenticate with"| node_firebase_client
node_auth_ui -->|"choose role"| node_profile_setup
node_api_client -->|"fetch token via"| node_csrf
node_api_client -->|"send requests"| node_api_routes
node_api_routes -->|"verify identity"| node_auth_service
node_api_routes -->|"read and write data"| node_firebase_admin
node_api_routes -->|"validate inputs"| node_validation
node_api_routes -->|"verify mutations"| node_csrf
node_api_routes -->|"limit requests"| node_rate_limit
node_api_routes -->|"handle failures"| node_error_handling
node_auth_service -->|"verify tokens with"| node_firebase_admin
node_firebase_admin -->|"accesses"| node_firestore
node_csrf -->|"stores tokens in"| node_redis
node_rate_limit -->|"uses"| node_redis
node_error_handling -->|"returns safe errors"| node_api_routes
node_students -->|"upload materials"| node_pdf_upload
node_teachers -->|"upload materials"| node_pdf_upload
node_pdf_upload -->|"configure card generation"| node_flashcard_creation
node_pdf_upload -->|"configure quiz generation"| node_quiz_authoring
node_flashcard_creation -.->|"save and edit sets"| node_flashcards
node_quiz_authoring -->|"save drafts"| node_quiz_drafts
node_quiz_authoring -.->|"create quizzes"| node_quiz_management
node_flashcards -->|"persist and query"| node_firebase_admin
node_quiz_management -->|"persist quiz data"| node_firebase_admin
node_quiz_drafts -->|"persist drafts"| node_firebase_admin
node_teachers -->|"organize classes"| node_sections
node_sections -->|"read and write sections"| node_firebase_admin
node_teachers -->|"assign quizzes"| node_quiz_management
node_students -->|"take assigned quizzes"| node_student_quizzes
node_student_quizzes -.->|"persist attempts"| node_firebase_admin
node_student_quizzes -.->|"review results"| node_quiz_history
node_teachers -->|"monitor attempts"| node_teacher_monitoring
node_student_quizzes -->|"track quiz activity"| node_anti_cheat
node_students -->|"study and share"| node_flashcards
node_students -->|"find classmates"| node_connections
node_connections -->|"read and write connections"| node_firebase_admin

click node_auth_ui "https://github.com/helvetiche/quizche/blob/main/app/components/GoogleAuthButton.tsx"
click node_profile_setup "https://github.com/helvetiche/quizche/blob/main/app/components/auth/ProfileSetup.tsx"
click node_api_client "https://github.com/helvetiche/quizche/blob/main/app/lib/api.ts"
click node_auth_service "https://github.com/helvetiche/quizche/blob/main/lib/auth.ts"
click node_api_routes "https://github.com/helvetiche/quizche/tree/main/app/api"
click node_validation "https://github.com/helvetiche/quizche/blob/main/lib/validation.ts"
click node_csrf "https://github.com/helvetiche/quizche/blob/main/lib/csrf.ts"
click node_rate_limit "https://github.com/helvetiche/quizche/blob/main/lib/rate-limit.ts"
click node_error_handling "https://github.com/helvetiche/quizche/blob/main/lib/error-handler.ts"
click node_firebase_client "https://github.com/helvetiche/quizche/blob/main/lib/firebase.ts"
click node_firebase_admin "https://github.com/helvetiche/quizche/blob/main/lib/firebase-admin.ts"
click node_pdf_upload "https://github.com/helvetiche/quizche/blob/main/app/components/create/PDFUploadModal.tsx"
click node_flashcard_creation "https://github.com/helvetiche/quizche/blob/main/app/components/create/flashcard-maker/hooks/useFlashcardMaker.ts"
click node_flashcards "https://github.com/helvetiche/quizche/tree/main/app/api/flashcards"
click node_quiz_authoring "https://github.com/helvetiche/quizche/blob/main/app/components/create/quiz-form/useQuizForm.ts"
click node_quiz_drafts "https://github.com/helvetiche/quizche/tree/main/app/api/quizzes/drafts"
click node_quiz_management "https://github.com/helvetiche/quizche/tree/main/app/api/quizzes"
click node_sections "https://github.com/helvetiche/quizche/tree/main/app/api/teacher/sections"
click node_student_quizzes "https://github.com/helvetiche/quizche/tree/main/app/api/student/quizzes"
click node_teacher_monitoring "https://github.com/helvetiche/quizche/blob/main/app/api/teacher/quizzes/%5Bid%5D/live/route.ts"
click node_anti_cheat "https://github.com/helvetiche/quizche/blob/main/app/components/create/useAntiCheat.ts"
click node_quiz_history "https://github.com/helvetiche/quizche/blob/main/app/student/history/%5BattemptId%5D/page.tsx"
click node_connections "https://github.com/helvetiche/quizche/tree/main/app/api/connections"

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_flashcards,node_student_quizzes,node_quiz_history toneBlue
class node_quiz_drafts,node_quiz_management,node_sections,node_teacher_monitoring,node_anti_cheat toneAmber
class node_pdf_upload,node_flashcard_creation,node_quiz_authoring toneMint
class node_connections toneRose
class node_auth_ui,node_profile_setup,node_api_client,node_auth_service,node_api_routes,node_validation,node_csrf,node_rate_limit,node_error_handling,node_firebase_client,node_firebase_admin,node_firestore,node_redis,node_students,node_teachers toneIndigo
```

## Components

### Student learning

- [Flashcard features](https://github.com/helvetiche/quizche/tree/main/app/api/flashcards): `app/api/flashcards`
- [Quiz attempts](https://github.com/helvetiche/quizche/tree/main/app/api/student/quizzes): `app/api/student/quizzes`
- [Quiz history and results](https://github.com/helvetiche/quizche/blob/main/app/student/history/%5BattemptId%5D/page.tsx): `app/student/history/[attemptId]/page.tsx`

### Teacher tools

- [Quiz drafts](https://github.com/helvetiche/quizche/tree/main/app/api/quizzes/drafts): `app/api/quizzes/drafts`
- [Quiz management](https://github.com/helvetiche/quizche/tree/main/app/api/quizzes): `app/api/quizzes`
- [Class sections](https://github.com/helvetiche/quizche/tree/main/app/api/teacher/sections): `app/api/teacher/sections`
- [Live monitoring](https://github.com/helvetiche/quizche/blob/main/app/api/teacher/quizzes/%5Bid%5D/live/route.ts): `app/api/teacher/quizzes/[id]/live/route.ts`
- [Anti-cheat tracking](https://github.com/helvetiche/quizche/blob/main/app/components/create/useAntiCheat.ts): `app/components/create/useAntiCheat.ts`

### Content creation

- [PDF upload](https://github.com/helvetiche/quizche/blob/main/app/components/create/PDFUploadModal.tsx): `app/components/create/PDFUploadModal.tsx`
- [Flashcard authoring](https://github.com/helvetiche/quizche/blob/main/app/components/create/flashcard-maker/hooks/useFlashcardMaker.ts): `app/components/create/flashcard-maker/hooks/useFlashcardMaker.ts`
- [Quiz authoring](https://github.com/helvetiche/quizche/blob/main/app/components/create/quiz-form/useQuizForm.ts): `app/components/create/quiz-form/useQuizForm.ts`

### Connections and sharing

- [Classmate connections](https://github.com/helvetiche/quizche/tree/main/app/api/connections): `app/api/connections`

### Platform services

- [Sign-in and roles](https://github.com/helvetiche/quizche/blob/main/app/components/GoogleAuthButton.tsx): `app/components/GoogleAuthButton.tsx`
- [Profile setup](https://github.com/helvetiche/quizche/blob/main/app/components/auth/ProfileSetup.tsx): `app/components/auth/ProfileSetup.tsx`
- [API client](https://github.com/helvetiche/quizche/blob/main/app/lib/api.ts): `app/lib/api.ts`
- [Token verification](https://github.com/helvetiche/quizche/blob/main/lib/auth.ts): `lib/auth.ts`
- [API routes](https://github.com/helvetiche/quizche/tree/main/app/api): `app/api`
- [Input validation](https://github.com/helvetiche/quizche/blob/main/lib/validation.ts): `lib/validation.ts`
- [CSRF protection](https://github.com/helvetiche/quizche/blob/main/lib/csrf.ts): `lib/csrf.ts`
- [Rate limiting](https://github.com/helvetiche/quizche/blob/main/lib/rate-limit.ts): `lib/rate-limit.ts`
- [Error handling](https://github.com/helvetiche/quizche/blob/main/lib/error-handler.ts): `lib/error-handler.ts`
- [Firebase client](https://github.com/helvetiche/quizche/blob/main/lib/firebase.ts): `lib/firebase.ts`
- [Firebase Admin](https://github.com/helvetiche/quizche/blob/main/lib/firebase-admin.ts): `lib/firebase-admin.ts`
- **Firestore data**
- **Redis**

### Other components

- **Students**
- **Teachers**

## Connections

- Students → Sign-in and roles: sign in (evidence: `README.md`)
- Teachers → Sign-in and roles: sign in (evidence: `README.md`)
- Sign-in and roles → API client: register or log in (evidence: `app/components/GoogleAuthButton.tsx`)
- Sign-in and roles → Firebase client: authenticate with (evidence: `app/components/GoogleAuthButton.tsx`)
- Sign-in and roles → Profile setup: choose role (evidence: `app/page.tsx`)
- API client → CSRF protection: fetch token via (evidence: `app/lib/api.ts`)
- API client → API routes: send requests (evidence: `app/lib/api.ts`)
- API routes → Token verification: verify identity (evidence: `app/api/connections/route.ts`)
- API routes → Firebase Admin: read and write data (evidence: `app/api/connections/route.ts`)
- API routes → Input validation: validate inputs (evidence: `app/api/connections/route.ts`)
- API routes → CSRF protection: verify mutations (evidence: `app/api/connections/route.ts`)
- API routes → Rate limiting: limit requests (evidence: `app/api/connections/route.ts`)
- API routes → Error handling: handle failures (evidence: `app/api/connections/route.ts`)
- Token verification → Firebase Admin: verify tokens with (evidence: `lib/auth.ts`)
- Firebase Admin → Firestore data: accesses (evidence: `lib/firebase-admin.ts`)
- CSRF protection → Redis: stores tokens in (evidence: `lib/csrf.ts`)
- Rate limiting → Redis: uses (evidence: `lib/rate-limit.ts`)
- Error handling → API routes: returns safe errors (evidence: `lib/error-handler.ts`)
- Students → PDF upload: upload materials (evidence: `README.md`)
- Teachers → PDF upload: upload materials (evidence: `README.md`)
- PDF upload → Flashcard authoring: configure card generation (evidence: `README.md`)
- PDF upload → Quiz authoring: configure quiz generation (evidence: `README.md`)
- Flashcard authoring → Flashcard features: save and edit sets
- Quiz authoring → Quiz drafts: save drafts (evidence: `app/components/create/quiz-form/useQuizForm.ts`)
- Quiz authoring → Quiz management: create quizzes
- Flashcard features → Firebase Admin: persist and query (evidence: `app/api/flashcards/route.ts`)
- Quiz management → Firebase Admin: persist quiz data (evidence: `app/api/quizzes/route.ts`)
- Quiz drafts → Firebase Admin: persist drafts (evidence: `app/api/quizzes/drafts/route.ts`)
- Teachers → Class sections: organize classes (evidence: `README.md`)
- Class sections → Firebase Admin: read and write sections (evidence: `app/api/teacher/sections/route.ts`)
- Teachers → Quiz management: assign quizzes (evidence: `README.md`)
- Students → Quiz attempts: take assigned quizzes (evidence: `README.md`)
- Quiz attempts → Firebase Admin: persist attempts
- Quiz attempts → Quiz history and results: review results
- Teachers → Live monitoring: monitor attempts (evidence: `README.md`)
- Quiz attempts → Anti-cheat tracking: track quiz activity (evidence: `app/components/create/useAntiCheat.ts`)
- Students → Flashcard features: study and share (evidence: `README.md`)
- Students → Classmate connections: find classmates (evidence: `README.md`)
- Classmate connections → Firebase Admin: read and write connections (evidence: `app/api/connections/route.ts`)