# kwarc/alea architecture

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

- Interactive diagram: https://gitdiagram.com/kwarc/alea
- Repository: https://github.com/kwarc/alea

## Overview

ALeA is a Next.js learning platform for course materials and learning activities, with additional job-portal and MathHub-query features. Learners and instructors enter through the web application, use course or specialized workflows, and receive rendered course content, activity results, or query results. Internal API routes support platform capabilities, while shared packages provide rendering and interaction utilities. The README establishes the frontend and sTeX-rendering purpose; sampled source supports the homework, query, job-portal, and comment details. Several connections to unsampled APIs are therefore left unverified.

Main entry points: [`packages/alea-frontend/components/HomeworkManager.tsx`](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkManager.tsx) (Homework management), [`packages/alea-frontend/pages/exp/mathhub-query.tsx`](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/exp/mathhub-query.tsx) (MathHub query page), [`packages/alea-frontend/pages/job-portal`](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/job-portal) (Job-portal pages), [`packages/alea-frontend/pages`](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages) (Next.js frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Next.js frontend"]
  node_mainlayout["Main layout<br/>[MainLayout.tsx]"]
  node_header["Site header<br/>[Header.tsx]"]
end

subgraph group_learning["Course learning"]
  node_coursepages["Course pages"]
  node_homeworkmanager["Homework management"]
  node_homeworkform["Homework form<br/>[HomeworkForm.tsx]"]
  node_homeworklist["Homework list<br/>[HomeworkList.tsx]"]
  node_homeworkstats["Homework statistics<br/>[HomeworkState.tsx]"]
end

subgraph group_career["Job portal"]
  node_jobpages["Job-portal pages"]
  node_recruiterapps["Recruiter applications<br/>[applications.tsx]"]
  node_studentapps["Student applications<br/>[applications.tsx]"]
  node_applications["Application table"]
  node_timeline["Application timeline"]
end

subgraph group_query["MathHub queries"]
  node_mathhubpage["MathHub query page<br/>[mathhub-query.tsx]"]
  node_templates["Query templates"]
  node_templatepicker["Template selector"]
  node_results["Query results<br/>[ResultsDisplay.tsx]"]
end

subgraph group_services["Platform services"]
  node_homeworkapi["Homework APIs"]
  node_comments[("Comment store")]
  node_commentapi["Comment APIs<br/>[comment-utils.ts]"]
  node_safequery["Safe query route"]
end

node_learner(("Learner or instructor"))
node_flams["FLAMS backend"]

node_learner -->|"uses"| node_frontend
node_frontend -.->|"renders through"| node_mainlayout
node_mainlayout -->|"renders"| node_header
node_learner -.->|"opens courses"| node_coursepages
node_homeworkmanager -->|"renders"| node_homeworkform
node_homeworkmanager -->|"renders"| node_homeworkstats
node_homeworkmanager -->|"loads list"| node_homeworklist
node_homeworkmanager -.->|"requests data"| node_homeworkapi
node_comments -.->|"loads comments"| node_commentapi
node_jobpages -.->|"routes to"| node_recruiterapps
node_jobpages -.->|"routes to"| node_studentapps
node_recruiterapps -->|"renders"| node_applications
node_studentapps -->|"renders"| node_timeline
node_mathhubpage -->|"renders"| node_templatepicker
node_templatepicker -->|"reads"| node_templates
node_mathhubpage -.->|"renders results"| node_results
node_mathhubpage -.->|"submits query"| node_safequery
node_safequery -->|"posts query"| node_flams

click node_frontend "https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages"
click node_mainlayout "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/layouts/MainLayout.tsx"
click node_header "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/Header.tsx"
click node_coursepages "https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/%5BinstitutionId%5D/%5BcourseId%5D/%5Binstance%5D"
click node_homeworkmanager "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkManager.tsx"
click node_homeworkform "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkForm.tsx"
click node_homeworklist "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkList.tsx"
click node_homeworkstats "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkState.tsx"
click node_homeworkapi "https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/api/homework"
click node_comments "https://github.com/kwarc/alea/blob/main/packages/comments/src/lib/comment-store-manager.ts"
click node_commentapi "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/api/comment-utils.ts"
click node_jobpages "https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/job-portal"
click node_recruiterapps "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/job-portal/recruiter/applications.tsx"
click node_studentapps "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/job-portal/student/applications.tsx"
click node_applications "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/job-portal/ApplicationsTable.tsx"
click node_timeline "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/job-portal/ApplicationTimelineModal.tsx"
click node_mathhubpage "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/exp/mathhub-query.tsx"
click node_templates "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/query-templates.config.ts"
click node_templatepicker "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/QueryTemplateSelector.tsx"
click node_results "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/ResultsDisplay.tsx"
click node_safequery "https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/api/safe-flams-query.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_frontend,node_mainlayout,node_header toneBlue
class node_coursepages,node_homeworkmanager,node_homeworkform,node_homeworklist,node_homeworkstats toneAmber
class node_jobpages,node_recruiterapps,node_studentapps,node_applications,node_timeline toneMint
class node_mathhubpage,node_templates,node_templatepicker,node_results toneRose
class node_homeworkapi,node_comments,node_commentapi,node_safequery,node_learner,node_flams toneIndigo
```

## Components

### Web experience

- [Next.js frontend](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages): `packages/alea-frontend/pages`
- [Main layout](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/layouts/MainLayout.tsx): `packages/alea-frontend/layouts/MainLayout.tsx`
- [Site header](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/Header.tsx): `packages/alea-frontend/components/Header.tsx`

### Course learning

- [Course pages](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/%5BinstitutionId%5D/%5BcourseId%5D/%5Binstance%5D): `packages/alea-frontend/pages/[institutionId]/[courseId]/[instance]`
- [Homework management](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkManager.tsx): `packages/alea-frontend/components/HomeworkManager.tsx`
- [Homework form](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkForm.tsx): `packages/alea-frontend/components/HomeworkForm.tsx`
- [Homework list](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkList.tsx): `packages/alea-frontend/components/HomeworkList.tsx`
- [Homework statistics](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/HomeworkState.tsx): `packages/alea-frontend/components/HomeworkState.tsx`

### Job portal

- [Job-portal pages](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/job-portal): `packages/alea-frontend/pages/job-portal`
- [Recruiter applications](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/job-portal/recruiter/applications.tsx): `packages/alea-frontend/pages/job-portal/recruiter/applications.tsx`
- [Student applications](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/job-portal/student/applications.tsx): `packages/alea-frontend/pages/job-portal/student/applications.tsx`
- [Application table](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/job-portal/ApplicationsTable.tsx): `packages/alea-frontend/components/job-portal/ApplicationsTable.tsx`
- [Application timeline](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/job-portal/ApplicationTimelineModal.tsx): `packages/alea-frontend/components/job-portal/ApplicationTimelineModal.tsx`

### MathHub queries

- [MathHub query page](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/exp/mathhub-query.tsx): `packages/alea-frontend/pages/exp/mathhub-query.tsx`
- [Query templates](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/query-templates.config.ts): `packages/alea-frontend/components/mathhub-query/query-templates.config.ts`
- [Template selector](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/QueryTemplateSelector.tsx): `packages/alea-frontend/components/mathhub-query/QueryTemplateSelector.tsx`
- [Query results](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/components/mathhub-query/ResultsDisplay.tsx): `packages/alea-frontend/components/mathhub-query/ResultsDisplay.tsx`

### Platform services

- [Homework APIs](https://github.com/kwarc/alea/tree/main/packages/alea-frontend/pages/api/homework): `packages/alea-frontend/pages/api/homework`
- [Comment store](https://github.com/kwarc/alea/blob/main/packages/comments/src/lib/comment-store-manager.ts): `packages/comments/src/lib/comment-store-manager.ts`
- [Comment APIs](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/api/comment-utils.ts): `packages/alea-frontend/pages/api/comment-utils.ts`
- [Safe query route](https://github.com/kwarc/alea/blob/main/packages/alea-frontend/pages/api/safe-flams-query.ts): `packages/alea-frontend/pages/api/safe-flams-query.ts`

### Other components

- **Learner or instructor**
- **FLAMS backend**

## Connections

- Learner or instructor → Next.js frontend: uses (evidence: `README.md`)
- Next.js frontend → Main layout: renders through (evidence: `packages/alea-frontend/pages/exp/mathhub-query.tsx`)
- Main layout → Site header: renders (evidence: `packages/alea-frontend/layouts/MainLayout.tsx`)
- Learner or instructor → Course pages: opens courses
- Homework management → Homework form: renders (evidence: `packages/alea-frontend/components/HomeworkManager.tsx`)
- Homework management → Homework statistics: renders (evidence: `packages/alea-frontend/components/HomeworkManager.tsx`)
- Homework management → Homework list: loads list (evidence: `packages/alea-frontend/components/HomeworkManager.tsx`)
- Homework management → Homework APIs: requests data
- Comment store → Comment APIs: loads comments
- Job-portal pages → Recruiter applications: routes to
- Job-portal pages → Student applications: routes to
- Recruiter applications → Application table: renders (evidence: `packages/alea-frontend/pages/job-portal/recruiter/applications.tsx`)
- Student applications → Application timeline: renders (evidence: `packages/alea-frontend/pages/job-portal/student/applications.tsx`)
- MathHub query page → Template selector: renders (evidence: `packages/alea-frontend/pages/exp/mathhub-query.tsx`)
- Template selector → Query templates: reads (evidence: `packages/alea-frontend/components/mathhub-query/QueryTemplateSelector.tsx`)
- MathHub query page → Query results: renders results (evidence: `packages/alea-frontend/pages/exp/mathhub-query.tsx`)
- MathHub query page → Safe query route: submits query
- Safe query route → FLAMS backend: posts query (evidence: `packages/alea-frontend/pages/api/safe-flams-query.ts`)
