# tudoan21/doc2practice architecture

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

- Interactive diagram: https://gitdiagram.com/tudoan21/doc2practice
- Repository: https://github.com/tudoan21/doc2practice

## Overview

Doc2Practice is a browser-based learning platform that turns study materials into quizzes and flashcards, supports independent practice and classroom assessments, and tracks learning activity. The main path is learner → document/notes input → AI or offline generation → quiz/flashcard practice → results and history. Teachers also manage classes, assignments, and question banks; school administrators manage schools and subjects. The map reflects documented features and indexed dependencies; unsampled implementation details are not inferred beyond those links.

Main entry points: [`src/App.tsx`](https://github.com/tudoan21/doc2practice/blob/main/src/App.tsx) (Route dispatcher), [`src/pages/AIGenerateQuizPage.tsx`](https://github.com/tudoan21/doc2practice/blob/main/src/pages/AIGenerateQuizPage.tsx) (Quiz generation), [`src/services/assessmentService.ts`](https://github.com/tudoan21/doc2practice/blob/main/src/services/assessmentService.ts) (Assessment service), [`src/services/questionBankService.ts`](https://github.com/tudoan21/doc2practice/blob/main/src/services/questionBankService.ts) (Question bank service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry and identity"]
  node_app["Route dispatcher<br/>[App.tsx]"]
  node_auth["Sign in and profiles<br/>[auth.ts]"]
  node_protected["Protected routes<br/>[ProtectedRoute.tsx]"]
end

subgraph group_learning["Study creation and practice"]
  node_document_input["Documents and notes<br/>[DocumentsPage.tsx]"]
  node_generation["Quiz generation"]
  node_quiz_player["Quiz practice<br/>[QuizPlayerPage.tsx]"]
  node_flashcards["Flashcard review<br/>[FlashcardPage.tsx]"]
  node_history["Results and history<br/>[HistoryPage.tsx]"]
  node_dashboard["Learning dashboard<br/>[DashboardPage.tsx]"]
end

subgraph group_classroom["Classroom learning"]
  node_classrooms["Classroom workspace<br/>[ClassroomsPage.tsx]"]
  node_assessment_player["Assessment taking"]
  node_assessment_result["Assessment results"]
  node_question_bank["Question bank"]
end

subgraph group_management["School management"]
  node_school_admin["School administration"]
  node_subjects["Subject management"]
end

subgraph group_services["Core services"]
  node_ai_engine["AI and offline engine<br/>[aiService.ts]"]
  node_material_service["Material library<br/>[materialService.ts]"]
  node_quiz_storage[("Quiz and study data<br/>[storage.ts]")]
  node_class_service["Class and assignment service<br/>[classService.ts]"]
  node_assessment_service["Assessment service"]
  node_question_service[("Question bank service")]
  node_subjects_service[("Subject service<br/>[subjectService.ts]")]
  node_rbac["Permission checks<br/>[rbac.ts]"]
  node_audit[("Audit log<br/>[auditService.ts]")]
end

node_learner(("Learner"))
node_teacher(("Teacher"))
node_admin(("School admin"))
node_gemini{{"Google Gemini"}}

node_learner -->|"opens platform"| node_app
node_teacher -->|"opens platform"| node_app
node_admin -->|"opens platform"| node_app
node_app -->|"guards app routes"| node_protected
node_protected -->|"checks session"| node_auth
node_app -->|"routes to"| node_document_input
node_learner -->|"uploads or pastes"| node_document_input
node_document_input -->|"manages materials"| node_material_service
node_app -->|"routes to"| node_generation
node_learner -->|"requests study sets"| node_generation
node_generation -->|"uses materials"| node_material_service
node_generation -->|"generates content"| node_ai_engine
node_ai_engine -.->|"calls API"| node_gemini
node_generation -->|"stores generated sets"| node_quiz_storage
node_quiz_storage -->|"uses generation functions"| node_ai_engine
node_app -->|"routes to"| node_quiz_player
node_learner -->|"practices quizzes"| node_quiz_player
node_app -->|"routes to"| node_flashcards
node_learner -->|"reviews cards"| node_flashcards
node_app -->|"routes to"| node_history
node_learner -->|"tracks progress"| node_dashboard
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_classrooms
node_teacher -->|"manages classes"| node_classrooms
node_learner -->|"joins classes"| node_classrooms
node_classrooms -->|"manages class data"| node_class_service
node_app -->|"routes to"| node_assessment_player
node_assessment_player -->|"takes assessment"| node_assessment_service
node_app -->|"routes to"| node_assessment_result
node_assessment_result -->|"loads results"| node_assessment_service
node_app -->|"routes to"| node_question_bank
node_question_bank -->|"manages questions"| node_question_service
node_assessment_service -->|"loads bank questions"| node_question_service
node_app -->|"routes to"| node_school_admin
node_admin -->|"manages schools"| node_school_admin
node_app -->|"routes to"| node_subjects
node_subjects -.->|"manages subjects"| node_subjects_service
node_class_service -->|"checks permissions"| node_rbac
node_assessment_service -->|"checks permissions"| node_rbac
node_question_service -->|"checks permissions"| node_rbac
node_question_service -->|"records actions"| node_audit

click node_app "https://github.com/tudoan21/doc2practice/blob/main/src/App.tsx"
click node_auth "https://github.com/tudoan21/doc2practice/blob/main/src/services/auth.ts"
click node_protected "https://github.com/tudoan21/doc2practice/blob/main/src/components/auth/ProtectedRoute.tsx"
click node_document_input "https://github.com/tudoan21/doc2practice/blob/main/src/pages/DocumentsPage.tsx"
click node_generation "https://github.com/tudoan21/doc2practice/blob/main/src/pages/AIGenerateQuizPage.tsx"
click node_ai_engine "https://github.com/tudoan21/doc2practice/blob/main/src/services/aiService.ts"
click node_material_service "https://github.com/tudoan21/doc2practice/blob/main/src/services/materialService.ts"
click node_quiz_storage "https://github.com/tudoan21/doc2practice/blob/main/src/services/storage.ts"
click node_quiz_player "https://github.com/tudoan21/doc2practice/blob/main/src/pages/QuizPlayerPage.tsx"
click node_flashcards "https://github.com/tudoan21/doc2practice/blob/main/src/pages/FlashcardPage.tsx"
click node_history "https://github.com/tudoan21/doc2practice/blob/main/src/pages/HistoryPage.tsx"
click node_dashboard "https://github.com/tudoan21/doc2practice/blob/main/src/pages/DashboardPage.tsx"
click node_classrooms "https://github.com/tudoan21/doc2practice/blob/main/src/pages/ClassroomsPage.tsx"
click node_class_service "https://github.com/tudoan21/doc2practice/blob/main/src/services/classService.ts"
click node_assessment_service "https://github.com/tudoan21/doc2practice/blob/main/src/services/assessmentService.ts"
click node_assessment_player "https://github.com/tudoan21/doc2practice/blob/main/src/pages/TakeAssessmentPage.tsx"
click node_assessment_result "https://github.com/tudoan21/doc2practice/blob/main/src/pages/AssessmentResultPage.tsx"
click node_question_bank "https://github.com/tudoan21/doc2practice/blob/main/src/pages/QuestionBankPage.tsx"
click node_question_service "https://github.com/tudoan21/doc2practice/blob/main/src/services/questionBankService.ts"
click node_school_admin "https://github.com/tudoan21/doc2practice/blob/main/src/pages/SchoolsManagementPage.tsx"
click node_subjects "https://github.com/tudoan21/doc2practice/blob/main/src/pages/SubjectsManagementPage.tsx"
click node_subjects_service "https://github.com/tudoan21/doc2practice/blob/main/src/services/subjectService.ts"
click node_rbac "https://github.com/tudoan21/doc2practice/blob/main/src/services/rbac.ts"
click node_audit "https://github.com/tudoan21/doc2practice/blob/main/src/services/auditService.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_app,node_auth,node_protected toneBlue
class node_document_input,node_generation,node_quiz_player,node_flashcards,node_history,node_dashboard toneAmber
class node_classrooms,node_assessment_player,node_assessment_result,node_question_bank toneMint
class node_school_admin,node_subjects toneRose
class node_ai_engine,node_material_service,node_quiz_storage,node_class_service,node_assessment_service,node_question_service,node_subjects_service,node_rbac,node_audit,node_learner,node_teacher,node_admin,node_gemini toneIndigo
```

## Components

### App entry and identity

- [Route dispatcher](https://github.com/tudoan21/doc2practice/blob/main/src/App.tsx): `src/App.tsx`
- [Sign in and profiles](https://github.com/tudoan21/doc2practice/blob/main/src/services/auth.ts): `src/services/auth.ts`
- [Protected routes](https://github.com/tudoan21/doc2practice/blob/main/src/components/auth/ProtectedRoute.tsx): `src/components/auth/ProtectedRoute.tsx`

### Study creation and practice

- [Documents and notes](https://github.com/tudoan21/doc2practice/blob/main/src/pages/DocumentsPage.tsx): `src/pages/DocumentsPage.tsx`
- [Quiz generation](https://github.com/tudoan21/doc2practice/blob/main/src/pages/AIGenerateQuizPage.tsx): `src/pages/AIGenerateQuizPage.tsx`
- [Quiz practice](https://github.com/tudoan21/doc2practice/blob/main/src/pages/QuizPlayerPage.tsx): `src/pages/QuizPlayerPage.tsx`
- [Flashcard review](https://github.com/tudoan21/doc2practice/blob/main/src/pages/FlashcardPage.tsx): `src/pages/FlashcardPage.tsx`
- [Results and history](https://github.com/tudoan21/doc2practice/blob/main/src/pages/HistoryPage.tsx): `src/pages/HistoryPage.tsx`
- [Learning dashboard](https://github.com/tudoan21/doc2practice/blob/main/src/pages/DashboardPage.tsx): `src/pages/DashboardPage.tsx`

### Classroom learning

- [Classroom workspace](https://github.com/tudoan21/doc2practice/blob/main/src/pages/ClassroomsPage.tsx): `src/pages/ClassroomsPage.tsx`
- [Assessment taking](https://github.com/tudoan21/doc2practice/blob/main/src/pages/TakeAssessmentPage.tsx): `src/pages/TakeAssessmentPage.tsx`
- [Assessment results](https://github.com/tudoan21/doc2practice/blob/main/src/pages/AssessmentResultPage.tsx): `src/pages/AssessmentResultPage.tsx`
- [Question bank](https://github.com/tudoan21/doc2practice/blob/main/src/pages/QuestionBankPage.tsx): `src/pages/QuestionBankPage.tsx`

### School management

- [School administration](https://github.com/tudoan21/doc2practice/blob/main/src/pages/SchoolsManagementPage.tsx): `src/pages/SchoolsManagementPage.tsx`
- [Subject management](https://github.com/tudoan21/doc2practice/blob/main/src/pages/SubjectsManagementPage.tsx): `src/pages/SubjectsManagementPage.tsx`

### Core services

- [AI and offline engine](https://github.com/tudoan21/doc2practice/blob/main/src/services/aiService.ts): `src/services/aiService.ts`
- [Material library](https://github.com/tudoan21/doc2practice/blob/main/src/services/materialService.ts): `src/services/materialService.ts`
- [Quiz and study data](https://github.com/tudoan21/doc2practice/blob/main/src/services/storage.ts): `src/services/storage.ts`
- [Class and assignment service](https://github.com/tudoan21/doc2practice/blob/main/src/services/classService.ts): `src/services/classService.ts`
- [Assessment service](https://github.com/tudoan21/doc2practice/blob/main/src/services/assessmentService.ts): `src/services/assessmentService.ts`
- [Question bank service](https://github.com/tudoan21/doc2practice/blob/main/src/services/questionBankService.ts): `src/services/questionBankService.ts`
- [Subject service](https://github.com/tudoan21/doc2practice/blob/main/src/services/subjectService.ts): `src/services/subjectService.ts`
- [Permission checks](https://github.com/tudoan21/doc2practice/blob/main/src/services/rbac.ts): `src/services/rbac.ts`
- [Audit log](https://github.com/tudoan21/doc2practice/blob/main/src/services/auditService.ts): `src/services/auditService.ts`

### Other components

- **Learner**
- **Teacher**
- **School admin**
- **Google Gemini**

## Connections

- Learner → Route dispatcher: opens platform
- Teacher → Route dispatcher: opens platform
- School admin → Route dispatcher: opens platform
- Route dispatcher → Protected routes: guards app routes (evidence: `src/App.tsx`)
- Protected routes → Sign in and profiles: checks session (evidence: `src/components/auth/ProtectedRoute.tsx`)
- Route dispatcher → Documents and notes: routes to (evidence: `src/App.tsx`)
- Learner → Documents and notes: uploads or pastes
- Documents and notes → Material library: manages materials (evidence: `src/pages/DocumentsPage.tsx`)
- Route dispatcher → Quiz generation: routes to (evidence: `src/App.tsx`)
- Learner → Quiz generation: requests study sets
- Quiz generation → Material library: uses materials (evidence: `src/pages/AIGenerateQuizPage.tsx`)
- Quiz generation → AI and offline engine: generates content (evidence: `src/pages/AIGenerateQuizPage.tsx`)
- AI and offline engine → Google Gemini: calls API
- Quiz generation → Quiz and study data: stores generated sets (evidence: `src/services/storage.ts`)
- Quiz and study data → AI and offline engine: uses generation functions (evidence: `src/services/storage.ts`)
- Route dispatcher → Quiz practice: routes to (evidence: `src/App.tsx`)
- Learner → Quiz practice: practices quizzes
- Route dispatcher → Flashcard review: routes to (evidence: `src/App.tsx`)
- Learner → Flashcard review: reviews cards
- Route dispatcher → Results and history: routes to (evidence: `src/App.tsx`)
- Learner → Learning dashboard: tracks progress
- Route dispatcher → Learning dashboard: routes to (evidence: `src/App.tsx`)
- Route dispatcher → Classroom workspace: routes to (evidence: `src/App.tsx`)
- Teacher → Classroom workspace: manages classes
- Learner → Classroom workspace: joins classes
- Classroom workspace → Class and assignment service: manages class data (evidence: `src/pages/ClassroomsPage.tsx`)
- Route dispatcher → Assessment taking: routes to (evidence: `src/App.tsx`)
- Assessment taking → Assessment service: takes assessment (evidence: `src/pages/TakeAssessmentPage.tsx`)
- Route dispatcher → Assessment results: routes to (evidence: `src/App.tsx`)
- Assessment results → Assessment service: loads results (evidence: `src/pages/AssessmentResultPage.tsx`)
- Route dispatcher → Question bank: routes to (evidence: `src/App.tsx`)
- Question bank → Question bank service: manages questions (evidence: `src/pages/QuestionBankPage.tsx`)
- Assessment service → Question bank service: loads bank questions (evidence: `src/services/assessmentService.ts`)
- Route dispatcher → School administration: routes to (evidence: `src/App.tsx`)
- School admin → School administration: manages schools
- Route dispatcher → Subject management: routes to (evidence: `src/App.tsx`)
- Subject management → Subject service: manages subjects
- Class and assignment service → Permission checks: checks permissions (evidence: `src/services/classService.ts`)
- Assessment service → Permission checks: checks permissions (evidence: `src/services/assessmentService.ts`)
- Question bank service → Permission checks: checks permissions (evidence: `src/services/questionBankService.ts`)
- Question bank service → Audit log: records actions (evidence: `src/services/questionBankService.ts`)
