# codewithjoee/quiz-app architecture

> Architecture diagram of the GitHub repository codewithjoee/quiz-app, 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/codewithjoee/quiz-app
- Repository: https://github.com/codewithjoee/quiz-app

## Overview

This is a role-based classroom and quiz application: teachers and administrators manage users, rooms, invitations, and quizzes; students join rooms, take timed quizzes, and review results, while teachers grade essay responses. The documented product also includes attempt history, profile-photo review, account deletion/restore, dashboard monitoring, and installable PWA support. Supabase provides authentication and persisted application data. The graph follows documented workflows and sampled source calls; several feature implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`src/app/api/admin/create-user/route.ts`](https://github.com/codewithjoee/quiz-app/blob/master/src/app/api/admin/create-user/route.ts) (Create user API), [`src/app/[locale]/(auth)/login/page.tsx`](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(auth)/login/page.tsx) (Login), [`src/app/[locale]/(dashboard)/quiz/[quizId]/page.tsx`](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/page.tsx) (Quiz authoring), [`src/app/[locale]/(dashboard)/quiz/[quizId]/QuizRunner.tsx`](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/QuizRunner.tsx) (Quiz attempt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_login["Login<br/>[page.tsx]"]
  node_auth_profile["Auth and profile<br/>[auth.ts]"]
  node_supabase_server["Server client<br/>[server.ts]"]
  node_user_creation["Create user API<br/>[route.ts]"]
end

subgraph group_classrooms["Classroom management"]
  node_rooms["Rooms and invitations<br/>[page.tsx]"]
end

subgraph group_assessment["Quiz and assessment"]
  node_quiz_setup["Quiz authoring<br/>[page.tsx]"]
  node_excel_import["Quiz spreadsheet import<br/>[ExcelImport.tsx]"]
  node_quiz_runner["Quiz attempt<br/>[QuizRunner.tsx]"]
  node_anti_cheat["Anti-cheat monitor<br/>[useAntiCheat.ts]"]
  node_attempts["Attempt handling<br/>[attempts.ts]"]
  node_scoring["Quiz scoring<br/>[scoring.ts]"]
  node_essay_grading["Essay grading<br/>[page.tsx]"]
  node_results["Quiz results<br/>[page.tsx]"]
  node_history["Attempt history<br/>[page.tsx]"]
end

subgraph group_oversight["Administration and profiles"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_student_management["Student management<br/>[page.tsx]"]
  node_bulk_import["Bulk student import"]
  node_profile["Profile and photos<br/>[page.tsx]"]
  node_pending_photos["Photo approvals<br/>[page.tsx]"]
end

subgraph group_experience["Shared experience"]
  node_help["Role-based help<br/>[content.ts]"]
  node_pwa["Installable app<br/>[sw.js]"]
  node_badge_counts["Navigation badges<br/>[useBadgeCounts.ts]"]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_admin(("Super admin"))
node_supabase_store[("Supabase")]

node_student -->|"signs in"| node_login
node_teacher -->|"signs in"| node_login
node_admin -->|"signs in"| node_login
node_login -->|"checks identity"| node_auth_profile
node_auth_profile -->|"creates client"| node_supabase_server
node_supabase_server -->|"reads profile"| node_supabase_store
node_teacher -->|"creates accounts"| node_user_creation
node_admin -->|"creates accounts"| node_user_creation
node_user_creation -->|"checks session"| node_supabase_server
node_user_creation -->|"creates auth user"| node_supabase_store
node_teacher -->|"monitors activity"| node_dashboard
node_admin -->|"monitors activity"| node_dashboard
node_teacher -->|"manages students"| node_student_management
node_student_management -->|"imports roster"| node_bulk_import
node_bulk_import -->|"creates students"| node_supabase_store
node_teacher -->|"manages classes"| node_rooms
node_student -->|"joins invitations"| node_rooms
node_rooms -->|"stores membership"| node_supabase_store
node_teacher -->|"authors quizzes"| node_quiz_setup
node_quiz_setup -->|"imports questions"| node_excel_import
node_quiz_setup -->|"stores quiz"| node_supabase_store
node_student -->|"takes quiz"| node_quiz_runner
node_quiz_runner -->|"monitors conduct"| node_anti_cheat
node_quiz_runner -->|"submits answers"| node_attempts
node_attempts -->|"stores attempt"| node_supabase_store
node_attempts -->|"scores answers"| node_scoring
node_teacher -->|"grades essays"| node_essay_grading
node_essay_grading -->|"saves grades"| node_supabase_store
node_student -->|"reviews result"| node_results
node_results -->|"reads attempt"| node_supabase_store
node_student -->|"reviews progress"| node_history
node_history -->|"reads attempts"| node_supabase_store
node_student -->|"manages profile"| node_profile
node_teacher -->|"reviews photos"| node_pending_photos
node_admin -->|"reviews photos"| node_pending_photos
node_profile -->|"updates profile"| node_supabase_store
node_teacher -->|"consults guidance"| node_help
node_student -->|"consults guidance"| node_help
node_admin -->|"consults guidance"| node_help
node_badge_counts -->|"counts pending items"| node_supabase_store

click node_login "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(auth)/login/page.tsx"
click node_auth_profile "https://github.com/codewithjoee/quiz-app/blob/master/lib/auth.ts"
click node_supabase_server "https://github.com/codewithjoee/quiz-app/blob/master/lib/supabase/server.ts"
click node_user_creation "https://github.com/codewithjoee/quiz-app/blob/master/src/app/api/admin/create-user/route.ts"
click node_dashboard "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/admin/dashboard/page.tsx"
click node_student_management "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/students/page.tsx"
click node_bulk_import "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/students/BulkImportModal.tsx"
click node_rooms "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/rooms/%5BroomId%5D/page.tsx"
click node_quiz_setup "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/page.tsx"
click node_excel_import "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/ExcelImport.tsx"
click node_quiz_runner "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/QuizRunner.tsx"
click node_anti_cheat "https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/useAntiCheat.ts"
click node_attempts "https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/attempts.ts"
click node_scoring "https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/scoring.ts"
click node_essay_grading "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/attempts/%5BattemptId%5D/grade/page.tsx"
click node_results "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/result/page.tsx"
click node_history "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/history/page.tsx"
click node_profile "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/profile/page.tsx"
click node_pending_photos "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/pending-photos/page.tsx"
click node_help "https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/help/content.ts"
click node_pwa "https://github.com/codewithjoee/quiz-app/blob/master/public/sw.js"
click node_badge_counts "https://github.com/codewithjoee/quiz-app/blob/master/components/useBadgeCounts.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_login,node_auth_profile,node_supabase_server,node_user_creation toneBlue
class node_rooms,node_supabase_store toneAmber
class node_quiz_setup,node_excel_import,node_quiz_runner,node_anti_cheat,node_attempts,node_scoring,node_essay_grading,node_results,node_history toneMint
class node_dashboard,node_student_management,node_bulk_import,node_profile,node_pending_photos toneRose
class node_help,node_pwa,node_badge_counts,node_teacher,node_student,node_admin toneIndigo
```

## Components

### Identity and access

- [Login](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(auth)/login/page.tsx): `src/app/[locale]/(auth)/login/page.tsx`
- [Auth and profile](https://github.com/codewithjoee/quiz-app/blob/master/lib/auth.ts): `lib/auth.ts`
- [Server client](https://github.com/codewithjoee/quiz-app/blob/master/lib/supabase/server.ts): `lib/supabase/server.ts`
- [Create user API](https://github.com/codewithjoee/quiz-app/blob/master/src/app/api/admin/create-user/route.ts): `src/app/api/admin/create-user/route.ts`

### Classroom management

- [Rooms and invitations](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/rooms/%5BroomId%5D/page.tsx): `src/app/[locale]/(dashboard)/rooms/[roomId]/page.tsx`

### Quiz and assessment

- [Quiz authoring](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/page.tsx): `src/app/[locale]/(dashboard)/quiz/[quizId]/page.tsx`
- [Quiz spreadsheet import](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/ExcelImport.tsx): `src/app/[locale]/(dashboard)/quiz/[quizId]/ExcelImport.tsx`
- [Quiz attempt](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/QuizRunner.tsx): `src/app/[locale]/(dashboard)/quiz/[quizId]/QuizRunner.tsx`
- [Anti-cheat monitor](https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/useAntiCheat.ts): `lib/quiz/useAntiCheat.ts`
- [Attempt handling](https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/attempts.ts): `lib/quiz/attempts.ts`
- [Quiz scoring](https://github.com/codewithjoee/quiz-app/blob/master/lib/quiz/scoring.ts): `lib/quiz/scoring.ts`
- [Essay grading](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/attempts/%5BattemptId%5D/grade/page.tsx): `src/app/[locale]/(dashboard)/quiz/[quizId]/attempts/[attemptId]/grade/page.tsx`
- [Quiz results](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/quiz/%5BquizId%5D/result/page.tsx): `src/app/[locale]/(dashboard)/quiz/[quizId]/result/page.tsx`
- [Attempt history](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/history/page.tsx): `src/app/[locale]/(dashboard)/history/page.tsx`

### Administration and profiles

- [Dashboard](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/admin/dashboard/page.tsx): `src/app/[locale]/(dashboard)/admin/dashboard/page.tsx`
- [Student management](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/students/page.tsx): `src/app/[locale]/(dashboard)/students/page.tsx`
- [Bulk student import](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/students/BulkImportModal.tsx): `src/app/[locale]/(dashboard)/students/BulkImportModal.tsx`
- [Profile and photos](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/profile/page.tsx): `src/app/[locale]/(dashboard)/profile/page.tsx`
- [Photo approvals](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/pending-photos/page.tsx): `src/app/[locale]/(dashboard)/pending-photos/page.tsx`

### Shared experience

- [Role-based help](https://github.com/codewithjoee/quiz-app/blob/master/src/app/%5Blocale%5D/(dashboard)/help/content.ts): `src/app/[locale]/(dashboard)/help/content.ts`
- [Installable app](https://github.com/codewithjoee/quiz-app/blob/master/public/sw.js): `public/sw.js`
- [Navigation badges](https://github.com/codewithjoee/quiz-app/blob/master/components/useBadgeCounts.ts): `components/useBadgeCounts.ts`

### Other components

- **Teacher**
- **Student**
- **Super admin**
- **Supabase**

## Connections

- Student → Login: signs in
- Teacher → Login: signs in
- Super admin → Login: signs in
- Login → Auth and profile: checks identity
- Auth and profile → Server client: creates client
- Server client → Supabase: reads profile
- Teacher → Create user API: creates accounts
- Super admin → Create user API: creates accounts
- Create user API → Server client: checks session
- Create user API → Supabase: creates auth user
- Teacher → Dashboard: monitors activity
- Super admin → Dashboard: monitors activity
- Teacher → Student management: manages students
- Student management → Bulk student import: imports roster
- Bulk student import → Supabase: creates students
- Teacher → Rooms and invitations: manages classes
- Student → Rooms and invitations: joins invitations
- Rooms and invitations → Supabase: stores membership
- Teacher → Quiz authoring: authors quizzes
- Quiz authoring → Quiz spreadsheet import: imports questions
- Quiz authoring → Supabase: stores quiz
- Student → Quiz attempt: takes quiz
- Quiz attempt → Anti-cheat monitor: monitors conduct
- Quiz attempt → Attempt handling: submits answers
- Attempt handling → Supabase: stores attempt
- Attempt handling → Quiz scoring: scores answers
- Teacher → Essay grading: grades essays
- Essay grading → Supabase: saves grades
- Student → Quiz results: reviews result
- Quiz results → Supabase: reads attempt
- Student → Attempt history: reviews progress
- Attempt history → Supabase: reads attempts
- Student → Profile and photos: manages profile
- Teacher → Photo approvals: reviews photos
- Super admin → Photo approvals: reviews photos
- Profile and photos → Supabase: updates profile
- Teacher → Role-based help: consults guidance
- Student → Role-based help: consults guidance
- Super admin → Role-based help: consults guidance
- Navigation badges → Supabase: counts pending items