# kyeremehs/sciencelab architecture

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

- Interactive diagram: https://gitdiagram.com/kyeremehs/sciencelab
- Repository: https://github.com/kyeremehs/sciencelab

## Overview

ScienceLab is a web platform for guided practical STEM learning and classroom management. Students browse experiments, run structured attempts with steps and observations, receive contextual AI help, and submit assessments; teachers create classes, assign experiments, and monitor progress. The graph groups the app by user workflows, API entry points, domain services, and persistence/integrations. The README establishes the product capabilities; sampled route handlers confirm several API-to-service dispatches, while wiring for unsampled domains is kept broad.

Main entry points: [`src/db/index.ts`](https://github.com/kyeremehs/sciencelab/blob/main/src/db/index.ts) (Database access), [`src/app/api/experiments/route.ts`](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/experiments/route.ts) (Experiment routes), [`src/app/dashboard/student/attempts/[id]/AttemptRunner.tsx`](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/attempts/%5Bid%5D/AttemptRunner.tsx) (Experiment runner), [`src/app/api/attempts/[id]/assessment/route.ts`](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/attempts/%5Bid%5D/assessment/route.ts) (Attempt routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student learning"]
  node_student_ui["Experiment runner<br/>[AttemptRunner.tsx]"]
  node_catalog["Experiment catalogue<br/>[page.tsx]"]
  node_student_classes["Class workspace<br/>[page.tsx]"]
end

subgraph group_teacher["Teacher workspace"]
  node_teacher_classes["Class management<br/>[page.tsx]"]
  node_assign_ui["Assignment manager"]
  node_teacher_progress["Progress dashboard<br/>[ClassProgress.tsx]"]
  node_teacher_experiments["Experiment authoring"]
end

subgraph group_api["HTTP API"]
  node_auth_api["Authentication routes<br/>[route.ts]"]
  node_experiment_api["Experiment routes<br/>[route.ts]"]
  node_attempt_api["Attempt routes<br/>[route.ts]"]
  node_class_api["Class routes<br/>[route.ts]"]
  node_assignment_api["Assignment routes<br/>[route.ts]"]
end

subgraph group_domain["Domain services"]
  node_attempt_service["Attempt workflow"]
  node_assessment_service["Assessment"]
  node_ai_service["Contextual AI help<br/>[ai-service.ts]"]
  node_experiment_service["Experiment catalogue"]
  node_creation_service["Experiment creation"]
  node_class_service["Class management<br/>[classes-service.ts]"]
  node_assignment_service["Assignments"]
  node_progress_service["Progress reporting"]
  node_auth_service["Authentication<br/>[auth-service.ts]"]
end

subgraph group_infra["Persistence and integrations"]
  node_db_schema[("Relational data<br/>[schema.ts]")]
  node_db_client["Database access<br/>[index.ts]"]
  node_openrouter{{"OpenRouter AI"}}
  node_email{{"SMTP email"}}
  node_mailer["Mail delivery<br/>[mailer.ts]"]
end

node_learner(("Student"))
node_teacher(("Teacher"))

node_learner -->|"browses"| node_catalog
node_catalog -->|"requests experiments"| node_experiment_api
node_experiment_api -->|"dispatches"| node_experiment_service
node_experiment_api -->|"dispatches"| node_creation_service
node_learner -->|"runs experiment"| node_student_ui
node_student_ui -->|"records progress"| node_attempt_api
node_attempt_api -->|"dispatches"| node_attempt_service
node_attempt_api -->|"dispatches"| node_assessment_service
node_student_ui -->|"requests help"| node_ai_service
node_ai_service -.->|"queries model"| node_openrouter
node_learner -->|"joins class"| node_student_classes
node_student_classes -->|"manages membership"| node_class_api
node_teacher -->|"manages classes"| node_teacher_classes
node_teacher_classes -->|"requests class actions"| node_class_api
node_teacher -->|"assigns experiments"| node_assign_ui
node_assign_ui -->|"fetches and updates"| node_assignment_api
node_assignment_api -->|"dispatches"| node_assignment_service
node_teacher -->|"reviews progress"| node_teacher_progress
node_teacher_progress -->|"requests progress"| node_class_api
node_teacher -->|"creates experiments"| node_teacher_experiments
node_teacher_experiments -->|"submits experiment"| node_experiment_api
node_auth_api -->|"dispatches"| node_auth_service
node_auth_service -->|"sends reset mail"| node_mailer
node_mailer -.->|"delivers mail"| node_email
node_attempt_service -->|"reads and writes"| node_db_client
node_assessment_service -->|"reads and writes"| node_db_client
node_experiment_service -->|"reads data"| node_db_client
node_creation_service -->|"writes data"| node_db_client
node_class_service -->|"reads and writes"| node_db_client
node_assignment_service -->|"reads and writes"| node_db_client
node_progress_service -->|"reads progress"| node_db_client
node_auth_service -->|"reads and writes"| node_db_client
node_db_client -->|"uses schema"| node_db_schema

click node_student_ui "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/attempts/%5Bid%5D/AttemptRunner.tsx"
click node_catalog "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/experiments/page.tsx"
click node_student_classes "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/classes/page.tsx"
click node_teacher_classes "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/page.tsx"
click node_assign_ui "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/AssignmentsManager.tsx"
click node_teacher_progress "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/ClassProgress.tsx"
click node_teacher_experiments "https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/experiments/new/ExperimentCreator.tsx"
click node_auth_api "https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/auth/login/route.ts"
click node_experiment_api "https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/experiments/route.ts"
click node_attempt_api "https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/attempts/%5Bid%5D/assessment/route.ts"
click node_class_api "https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/classes/%5Bid%5D/route.ts"
click node_assignment_api "https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/classes/%5Bid%5D/assignments/route.ts"
click node_attempt_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/attempts-service.ts"
click node_assessment_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/assessment-service.ts"
click node_ai_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/ai-service.ts"
click node_experiment_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/experiments-service.ts"
click node_creation_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/experiment-creation-service.ts"
click node_class_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/classes-service.ts"
click node_assignment_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/assignments-service.ts"
click node_progress_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/progress-service.ts"
click node_auth_service "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/auth-service.ts"
click node_db_schema "https://github.com/kyeremehs/sciencelab/blob/main/src/db/schema.ts"
click node_db_client "https://github.com/kyeremehs/sciencelab/blob/main/src/db/index.ts"
click node_mailer "https://github.com/kyeremehs/sciencelab/blob/main/src/lib/mailer.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_student_ui,node_catalog,node_student_classes toneBlue
class node_teacher_classes,node_assign_ui,node_teacher_progress,node_teacher_experiments toneAmber
class node_auth_api,node_experiment_api,node_attempt_api,node_class_api,node_assignment_api toneMint
class node_attempt_service,node_assessment_service,node_ai_service,node_experiment_service,node_creation_service,node_class_service,node_assignment_service,node_progress_service,node_auth_service toneRose
class node_db_schema,node_db_client,node_openrouter,node_email,node_mailer,node_learner,node_teacher toneIndigo
```

## Components

### Student learning

- [Experiment runner](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/attempts/%5Bid%5D/AttemptRunner.tsx): `src/app/dashboard/student/attempts/[id]/AttemptRunner.tsx`
- [Experiment catalogue](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/experiments/page.tsx): `src/app/dashboard/student/experiments/page.tsx`
- [Class workspace](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/student/classes/page.tsx): `src/app/dashboard/student/classes/page.tsx`

### Teacher workspace

- [Class management](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/page.tsx): `src/app/dashboard/teacher/classes/[id]/page.tsx`
- [Assignment manager](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/AssignmentsManager.tsx): `src/app/dashboard/teacher/classes/[id]/AssignmentsManager.tsx`
- [Progress dashboard](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/classes/%5Bid%5D/ClassProgress.tsx): `src/app/dashboard/teacher/classes/[id]/ClassProgress.tsx`
- [Experiment authoring](https://github.com/kyeremehs/sciencelab/blob/main/src/app/dashboard/teacher/experiments/new/ExperimentCreator.tsx): `src/app/dashboard/teacher/experiments/new/ExperimentCreator.tsx`

### HTTP API

- [Authentication routes](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/auth/login/route.ts): `src/app/api/auth/login/route.ts`
- [Experiment routes](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/experiments/route.ts): `src/app/api/experiments/route.ts`
- [Attempt routes](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/attempts/%5Bid%5D/assessment/route.ts): `src/app/api/attempts/[id]/assessment/route.ts`
- [Class routes](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/classes/%5Bid%5D/route.ts): `src/app/api/classes/[id]/route.ts`
- [Assignment routes](https://github.com/kyeremehs/sciencelab/blob/main/src/app/api/classes/%5Bid%5D/assignments/route.ts): `src/app/api/classes/[id]/assignments/route.ts`

### Domain services

- [Attempt workflow](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/attempts-service.ts): `src/lib/attempts-service.ts`
- [Assessment](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/assessment-service.ts): `src/lib/assessment-service.ts`
- [Contextual AI help](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/ai-service.ts): `src/lib/ai-service.ts`
- [Experiment catalogue](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/experiments-service.ts): `src/lib/experiments-service.ts`
- [Experiment creation](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/experiment-creation-service.ts): `src/lib/experiment-creation-service.ts`
- [Class management](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/classes-service.ts): `src/lib/classes-service.ts`
- [Assignments](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/assignments-service.ts): `src/lib/assignments-service.ts`
- [Progress reporting](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/progress-service.ts): `src/lib/progress-service.ts`
- [Authentication](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/auth-service.ts): `src/lib/auth-service.ts`

### Persistence and integrations

- [Relational data](https://github.com/kyeremehs/sciencelab/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Database access](https://github.com/kyeremehs/sciencelab/blob/main/src/db/index.ts): `src/db/index.ts`
- **OpenRouter AI**
- **SMTP email**
- [Mail delivery](https://github.com/kyeremehs/sciencelab/blob/main/src/lib/mailer.ts): `src/lib/mailer.ts`

### Other components

- **Student**
- **Teacher**

## Connections

- Student → Experiment catalogue: browses
- Experiment catalogue → Experiment routes: requests experiments
- Experiment routes → Experiment catalogue: dispatches
- Experiment routes → Experiment creation: dispatches
- Student → Experiment runner: runs experiment
- Experiment runner → Attempt routes: records progress
- Attempt routes → Attempt workflow: dispatches
- Attempt routes → Assessment: dispatches
- Experiment runner → Contextual AI help: requests help
- Contextual AI help → OpenRouter AI: queries model
- Student → Class workspace: joins class
- Class workspace → Class routes: manages membership
- Teacher → Class management: manages classes
- Class management → Class routes: requests class actions
- Teacher → Assignment manager: assigns experiments
- Assignment manager → Assignment routes: fetches and updates
- Assignment routes → Assignments: dispatches
- Teacher → Progress dashboard: reviews progress
- Progress dashboard → Class routes: requests progress
- Teacher → Experiment authoring: creates experiments
- Experiment authoring → Experiment routes: submits experiment
- Authentication routes → Authentication: dispatches
- Authentication → Mail delivery: sends reset mail
- Mail delivery → SMTP email: delivers mail
- Attempt workflow → Database access: reads and writes
- Assessment → Database access: reads and writes
- Experiment catalogue → Database access: reads data
- Experiment creation → Database access: writes data
- Class management → Database access: reads and writes
- Assignments → Database access: reads and writes
- Progress reporting → Database access: reads progress
- Authentication → Database access: reads and writes
- Database access → Relational data: uses schema