# figurerevitalization/neet-practice-platform architecture

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

- Interactive diagram: https://gitdiagram.com/figurerevitalization/neet-practice-platform
- Repository: https://github.com/figurerevitalization/neet-practice-platform

## Overview

NEET Practice Platform is a mock-test and question-bank product, currently described as a Phase 1 skeleton. The main user journey is to sign in or continue anonymously, use the web exam interface, and submit an attempt; the API provides attempt and content endpoints backed by MongoDB. Admins manage question content and review live sessions. A separate OpenAI-backed generator creates draft questions. The README documents blueprint-accurate paper assembly as a goal, not a built capability. The tree and sampled source support the live-monitoring and snapshot features, but not every route’s internal wiring.

Main entry points: [`apps/api/src/index.ts`](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/index.ts) (Express API), [`packages/db/src/models`](https://github.com/figurerevitalization/neet-practice-platform/tree/master/packages/db/src/models) (MongoDB models), [`apps/web/src/app`](https://github.com/figurerevitalization/neet-practice-platform/tree/master/apps/web/src/app) (Practice web app), [`apps/api/src/routes/liveSessions.ts`](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/liveSessions.ts) (Live session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Practice web app"]
  node_examui["Mock test runner<br/>[MockTestRunner.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_attemptclient["Attempt client<br/>[attempts.ts]"]
  node_authui["Web authentication<br/>[auth.ts]"]
end

subgraph group_api["API services"]
  node_apiapp["Express API<br/>[index.ts]"]
  node_authroutes["Auth endpoints<br/>[auth.ts]"]
  node_itemroutes["Item endpoints<br/>[items.ts]"]
  node_contentroutes["Content endpoints<br/>[chapters.ts]"]
  node_blueprints["Blueprint endpoints<br/>[blueprints.ts]"]
  node_attempts["Attempt endpoints<br/>[attempts.ts]"]
  node_snapshots["Snapshot endpoints<br/>[snapshots.ts]"]
  node_livesessions["Live session endpoints<br/>[liveSessions.ts]"]
  node_authmw["Token and role checks<br/>[auth.ts]"]
end

subgraph group_data["Content and persistence"]
  node_dbmodels["MongoDB models"]
  node_itemmodel["Question item model<br/>[Item.ts]"]
  node_attemptmodel["Attempt model<br/>[Attempt.ts]"]
  node_live_model["Live session model<br/>[LiveSession.ts]"]
end

subgraph group_generation["Question generation"]
  node_gencli["Question generation<br/>[generate.ts]"]
  node_genclient["OpenAI client<br/>[openaiClient.ts]"]
  node_genschema["Generation schema<br/>[schema.ts]"]
end

subgraph group_monitoring["Exam monitoring"]
  node_camera["Camera capture"]
  node_broadcast["Live video broadcaster"]
  node_viewer["Live video viewer"]
  node_signaling["WebRTC signaling relay<br/>[signaling.ts]"]
  node_adminlive["Admin proctoring<br/>[page.tsx]"]
end

node_student(("Student"))
node_admin(("Admin"))
node_mongo[("MongoDB")]
node_openai["OpenAI"]

node_student -->|"uses"| node_webapp
node_admin -->|"uses"| node_webapp
node_webapp -->|"runs exams"| node_examui
node_webapp -->|"authenticates"| node_authui
node_examui -->|"submits attempts"| node_attemptclient
node_attemptclient -->|"requests API"| node_webapi
node_webapi -->|"sends requests"| node_apiapp
node_apiapp -->|"dispatches"| node_authroutes
node_apiapp -->|"dispatches"| node_itemroutes
node_apiapp -->|"dispatches"| node_contentroutes
node_apiapp -->|"dispatches"| node_blueprints
node_apiapp -->|"dispatches"| node_attempts
node_apiapp -->|"dispatches"| node_snapshots
node_apiapp -->|"dispatches"| node_livesessions
node_authroutes -->|"signs tokens"| node_authmw
node_authroutes -->|"reads and writes"| node_dbmodels
node_itemroutes -->|"reads and writes"| node_itemmodel
node_contentroutes -->|"reads and writes"| node_dbmodels
node_blueprints -->|"reads and writes"| node_dbmodels
node_attempts -->|"reads and writes"| node_attemptmodel
node_snapshots -->|"stores snapshots"| node_dbmodels
node_livesessions -->|"reads and writes"| node_live_model
node_dbmodels -->|"persists"| node_mongo
node_gencli -->|"generates items"| node_genclient
node_genclient -->|"validates response"| node_genschema
node_genclient -.->|"requests completion"| node_openai
node_gencli -->|"inserts drafts"| node_itemmodel
node_examui -->|"captures evidence"| node_camera
node_camera -->|"uploads snapshots"| node_snapshots
node_camera -->|"provides camera stream"| node_broadcast
node_broadcast -->|"exchanges signaling"| node_signaling
node_viewer -->|"exchanges signaling"| node_signaling
node_adminlive -->|"fetches active sessions"| node_livesessions
node_adminlive -->|"watches candidate"| node_viewer
node_livesessions -->|"updates session state"| node_live_model

click node_webapp "https://github.com/figurerevitalization/neet-practice-platform/tree/master/apps/web/src/app"
click node_examui "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/components/MockTestRunner.tsx"
click node_webapi "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/api.ts"
click node_attemptclient "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/attempts.ts"
click node_authui "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/auth.ts"
click node_apiapp "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/index.ts"
click node_authroutes "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/auth.ts"
click node_itemroutes "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/items.ts"
click node_contentroutes "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/chapters.ts"
click node_blueprints "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/blueprints.ts"
click node_attempts "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/attempts.ts"
click node_snapshots "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/snapshots.ts"
click node_livesessions "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/liveSessions.ts"
click node_authmw "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/middleware/auth.ts"
click node_dbmodels "https://github.com/figurerevitalization/neet-practice-platform/tree/master/packages/db/src/models"
click node_itemmodel "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/Item.ts"
click node_attemptmodel "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/Attempt.ts"
click node_live_model "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/LiveSession.ts"
click node_gencli "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/generate.ts"
click node_genclient "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/openaiClient.ts"
click node_genschema "https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/schema.ts"
click node_camera "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useCameraSnapshots.ts"
click node_broadcast "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useLiveVideoBroadcast.ts"
click node_viewer "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useLiveVideoViewer.ts"
click node_signaling "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/signaling.ts"
click node_adminlive "https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/app/admin/proctoring/page.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_webapp,node_examui,node_webapi,node_attemptclient,node_authui toneBlue
class node_apiapp,node_authroutes,node_itemroutes,node_contentroutes,node_blueprints,node_attempts,node_snapshots,node_livesessions,node_authmw,node_mongo toneAmber
class node_dbmodels,node_itemmodel,node_attemptmodel,node_live_model toneMint
class node_gencli,node_genclient,node_genschema toneRose
class node_camera,node_broadcast,node_viewer,node_signaling,node_adminlive,node_student,node_admin,node_openai toneIndigo
```

## Components

### Web experience

- [Practice web app](https://github.com/figurerevitalization/neet-practice-platform/tree/master/apps/web/src/app): `apps/web/src/app`
- [Mock test runner](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/components/MockTestRunner.tsx): `apps/web/src/components/MockTestRunner.tsx`
- [API client](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Attempt client](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/attempts.ts): `apps/web/src/lib/attempts.ts`
- [Web authentication](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/auth.ts): `apps/web/src/lib/auth.ts`

### API services

- [Express API](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Auth endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Item endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/items.ts): `apps/api/src/routes/items.ts`
- [Content endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/chapters.ts): `apps/api/src/routes/chapters.ts`
- [Blueprint endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/blueprints.ts): `apps/api/src/routes/blueprints.ts`
- [Attempt endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/attempts.ts): `apps/api/src/routes/attempts.ts`
- [Snapshot endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/snapshots.ts): `apps/api/src/routes/snapshots.ts`
- [Live session endpoints](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/routes/liveSessions.ts): `apps/api/src/routes/liveSessions.ts`
- [Token and role checks](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`

### Content and persistence

- [MongoDB models](https://github.com/figurerevitalization/neet-practice-platform/tree/master/packages/db/src/models): `packages/db/src/models`
- [Question item model](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/Item.ts): `packages/db/src/models/Item.ts`
- [Attempt model](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/Attempt.ts): `packages/db/src/models/Attempt.ts`
- [Live session model](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/db/src/models/LiveSession.ts): `packages/db/src/models/LiveSession.ts`

### Question generation

- [Question generation](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/generate.ts): `packages/question-gen/src/generate.ts`
- [OpenAI client](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/openaiClient.ts): `packages/question-gen/src/openaiClient.ts`
- [Generation schema](https://github.com/figurerevitalization/neet-practice-platform/blob/master/packages/question-gen/src/schema.ts): `packages/question-gen/src/schema.ts`

### Exam monitoring

- [Camera capture](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useCameraSnapshots.ts): `apps/web/src/lib/useCameraSnapshots.ts`
- [Live video broadcaster](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useLiveVideoBroadcast.ts): `apps/web/src/lib/useLiveVideoBroadcast.ts`
- [Live video viewer](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/lib/useLiveVideoViewer.ts): `apps/web/src/lib/useLiveVideoViewer.ts`
- [WebRTC signaling relay](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/api/src/signaling.ts): `apps/api/src/signaling.ts`
- [Admin proctoring](https://github.com/figurerevitalization/neet-practice-platform/blob/master/apps/web/src/app/admin/proctoring/page.tsx): `apps/web/src/app/admin/proctoring/page.tsx`

### Other components

- **Student**
- **Admin**
- **MongoDB**
- **OpenAI**

## Connections

- Student → Practice web app: uses
- Admin → Practice web app: uses
- Practice web app → Mock test runner: runs exams
- Practice web app → Web authentication: authenticates
- Mock test runner → Attempt client: submits attempts
- Attempt client → API client: requests API
- API client → Express API: sends requests
- Express API → Auth endpoints: dispatches
- Express API → Item endpoints: dispatches
- Express API → Content endpoints: dispatches
- Express API → Blueprint endpoints: dispatches
- Express API → Attempt endpoints: dispatches
- Express API → Snapshot endpoints: dispatches
- Express API → Live session endpoints: dispatches
- Auth endpoints → Token and role checks: signs tokens
- Auth endpoints → MongoDB models: reads and writes
- Item endpoints → Question item model: reads and writes
- Content endpoints → MongoDB models: reads and writes
- Blueprint endpoints → MongoDB models: reads and writes
- Attempt endpoints → Attempt model: reads and writes
- Snapshot endpoints → MongoDB models: stores snapshots
- Live session endpoints → Live session model: reads and writes
- MongoDB models → MongoDB: persists
- Question generation → OpenAI client: generates items
- OpenAI client → Generation schema: validates response
- OpenAI client → OpenAI: requests completion
- Question generation → Question item model: inserts drafts
- Mock test runner → Camera capture: captures evidence
- Camera capture → Snapshot endpoints: uploads snapshots
- Camera capture → Live video broadcaster: provides camera stream
- Live video broadcaster → WebRTC signaling relay: exchanges signaling
- Live video viewer → WebRTC signaling relay: exchanges signaling
- Admin proctoring → Live session endpoints: fetches active sessions
- Admin proctoring → Live video viewer: watches candidate
- Live session endpoints → Live session model: updates session state