# parvincodes/kgs_gurmatstudies architecture

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

## Overview

Khalsa Gurmat School is an early-preview study portal for students, teachers, and parents. Its main operational workflow lets teachers upload materials, review and approve them, and make approved items available for browsing and preview; parent surveys provide a separate input-and-results workflow. The portal also includes Sikh Empire history content and a Japji Sahib assistant. The graph preserves mock and placeholder capabilities documented in the README. Some client-to-API wiring is not visible in the excerpts, so uncertain relationships are omitted.

Main entry points: [`src/lib/materials-db.ts`](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/materials-db.ts) (Materials records), [`src/app/history/sikh-empire/page.tsx`](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/history/sikh-empire/page.tsx) (Sikh Empire history), [`src/app/upload/page.tsx`](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/upload/page.tsx) (Teacher upload), [`src/app/review/page.tsx`](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/review/page.tsx) (Material review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Portal and study"]
  node_home["Home and program<br/>[page.tsx]"]
  node_materials_page["Sample materials<br/>[page.tsx]"]
  node_progress["Progress preview<br/>[page.tsx]"]
  node_login["Login placeholder<br/>[page.tsx]"]
end

subgraph group_materials["Materials workflow"]
  node_upload_page["Teacher upload<br/>[page.tsx]"]
  node_review_page["Material review<br/>[page.tsx]"]
  node_upload_api["Upload API<br/>[route.ts]"]
  node_materials_api["Materials API<br/>[route.ts]"]
  node_material_api["Material detail API<br/>[route.ts]"]
  node_public_materials_api["Public materials API<br/>[route.ts]"]
  node_materials_db["Materials records<br/>[materials-db.ts]"]
  node_postgres[("Postgres")]
  node_blob[("Vercel Blob")]
  node_preview["File preview panel"]
end

subgraph group_survey["Parent survey"]
  node_survey_page["Parent survey<br/>[page.tsx]"]
  node_survey_api["Survey API<br/>[route.ts]"]
  node_survey_results["Survey results<br/>[page.tsx]"]
  node_survey_db["Survey responses<br/>[survey-db.ts]"]
end

subgraph group_learning["Learning features"]
  node_history_page["Sikh Empire history<br/>[page.tsx]"]
  node_chronology["Chronology data"]
  node_timeline["Event timeline<br/>[EventTimeline.tsx]"]
  node_lifespans["Lifespans chart<br/>[LifespansChart.tsx]"]
end

subgraph group_assistant["Japji assistant"]
  node_search_widget["Search widget<br/>[SearchWidget.tsx]"]
  node_japji_detect["Japji detection<br/>[japji-detect.ts]"]
  node_japji_api["Japji chat API<br/>[route.ts]"]
  node_japji_agent["Japji assistant<br/>[japji-agent.ts]"]
  node_anthropic["Anthropic Claude"]
end

node_students(("Students and visitors"))
node_teachers(("Teachers"))
node_parents(("Parents"))

node_students -->|"browse"| node_home
node_students -->|"browse"| node_materials_page
node_students -->|"view preview"| node_progress
node_teachers -->|"upload materials"| node_upload_page
node_teachers -->|"review materials"| node_review_page
node_parents -->|"submit answers"| node_survey_page
node_upload_page -->|"requests upload"| node_upload_api
node_upload_api -->|"stores file"| node_blob
node_upload_page -->|"saves metadata"| node_materials_api
node_review_page -->|"loads materials"| node_materials_api
node_materials_api -->|"reads and writes"| node_materials_db
node_material_api -->|"updates records"| node_materials_db
node_public_materials_api -->|"reads approved"| node_materials_db
node_materials_db -->|"queries"| node_postgres
node_review_page -->|"opens preview"| node_preview
node_survey_page -->|"submits responses"| node_survey_api
node_survey_results -->|"loads results"| node_survey_api
node_survey_api -->|"creates and lists"| node_survey_db
node_survey_db -->|"queries"| node_postgres
node_history_page -->|"reads chronology"| node_chronology
node_history_page -->|"renders events"| node_timeline
node_history_page -->|"renders lifespans"| node_lifespans
node_search_widget -->|"detects topic"| node_japji_detect
node_search_widget -->|"opens result"| node_preview
node_japji_api -->|"delegates answer"| node_japji_agent
node_japji_agent -->|"asks Claude"| node_anthropic

click node_home "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/page.tsx"
click node_materials_page "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/materials/page.tsx"
click node_progress "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/progress/page.tsx"
click node_login "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/login/page.tsx"
click node_upload_page "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/upload/page.tsx"
click node_review_page "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/review/page.tsx"
click node_upload_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/upload/route.ts"
click node_materials_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/materials/route.ts"
click node_material_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/materials/%5Bid%5D/route.ts"
click node_public_materials_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/public/materials/route.ts"
click node_materials_db "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/materials-db.ts"
click node_preview "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/FilePreviewPanel.tsx"
click node_survey_page "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/survey/page.tsx"
click node_survey_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/survey/route.ts"
click node_survey_results "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/survey/results/page.tsx"
click node_survey_db "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/survey-db.ts"
click node_history_page "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/history/sikh-empire/page.tsx"
click node_chronology "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/sikh-empire-chronology.ts"
click node_timeline "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/history/EventTimeline.tsx"
click node_lifespans "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/history/LifespansChart.tsx"
click node_search_widget "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/SearchWidget.tsx"
click node_japji_detect "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/japji-detect.ts"
click node_japji_api "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/japji-chat/route.ts"
click node_japji_agent "https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/japji-agent.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_home,node_materials_page,node_progress,node_login toneBlue
class node_upload_page,node_review_page,node_upload_api,node_materials_api,node_material_api,node_public_materials_api,node_materials_db,node_postgres,node_blob,node_preview toneAmber
class node_survey_page,node_survey_api,node_survey_results,node_survey_db toneMint
class node_history_page,node_chronology,node_timeline,node_lifespans toneRose
class node_search_widget,node_japji_detect,node_japji_api,node_japji_agent,node_anthropic,node_students,node_teachers,node_parents toneIndigo
```

## Components

### Portal and study

- [Home and program](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Sample materials](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/materials/page.tsx): `src/app/materials/page.tsx`
- [Progress preview](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/progress/page.tsx): `src/app/progress/page.tsx`
- [Login placeholder](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`

### Materials workflow

- [Teacher upload](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/upload/page.tsx): `src/app/upload/page.tsx`
- [Material review](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/review/page.tsx): `src/app/review/page.tsx`
- [Upload API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [Materials API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/materials/route.ts): `src/app/api/materials/route.ts`
- [Material detail API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/materials/%5Bid%5D/route.ts): `src/app/api/materials/[id]/route.ts`
- [Public materials API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/public/materials/route.ts): `src/app/api/public/materials/route.ts`
- [Materials records](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/materials-db.ts): `src/lib/materials-db.ts`
- **Postgres**
- **Vercel Blob**
- [File preview panel](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/FilePreviewPanel.tsx): `src/components/FilePreviewPanel.tsx`

### Parent survey

- [Parent survey](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/survey/page.tsx): `src/app/survey/page.tsx`
- [Survey API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/survey/route.ts): `src/app/api/survey/route.ts`
- [Survey results](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/survey/results/page.tsx): `src/app/survey/results/page.tsx`
- [Survey responses](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/survey-db.ts): `src/lib/survey-db.ts`

### Learning features

- [Sikh Empire history](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/history/sikh-empire/page.tsx): `src/app/history/sikh-empire/page.tsx`
- [Chronology data](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/sikh-empire-chronology.ts): `src/lib/sikh-empire-chronology.ts`
- [Event timeline](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/history/EventTimeline.tsx): `src/components/history/EventTimeline.tsx`
- [Lifespans chart](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/history/LifespansChart.tsx): `src/components/history/LifespansChart.tsx`

### Japji assistant

- [Search widget](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/components/SearchWidget.tsx): `src/components/SearchWidget.tsx`
- [Japji detection](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/japji-detect.ts): `src/lib/japji-detect.ts`
- [Japji chat API](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/app/api/japji-chat/route.ts): `src/app/api/japji-chat/route.ts`
- [Japji assistant](https://github.com/parvincodes/kgs_gurmatstudies/blob/main/src/lib/japji-agent.ts): `src/lib/japji-agent.ts`
- **Anthropic Claude**

### Other components

- **Students and visitors**
- **Teachers**
- **Parents**

## Connections

- Students and visitors → Home and program: browse
- Students and visitors → Sample materials: browse
- Students and visitors → Progress preview: view preview
- Teachers → Teacher upload: upload materials
- Teachers → Material review: review materials
- Parents → Parent survey: submit answers
- Teacher upload → Upload API: requests upload (evidence: `src/app/upload/page.tsx`)
- Upload API → Vercel Blob: stores file
- Teacher upload → Materials API: saves metadata
- Material review → Materials API: loads materials (evidence: `src/app/review/page.tsx`)
- Materials API → Materials records: reads and writes (evidence: `src/app/api/materials/route.ts`)
- Material detail API → Materials records: updates records (evidence: `src/app/api/materials/[id]/route.ts`)
- Public materials API → Materials records: reads approved (evidence: `src/app/api/public/materials/route.ts`)
- Materials records → Postgres: queries (evidence: `src/lib/materials-db.ts`)
- Material review → File preview panel: opens preview (evidence: `src/app/review/page.tsx`)
- Parent survey → Survey API: submits responses
- Survey results → Survey API: loads results
- Survey API → Survey responses: creates and lists (evidence: `src/app/api/survey/route.ts`)
- Survey responses → Postgres: queries (evidence: `src/lib/survey-db.ts`)
- Sikh Empire history → Chronology data: reads chronology (evidence: `src/app/history/sikh-empire/page.tsx`)
- Sikh Empire history → Event timeline: renders events (evidence: `src/app/history/sikh-empire/page.tsx`)
- Sikh Empire history → Lifespans chart: renders lifespans (evidence: `src/app/history/sikh-empire/page.tsx`)
- Search widget → Japji detection: detects topic (evidence: `src/components/SearchWidget.tsx`)
- Search widget → File preview panel: opens result (evidence: `src/components/SearchWidget.tsx`)
- Japji chat API → Japji assistant: delegates answer (evidence: `src/app/api/japji-chat/route.ts`)
- Japji assistant → Anthropic Claude: asks Claude