# mghashim/teacher-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/mghashim/teacher-assistant
- Repository: https://github.com/mghashim/teacher-assistant

## Overview

Teacher Assistant is an offline-first browser app for teachers. The main workflow runs from the dashboard or routed feature pages through class, student, timetable, assessment, and task management, with records stored locally in IndexedDB. Backup and restore protect that local data; settings cover academic-year and theme preferences. The graph preserves documented product areas, but most feature-to-storage calls were not excerpted, so those links are marked unverified rather than inferred as confirmed calls.

Main entry points: [`src/router/AppRouter.tsx`](https://github.com/mghashim/teacher-assistant/blob/main/src/router/AppRouter.tsx) (Page routing), [`src/db/database.ts`](https://github.com/mghashim/teacher-assistant/blob/main/src/db/database.ts) (IndexedDB), [`src/features/grades/GradesPage.tsx`](https://github.com/mghashim/teacher-assistant/blob/main/src/features/grades/GradesPage.tsx) (Assessments & grades), [`src/features/classes/ClassesPage.tsx`](https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/ClassesPage.tsx) (Classes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_router["Page routing<br/>[AppRouter.tsx]"]
  node_layout["App layout<br/>[AppLayout.tsx]"]
end

subgraph group_teaching["Teaching workflow"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_classes["Classes<br/>[ClassesPage.tsx]"]
  node_classdetail["Class details"]
  node_timetable["Timetable<br/>[TimetablePage.tsx]"]
  node_lessons["Lesson progress"]
  node_grades["Assessments &amp; grades<br/>[GradesPage.tsx]"]
  node_gradecalc["Grade calculations<br/>[calculations.ts]"]
  node_tasks["Tasks<br/>[TasksPage.tsx]"]
end

subgraph group_records["Student records"]
  node_students["Student directory<br/>[StudentsPage.tsx]"]
  node_profile["Student profiles"]
  node_studentmodal["Student editor<br/>[StudentModal.tsx]"]
  node_excel["Grade export<br/>[excelExport.ts]"]
end

subgraph group_local["Local data"]
  node_settings["Settings<br/>[SettingsPage.tsx]"]
  node_backup["Backup &amp; restore<br/>[backup.service.ts]"]
  node_autobackup["Backup reminders"]
  node_database[("IndexedDB<br/>[database.ts]")]
  node_types["Domain records<br/>[database.ts]"]
end

subgraph group_shared["Shared UI"]
  node_button["Button primitive<br/>[Button.tsx]"]
  node_badge["Badge primitive<br/>[Badge.tsx]"]
  node_card["Card primitive<br/>[Card.tsx]"]
  node_confirm["Confirmation dialog"]
  node_empty["Empty state<br/>[EmptyState.tsx]"]
  node_input["Input primitive<br/>[Input.tsx]"]
  node_modal["Modal primitive<br/>[Modal.tsx]"]
end

node_teacher(("Teacher"))

node_teacher -->|"opens app"| node_router
node_router -->|"routes through"| node_layout
node_router -->|"routes to"| node_dashboard
node_router -->|"routes to"| node_classes
node_router -->|"routes to"| node_classdetail
node_router -->|"routes to"| node_students
node_router -->|"routes to"| node_profile
node_router -->|"routes to"| node_grades
node_router -->|"routes to"| node_tasks
node_router -->|"routes to"| node_timetable
node_dashboard -->|"opens quick actions"| node_classes
node_classes -.->|"opens class"| node_classdetail
node_classdetail -->|"shows progress"| node_lessons
node_students -.->|"opens profile"| node_profile
node_profile -.->|"edits student"| node_studentmodal
node_grades -.->|"calculates averages"| node_gradecalc
node_grades -.->|"exports marks"| node_excel
node_layout -->|"mounts manager"| node_autobackup
node_autobackup -->|"triggers backup"| node_backup
node_autobackup -->|"checks backup state"| node_settings
node_settings -->|"exports or restores"| node_backup
node_backup -->|"reads and writes"| node_database
node_database -->|"types tables"| node_types
node_classes -.->|"persists class data"| node_database
node_classdetail -.->|"reads class data"| node_database
node_timetable -.->|"reads schedules"| node_database
node_grades -.->|"persists grade data"| node_database
node_students -.->|"persists pupil data"| node_database
node_tasks -.->|"persists tasks"| node_database
node_confirm -->|"renders in"| node_modal
node_confirm -->|"uses password input"| node_input
node_confirm -->|"uses actions"| node_button

click node_router "https://github.com/mghashim/teacher-assistant/blob/main/src/router/AppRouter.tsx"
click node_layout "https://github.com/mghashim/teacher-assistant/blob/main/src/components/layout/AppLayout.tsx"
click node_dashboard "https://github.com/mghashim/teacher-assistant/blob/main/src/features/dashboard/DashboardPage.tsx"
click node_classes "https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/ClassesPage.tsx"
click node_classdetail "https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/ClassDetailPage.tsx"
click node_timetable "https://github.com/mghashim/teacher-assistant/blob/main/src/features/timetable/TimetablePage.tsx"
click node_lessons "https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/lessons/LessonsProgressTab.tsx"
click node_grades "https://github.com/mghashim/teacher-assistant/blob/main/src/features/grades/GradesPage.tsx"
click node_gradecalc "https://github.com/mghashim/teacher-assistant/blob/main/src/lib/calculations.ts"
click node_tasks "https://github.com/mghashim/teacher-assistant/blob/main/src/features/tasks/TasksPage.tsx"
click node_students "https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentsPage.tsx"
click node_profile "https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentProfilePage.tsx"
click node_studentmodal "https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentModal.tsx"
click node_excel "https://github.com/mghashim/teacher-assistant/blob/main/src/lib/excelExport.ts"
click node_settings "https://github.com/mghashim/teacher-assistant/blob/main/src/features/settings/SettingsPage.tsx"
click node_backup "https://github.com/mghashim/teacher-assistant/blob/main/src/db/backup/backup.service.ts"
click node_autobackup "https://github.com/mghashim/teacher-assistant/blob/main/src/components/layout/AutoBackupManager.tsx"
click node_database "https://github.com/mghashim/teacher-assistant/blob/main/src/db/database.ts"
click node_types "https://github.com/mghashim/teacher-assistant/blob/main/src/types/database.ts"
click node_button "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Button.tsx"
click node_badge "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Badge.tsx"
click node_card "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Card.tsx"
click node_confirm "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/ConfirmationModal.tsx"
click node_empty "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/EmptyState.tsx"
click node_input "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Input.tsx"
click node_modal "https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Modal.tsx"

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_router,node_layout toneBlue
class node_dashboard,node_classes,node_classdetail,node_timetable,node_lessons,node_grades,node_gradecalc,node_tasks toneAmber
class node_students,node_profile,node_studentmodal,node_excel toneMint
class node_settings,node_backup,node_autobackup,node_database,node_types toneRose
class node_button,node_badge,node_card,node_confirm,node_empty,node_input,node_modal,node_teacher toneIndigo
```

## Components

### App shell

- [Page routing](https://github.com/mghashim/teacher-assistant/blob/main/src/router/AppRouter.tsx): `src/router/AppRouter.tsx`
- [App layout](https://github.com/mghashim/teacher-assistant/blob/main/src/components/layout/AppLayout.tsx): `src/components/layout/AppLayout.tsx`

### Teaching workflow

- [Dashboard](https://github.com/mghashim/teacher-assistant/blob/main/src/features/dashboard/DashboardPage.tsx): `src/features/dashboard/DashboardPage.tsx`
- [Classes](https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/ClassesPage.tsx): `src/features/classes/ClassesPage.tsx`
- [Class details](https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/ClassDetailPage.tsx): `src/features/classes/ClassDetailPage.tsx`
- [Timetable](https://github.com/mghashim/teacher-assistant/blob/main/src/features/timetable/TimetablePage.tsx): `src/features/timetable/TimetablePage.tsx`
- [Lesson progress](https://github.com/mghashim/teacher-assistant/blob/main/src/features/classes/lessons/LessonsProgressTab.tsx): `src/features/classes/lessons/LessonsProgressTab.tsx`
- [Assessments & grades](https://github.com/mghashim/teacher-assistant/blob/main/src/features/grades/GradesPage.tsx): `src/features/grades/GradesPage.tsx`
- [Grade calculations](https://github.com/mghashim/teacher-assistant/blob/main/src/lib/calculations.ts): `src/lib/calculations.ts`
- [Tasks](https://github.com/mghashim/teacher-assistant/blob/main/src/features/tasks/TasksPage.tsx): `src/features/tasks/TasksPage.tsx`

### Student records

- [Student directory](https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentsPage.tsx): `src/features/students/StudentsPage.tsx`
- [Student profiles](https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentProfilePage.tsx): `src/features/students/StudentProfilePage.tsx`
- [Student editor](https://github.com/mghashim/teacher-assistant/blob/main/src/features/students/StudentModal.tsx): `src/features/students/StudentModal.tsx`
- [Grade export](https://github.com/mghashim/teacher-assistant/blob/main/src/lib/excelExport.ts): `src/lib/excelExport.ts`

### Local data

- [Settings](https://github.com/mghashim/teacher-assistant/blob/main/src/features/settings/SettingsPage.tsx): `src/features/settings/SettingsPage.tsx`
- [Backup & restore](https://github.com/mghashim/teacher-assistant/blob/main/src/db/backup/backup.service.ts): `src/db/backup/backup.service.ts`
- [Backup reminders](https://github.com/mghashim/teacher-assistant/blob/main/src/components/layout/AutoBackupManager.tsx): `src/components/layout/AutoBackupManager.tsx`
- [IndexedDB](https://github.com/mghashim/teacher-assistant/blob/main/src/db/database.ts): `src/db/database.ts`
- [Domain records](https://github.com/mghashim/teacher-assistant/blob/main/src/types/database.ts): `src/types/database.ts`

### Shared UI

- [Button primitive](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Button.tsx): `src/components/ui/Button.tsx`
- [Badge primitive](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Badge.tsx): `src/components/ui/Badge.tsx`
- [Card primitive](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Card.tsx): `src/components/ui/Card.tsx`
- [Confirmation dialog](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/ConfirmationModal.tsx): `src/components/ui/ConfirmationModal.tsx`
- [Empty state](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/EmptyState.tsx): `src/components/ui/EmptyState.tsx`
- [Input primitive](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Input.tsx): `src/components/ui/Input.tsx`
- [Modal primitive](https://github.com/mghashim/teacher-assistant/blob/main/src/components/ui/Modal.tsx): `src/components/ui/Modal.tsx`

### Other components

- **Teacher**

## Connections

- Teacher → Page routing: opens app
- Page routing → App layout: routes through (evidence: `src/router/AppRouter.tsx`)
- Page routing → Dashboard: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Classes: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Class details: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Student directory: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Student profiles: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Assessments & grades: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Tasks: routes to (evidence: `src/router/AppRouter.tsx`)
- Page routing → Timetable: routes to (evidence: `src/router/AppRouter.tsx`)
- Dashboard → Classes: opens quick actions (evidence: `src/features/dashboard/DashboardPage.tsx`)
- Classes → Class details: opens class
- Class details → Lesson progress: shows progress (evidence: `src/features/classes/ClassDetailPage.tsx`)
- Student directory → Student profiles: opens profile
- Student profiles → Student editor: edits student
- Assessments & grades → Grade calculations: calculates averages
- Assessments & grades → Grade export: exports marks
- App layout → Backup reminders: mounts manager (evidence: `src/components/layout/AppLayout.tsx`)
- Backup reminders → Backup & restore: triggers backup (evidence: `src/components/layout/AutoBackupManager.tsx`)
- Backup reminders → Settings: checks backup state (evidence: `src/components/layout/AutoBackupManager.tsx`)
- Settings → Backup & restore: exports or restores (evidence: `src/features/settings/SettingsPage.tsx`)
- Backup & restore → IndexedDB: reads and writes (evidence: `src/db/backup/backup.service.ts`)
- IndexedDB → Domain records: types tables (evidence: `src/db/database.ts`)
- Classes → IndexedDB: persists class data
- Class details → IndexedDB: reads class data (evidence: `src/features/classes/ClassDetailPage.tsx`)
- Timetable → IndexedDB: reads schedules (evidence: `src/features/timetable/TimetablePage.tsx`)
- Assessments & grades → IndexedDB: persists grade data
- Student directory → IndexedDB: persists pupil data
- Tasks → IndexedDB: persists tasks (evidence: `src/features/tasks/TasksPage.tsx`)
- Confirmation dialog → Modal primitive: renders in (evidence: `src/components/ui/ConfirmationModal.tsx`)
- Confirmation dialog → Input primitive: uses password input (evidence: `src/components/ui/ConfirmationModal.tsx`)
- Confirmation dialog → Button primitive: uses actions (evidence: `src/components/ui/ConfirmationModal.tsx`)
