# arjundevjha/paperforge architecture

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

- Interactive diagram: https://gitdiagram.com/arjundevjha/paperforge
- Repository: https://github.com/arjundevjha/paperforge

## Overview

PaperForge is a Singapore A-Level question-bank and worksheet platform. Its central workflow brings examination papers into the system, extracts and aligns questions with marking schemes, classifies and deduplicates items, then lets teachers review the bank and generate worksheets with matching answer keys. The graph combines documented capabilities with relationships visible in the supplied excerpts and source index; some intake and UI wiring is documented only at a high level.

Main entry points: [`packages/db/src/store.ts`](https://github.com/arjundevjha/paperforge/blob/main/packages/db/src/store.ts) (Question Data Store), [`packages/ingestion/src/pipeline.ts`](https://github.com/arjundevjha/paperforge/blob/main/packages/ingestion/src/pipeline.ts) (Ingestion Pipeline), [`apps/web/src/app/api/questions/route.ts`](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/questions/route.ts) (Questions API), [`apps/web/src/app/api/worksheets/route.ts`](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/worksheets/route.ts) (Worksheets API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Teacher Web App"]
  node_hub["Resource Hub"]
  node_source_console["Source Console<br/>[SourcesConsole.tsx]"]
  node_question_bank_ui["Question Bank"]
  node_review_ui["Review Queue UI<br/>[ReviewQueue.tsx]"]
  node_review_api["Review API<br/>[route.ts]"]
  node_questions_api["Questions API<br/>[route.ts]"]
end

subgraph group_intake["Paper Intake"]
  node_sources_api["Source API<br/>[route.ts]"]
  node_ingestion["Ingestion Pipeline<br/>[pipeline.ts]"]
end

subgraph group_domain["Question Processing"]
  node_question_parser["Question Parser<br/>[parser.ts]"]
  node_syllabus["SEAB Syllabus<br/>[syllabus.ts]"]
  node_classification["Topic Classification<br/>[matcher.ts]"]
  node_dedup["Duplicate Detection<br/>[classifier.ts]"]
end

subgraph group_data["Data and Storage"]
  node_store[("Question Data Store<br/>[store.ts]")]
  node_storage["File Storage Providers<br/>[index.ts]"]
  node_db_sync["Supabase Sync<br/>[db-sync.ts]"]
end

subgraph group_delivery["Worksheet Delivery"]
  node_worksheets_api["Worksheets API<br/>[route.ts]"]
  node_worksheet_engine["Worksheet Engine<br/>[engine.ts]"]
  node_pdf_compiler["A4 PDF Compiler<br/>[compiler.ts]"]
end

node_teacher(("Teacher or Tutor"))

node_teacher -->|"uses"| node_hub
node_hub -.->|"opens"| node_source_console
node_source_console -.->|"uploads papers"| node_sources_api
node_sources_api -->|"lists files"| node_storage
node_teacher -->|"submits papers"| node_ingestion
node_ingestion -->|"extracts questions"| node_question_parser
node_ingestion -->|"gets provider"| node_storage
node_ingestion -->|"ingests package"| node_store
node_ingestion -->|"hashes text"| node_dedup
node_question_parser -.->|"classifies items"| node_classification
node_classification -->|"aligns topics"| node_syllabus
node_store -->|"classifies seeded items"| node_classification
node_store -->|"checks duplicates"| node_dedup
node_teacher -->|"browses bank"| node_question_bank_ui
node_question_bank_ui -.->|"requests questions"| node_questions_api
node_questions_api -->|"lists questions"| node_store
node_questions_api -->|"syncs questions"| node_db_sync
node_teacher -->|"verifies items"| node_review_ui
node_review_ui -.->|"resolves review"| node_review_api
node_review_api -->|"updates review"| node_store
node_teacher -->|"requests worksheet"| node_worksheets_api
node_worksheets_api -->|"loads questions"| node_store
node_worksheets_api -->|"builds manifest"| node_worksheet_engine
node_worksheet_engine -->|"generates PDFs"| node_pdf_compiler

click node_hub "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/hub/TeacherResourceHub.tsx"
click node_source_console "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/sources/SourcesConsole.tsx"
click node_question_bank_ui "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/questions/QuestionBankMatrix.tsx"
click node_review_ui "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/review/ReviewQueue.tsx"
click node_sources_api "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/sources/route.ts"
click node_ingestion "https://github.com/arjundevjha/paperforge/blob/main/packages/ingestion/src/pipeline.ts"
click node_question_parser "https://github.com/arjundevjha/paperforge/blob/main/packages/questions/src/parser.ts"
click node_syllabus "https://github.com/arjundevjha/paperforge/blob/main/packages/shared/src/syllabus.ts"
click node_classification "https://github.com/arjundevjha/paperforge/blob/main/packages/classification/src/matcher.ts"
click node_dedup "https://github.com/arjundevjha/paperforge/blob/main/packages/dedup/src/classifier.ts"
click node_review_api "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/review/route.ts"
click node_questions_api "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/questions/route.ts"
click node_store "https://github.com/arjundevjha/paperforge/blob/main/packages/db/src/store.ts"
click node_storage "https://github.com/arjundevjha/paperforge/blob/main/packages/storage/src/index.ts"
click node_db_sync "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/lib/supabase/db-sync.ts"
click node_worksheets_api "https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/worksheets/route.ts"
click node_worksheet_engine "https://github.com/arjundevjha/paperforge/blob/main/packages/worksheets/src/engine.ts"
click node_pdf_compiler "https://github.com/arjundevjha/paperforge/blob/main/packages/pdf/src/compiler.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_hub,node_source_console,node_question_bank_ui,node_review_ui,node_review_api,node_questions_api toneBlue
class node_sources_api,node_ingestion toneAmber
class node_question_parser,node_syllabus,node_classification,node_dedup toneMint
class node_store,node_storage,node_db_sync toneRose
class node_worksheets_api,node_worksheet_engine,node_pdf_compiler,node_teacher toneIndigo
```

## Components

### Teacher Web App

- [Resource Hub](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/hub/TeacherResourceHub.tsx): `apps/web/src/components/hub/TeacherResourceHub.tsx`
- [Source Console](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/sources/SourcesConsole.tsx): `apps/web/src/components/sources/SourcesConsole.tsx`
- [Question Bank](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/questions/QuestionBankMatrix.tsx): `apps/web/src/components/questions/QuestionBankMatrix.tsx`
- [Review Queue UI](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/components/review/ReviewQueue.tsx): `apps/web/src/components/review/ReviewQueue.tsx`
- [Review API](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/review/route.ts): `apps/web/src/app/api/review/route.ts`
- [Questions API](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/questions/route.ts): `apps/web/src/app/api/questions/route.ts`

### Paper Intake

- [Source API](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/sources/route.ts): `apps/web/src/app/api/sources/route.ts`
- [Ingestion Pipeline](https://github.com/arjundevjha/paperforge/blob/main/packages/ingestion/src/pipeline.ts): `packages/ingestion/src/pipeline.ts`

### Question Processing

- [Question Parser](https://github.com/arjundevjha/paperforge/blob/main/packages/questions/src/parser.ts): `packages/questions/src/parser.ts`
- [SEAB Syllabus](https://github.com/arjundevjha/paperforge/blob/main/packages/shared/src/syllabus.ts): `packages/shared/src/syllabus.ts`
- [Topic Classification](https://github.com/arjundevjha/paperforge/blob/main/packages/classification/src/matcher.ts): `packages/classification/src/matcher.ts`
- [Duplicate Detection](https://github.com/arjundevjha/paperforge/blob/main/packages/dedup/src/classifier.ts): `packages/dedup/src/classifier.ts`

### Data and Storage

- [Question Data Store](https://github.com/arjundevjha/paperforge/blob/main/packages/db/src/store.ts): `packages/db/src/store.ts`
- [File Storage Providers](https://github.com/arjundevjha/paperforge/blob/main/packages/storage/src/index.ts): `packages/storage/src/index.ts`
- [Supabase Sync](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/lib/supabase/db-sync.ts): `apps/web/src/lib/supabase/db-sync.ts`

### Worksheet Delivery

- [Worksheets API](https://github.com/arjundevjha/paperforge/blob/main/apps/web/src/app/api/worksheets/route.ts): `apps/web/src/app/api/worksheets/route.ts`
- [Worksheet Engine](https://github.com/arjundevjha/paperforge/blob/main/packages/worksheets/src/engine.ts): `packages/worksheets/src/engine.ts`
- [A4 PDF Compiler](https://github.com/arjundevjha/paperforge/blob/main/packages/pdf/src/compiler.ts): `packages/pdf/src/compiler.ts`

### Other components

- **Teacher or Tutor**

## Connections

- Teacher or Tutor → Resource Hub: uses
- Resource Hub → Source Console: opens
- Source Console → Source API: uploads papers
- Source API → File Storage Providers: lists files (evidence: `apps/web/src/app/api/sources/route.ts`)
- Teacher or Tutor → Ingestion Pipeline: submits papers
- Ingestion Pipeline → Question Parser: extracts questions
- Ingestion Pipeline → File Storage Providers: gets provider (evidence: `packages/ingestion/src/pipeline.ts`)
- Ingestion Pipeline → Question Data Store: ingests package (evidence: `packages/ingestion/src/pipeline.ts`)
- Ingestion Pipeline → Duplicate Detection: hashes text (evidence: `packages/ingestion/src/pipeline.ts`)
- Question Parser → Topic Classification: classifies items
- Topic Classification → SEAB Syllabus: aligns topics (evidence: `packages/classification/src/matcher.ts`)
- Question Data Store → Topic Classification: classifies seeded items
- Question Data Store → Duplicate Detection: checks duplicates
- Teacher or Tutor → Question Bank: browses bank
- Question Bank → Questions API: requests questions
- Questions API → Question Data Store: lists questions (evidence: `apps/web/src/app/api/questions/route.ts`)
- Questions API → Supabase Sync: syncs questions (evidence: `apps/web/src/app/api/questions/route.ts`)
- Teacher or Tutor → Review Queue UI: verifies items
- Review Queue UI → Review API: resolves review
- Review API → Question Data Store: updates review (evidence: `apps/web/src/app/api/review/route.ts`)
- Teacher or Tutor → Worksheets API: requests worksheet
- Worksheets API → Question Data Store: loads questions (evidence: `apps/web/src/app/api/worksheets/route.ts`)
- Worksheets API → Worksheet Engine: builds manifest (evidence: `apps/web/src/app/api/worksheets/route.ts`)
- Worksheet Engine → A4 PDF Compiler: generates PDFs (evidence: `packages/worksheets/src/engine.ts`)
