# rat-sh/x-pert2 architecture

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

- Interactive diagram: https://gitdiagram.com/rat-sh/x-pert2
- Repository: https://github.com/rat-sh/x-pert2

## Overview

X-Pert is a teacher-focused online examination platform. Teachers create batches, build or source questions, configure and publish exams, then review and export results; students enroll by code, find exams, take timed tests, and view results. The graph also preserves the documented calendar, materials, and upcoming-exam capabilities. Sampled sources confirm the batch manager’s Supabase operations, auth context/profile loading, and extraction API’s Gemini calls; other feature-level links follow README workflows because their runtime source was not sampled.

Main entry points: [`src/features/batch-manager/components/BatchManagerPage.tsx`](https://github.com/rat-sh/x-pert2/blob/main/src/features/batch-manager/components/BatchManagerPage.tsx) (Batch management), [`src/features/exam-creator/components/ExamCreatorPage.tsx`](https://github.com/rat-sh/x-pert2/blob/main/src/features/exam-creator/components/ExamCreatorPage.tsx) (Exam creation), [`src/features/auth/services/auth.service.ts`](https://github.com/rat-sh/x-pert2/blob/main/src/features/auth/services/auth.service.ts) (Auth service), [`src/shared/services/supabase-client.ts`](https://github.com/rat-sh/x-pert2/blob/main/src/shared/services/supabase-client.ts) (Supabase backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and shared services"]
  node_signup["Sign up<br/>[SignupForm.tsx]"]
  node_auth_context["Auth context<br/>[AuthContext.tsx]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
end

subgraph group_teacher["Teacher tools"]
  node_batch_manager["Batch management"]
  node_calendar["Calendar scheduling<br/>[CalendarPage.tsx]"]
  node_exam_creator["Exam creation"]
  node_paper_builder["Paper builder"]
  node_question_bank["Question bank"]
  node_extraction["Question extraction"]
  node_materials_manager["Materials manager"]
  node_teacher_results["Teacher results"]
end

subgraph group_student["Student experience"]
  node_student_join["Batch enrollment"]
  node_student_exams["Available exams"]
  node_exam_session["Timed exam session<br/>[page.tsx]"]
  node_student_results["Student results"]
  node_upcoming_exams["Upcoming exams"]
  node_student_materials["Study materials"]
end

subgraph group_platform["Platform services"]
  node_extraction_api["Extraction API<br/>[route.ts]"]
  node_supabase[("Supabase backend<br/>[supabase-client.ts]")]
  node_storage[("Supabase storage<br/>[storage.service.ts]")]
end

node_teacher_actor(("Teacher"))
node_student_actor(("Student"))
node_gemini["Gemini extraction"]

node_teacher_actor -->|"signs up"| node_signup
node_signup -->|"submits credentials"| node_auth_service
node_auth_service -->|"authenticates"| node_supabase
node_auth_context -->|"loads profile"| node_auth_service
node_teacher_actor -->|"creates batches"| node_batch_manager
node_batch_manager -->|"reads and writes"| node_supabase
node_batch_manager -->|"creates sessions"| node_calendar
node_teacher_actor -->|"creates exams"| node_exam_creator
node_exam_creator -->|"builds paper"| node_paper_builder
node_exam_creator -->|"sources questions"| node_question_bank
node_teacher_actor -->|"uploads questions"| node_extraction
node_extraction -->|"submits file"| node_extraction_api
node_extraction_api -->|"requests extraction"| node_gemini
node_teacher_actor -->|"manages materials"| node_materials_manager
node_materials_manager -.->|"uploads files"| node_storage
node_teacher_actor -->|"reviews results"| node_teacher_results
node_student_actor -->|"joins by code"| node_student_join
node_student_join -->|"enrolls student"| node_supabase
node_student_actor -->|"views exams"| node_student_exams
node_student_exams -->|"starts exam"| node_exam_session
node_exam_session -->|"submits answers"| node_student_results
node_student_actor -->|"checks schedule"| node_upcoming_exams
node_student_actor -->|"views materials"| node_student_materials

click node_signup "https://github.com/rat-sh/x-pert2/blob/main/src/features/auth/components/SignupForm.tsx"
click node_auth_context "https://github.com/rat-sh/x-pert2/blob/main/src/contexts/AuthContext.tsx"
click node_auth_service "https://github.com/rat-sh/x-pert2/blob/main/src/features/auth/services/auth.service.ts"
click node_batch_manager "https://github.com/rat-sh/x-pert2/blob/main/src/features/batch-manager/components/BatchManagerPage.tsx"
click node_calendar "https://github.com/rat-sh/x-pert2/blob/main/src/features/calendar-schedule/components/CalendarPage.tsx"
click node_exam_creator "https://github.com/rat-sh/x-pert2/blob/main/src/features/exam-creator/components/ExamCreatorPage.tsx"
click node_paper_builder "https://github.com/rat-sh/x-pert2/blob/main/src/features/question-builder/components/QuestionPaperBuilder.tsx"
click node_question_bank "https://github.com/rat-sh/x-pert2/blob/main/src/features/question-bank/components/QuestionBankPage.tsx"
click node_extraction "https://github.com/rat-sh/x-pert2/blob/main/src/features/question-extraction/components/QuestionExtractionUpload.tsx"
click node_extraction_api "https://github.com/rat-sh/x-pert2/blob/main/app/api/questions/extract/route.ts"
click node_materials_manager "https://github.com/rat-sh/x-pert2/blob/main/src/features/study-materials/components/teacher/MaterialsManagerPage.tsx"
click node_teacher_results "https://github.com/rat-sh/x-pert2/blob/main/src/features/teacher-results/components/TeacherResultsPage.tsx"
click node_student_join "https://github.com/rat-sh/x-pert2/blob/main/src/features/student-join/components/StudentJoinPage.tsx"
click node_student_exams "https://github.com/rat-sh/x-pert2/blob/main/src/features/student-exams/components/StudentExamsPage.tsx"
click node_exam_session "https://github.com/rat-sh/x-pert2/blob/main/app/student/exams/%5BexamId%5D/take/page.tsx"
click node_student_results "https://github.com/rat-sh/x-pert2/blob/main/src/features/student-results/components/StudentResultsPage.tsx"
click node_upcoming_exams "https://github.com/rat-sh/x-pert2/blob/main/src/features/upcoming-exams/components/UpcomingExamsPage.tsx"
click node_student_materials "https://github.com/rat-sh/x-pert2/blob/main/src/features/study-materials/components/student/MaterialsBrowserPage.tsx"
click node_supabase "https://github.com/rat-sh/x-pert2/blob/main/src/shared/services/supabase-client.ts"
click node_storage "https://github.com/rat-sh/x-pert2/blob/main/src/shared/services/storage.service.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_signup,node_auth_context,node_auth_service toneBlue
class node_batch_manager,node_calendar,node_exam_creator,node_paper_builder,node_question_bank,node_extraction,node_materials_manager,node_teacher_results toneAmber
class node_student_join,node_student_exams,node_exam_session,node_student_results,node_upcoming_exams,node_student_materials toneMint
class node_extraction_api,node_supabase,node_storage toneRose
class node_teacher_actor,node_student_actor,node_gemini toneIndigo
```

## Components

### Identity and shared services

- [Sign up](https://github.com/rat-sh/x-pert2/blob/main/src/features/auth/components/SignupForm.tsx): `src/features/auth/components/SignupForm.tsx`
- [Auth context](https://github.com/rat-sh/x-pert2/blob/main/src/contexts/AuthContext.tsx): `src/contexts/AuthContext.tsx`
- [Auth service](https://github.com/rat-sh/x-pert2/blob/main/src/features/auth/services/auth.service.ts): `src/features/auth/services/auth.service.ts`

### Teacher tools

- [Batch management](https://github.com/rat-sh/x-pert2/blob/main/src/features/batch-manager/components/BatchManagerPage.tsx): `src/features/batch-manager/components/BatchManagerPage.tsx`
- [Calendar scheduling](https://github.com/rat-sh/x-pert2/blob/main/src/features/calendar-schedule/components/CalendarPage.tsx): `src/features/calendar-schedule/components/CalendarPage.tsx`
- [Exam creation](https://github.com/rat-sh/x-pert2/blob/main/src/features/exam-creator/components/ExamCreatorPage.tsx): `src/features/exam-creator/components/ExamCreatorPage.tsx`
- [Paper builder](https://github.com/rat-sh/x-pert2/blob/main/src/features/question-builder/components/QuestionPaperBuilder.tsx): `src/features/question-builder/components/QuestionPaperBuilder.tsx`
- [Question bank](https://github.com/rat-sh/x-pert2/blob/main/src/features/question-bank/components/QuestionBankPage.tsx): `src/features/question-bank/components/QuestionBankPage.tsx`
- [Question extraction](https://github.com/rat-sh/x-pert2/blob/main/src/features/question-extraction/components/QuestionExtractionUpload.tsx): `src/features/question-extraction/components/QuestionExtractionUpload.tsx`
- [Materials manager](https://github.com/rat-sh/x-pert2/blob/main/src/features/study-materials/components/teacher/MaterialsManagerPage.tsx): `src/features/study-materials/components/teacher/MaterialsManagerPage.tsx`
- [Teacher results](https://github.com/rat-sh/x-pert2/blob/main/src/features/teacher-results/components/TeacherResultsPage.tsx): `src/features/teacher-results/components/TeacherResultsPage.tsx`

### Student experience

- [Batch enrollment](https://github.com/rat-sh/x-pert2/blob/main/src/features/student-join/components/StudentJoinPage.tsx): `src/features/student-join/components/StudentJoinPage.tsx`
- [Available exams](https://github.com/rat-sh/x-pert2/blob/main/src/features/student-exams/components/StudentExamsPage.tsx): `src/features/student-exams/components/StudentExamsPage.tsx`
- [Timed exam session](https://github.com/rat-sh/x-pert2/blob/main/app/student/exams/%5BexamId%5D/take/page.tsx): `app/student/exams/[examId]/take/page.tsx`
- [Student results](https://github.com/rat-sh/x-pert2/blob/main/src/features/student-results/components/StudentResultsPage.tsx): `src/features/student-results/components/StudentResultsPage.tsx`
- [Upcoming exams](https://github.com/rat-sh/x-pert2/blob/main/src/features/upcoming-exams/components/UpcomingExamsPage.tsx): `src/features/upcoming-exams/components/UpcomingExamsPage.tsx`
- [Study materials](https://github.com/rat-sh/x-pert2/blob/main/src/features/study-materials/components/student/MaterialsBrowserPage.tsx): `src/features/study-materials/components/student/MaterialsBrowserPage.tsx`

### Platform services

- [Extraction API](https://github.com/rat-sh/x-pert2/blob/main/app/api/questions/extract/route.ts): `app/api/questions/extract/route.ts`
- [Supabase backend](https://github.com/rat-sh/x-pert2/blob/main/src/shared/services/supabase-client.ts): `src/shared/services/supabase-client.ts`
- [Supabase storage](https://github.com/rat-sh/x-pert2/blob/main/src/shared/services/storage.service.ts): `src/shared/services/storage.service.ts`

### Other components

- **Teacher**
- **Student**
- **Gemini extraction**

## Connections

- Teacher → Sign up: signs up
- Sign up → Auth service: submits credentials (evidence: `src/features/auth/components/SignupForm.tsx`)
- Auth service → Supabase backend: authenticates (evidence: `src/features/auth/services/auth.service.ts`)
- Auth context → Auth service: loads profile (evidence: `src/contexts/AuthContext.tsx`)
- Teacher → Batch management: creates batches
- Batch management → Supabase backend: reads and writes
- Batch management → Calendar scheduling: creates sessions
- Teacher → Exam creation: creates exams
- Exam creation → Paper builder: builds paper
- Exam creation → Question bank: sources questions
- Teacher → Question extraction: uploads questions
- Question extraction → Extraction API: submits file
- Extraction API → Gemini extraction: requests extraction (evidence: `app/api/questions/extract/route.ts`)
- Teacher → Materials manager: manages materials
- Materials manager → Supabase storage: uploads files
- Teacher → Teacher results: reviews results
- Student → Batch enrollment: joins by code
- Batch enrollment → Supabase backend: enrolls student
- Student → Available exams: views exams
- Available exams → Timed exam session: starts exam
- Timed exam session → Student results: submits answers
- Student → Upcoming exams: checks schedule
- Student → Study materials: views materials