# harshsharma07k/proctor architecture

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

- Interactive diagram: https://gitdiagram.com/harshsharma07k/proctor
- Repository: https://github.com/harshsharma07k/proctor

## Overview

Proctor is a student-and-teacher portal for sandboxed code grading and teacher-vetted doubt answers. Students browse problems, submit code, then retrieve asynchronous grading results and AI feedback; they can also post doubts, whose AI-generated drafts remain hidden from other students until a teacher approves them. Teachers review, edit, approve, or reject drafts. The README documents the major boundaries and capabilities; the sampled source confirms API routing and key review, submission, and doubt dispatch, but does not show every service implementation.

Main entry points: [`apps/api/src/db/prisma.ts`](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/db/prisma.ts) (PostgreSQL), [`apps/web/app/layout.tsx`](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/layout.tsx) (Student and teacher UI), [`apps/api/src/app.ts`](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/app.ts) (HTTP API), [`apps/api/src/queue/worker.ts`](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/queue/worker.ts) (Grading worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portal"]
  node_webapp["Student and teacher UI<br/>[layout.tsx]"]
  node_problem_pages["Problem pages<br/>[page.tsx]"]
  node_submission_pages["Submission history<br/>[page.tsx]"]
  node_doubt_pages["Doubt board<br/>[page.tsx]"]
  node_review_pages["Teacher review UI<br/>[page.tsx]"]
end

subgraph group_api["API and identity"]
  node_api_app["HTTP API<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_problems["Problem catalog"]
end

subgraph group_grading["Code grading"]
  node_submissions["Submission handling"]
  node_worker["Grading worker<br/>[worker.ts]"]
  node_sandbox["Code executor"]
  node_grading_ai["AI grading feedback<br/>[grading.service.ts]"]
end

subgraph group_doubts["Doubt answers"]
  node_doubts["Doubt handling"]
  node_answer_generation["Draft generation<br/>[answers.service.ts]"]
  node_review["Teacher review<br/>[review.service.ts]"]
  node_ai_graphs["AI workflows and guards<br/>[answer.graph.ts]"]
end

subgraph group_infra["State and integrations"]
  node_postgres[("PostgreSQL<br/>[prisma.ts]")]
  node_job_queue[("Grading jobs<br/>[job.repository.ts]")]
  node_memory[("AI memory store<br/>[index.ts]")]
end

node_student(("Student"))
node_teacher(("Teacher"))
node_executor_runtime["Sandbox runtime"]
node_llm["LLM provider"]

node_student -->|"uses"| node_webapp
node_teacher -->|"uses"| node_webapp
node_webapp -->|"REST requests"| node_api_app
node_api_app -->|"routes auth"| node_auth
node_api_app -->|"routes problems"| node_problems
node_api_app -->|"routes submissions"| node_submissions
node_api_app -->|"routes doubts"| node_doubts
node_api_app -->|"routes review"| node_review
node_auth -->|"reads and writes"| node_postgres
node_problems -->|"reads catalog"| node_postgres
node_submissions -->|"records submissions"| node_postgres
node_submissions -->|"enqueues grading"| node_job_queue
node_worker -->|"claims jobs"| node_job_queue
node_worker -->|"runs test cases"| node_sandbox
node_sandbox -->|"executes code"| node_executor_runtime
node_worker -->|"saves results"| node_postgres
node_grading_ai -.->|"requests feedback"| node_llm
node_grading_ai -->|"stores feedback"| node_postgres
node_doubts -->|"creates doubt"| node_postgres
node_doubts -->|"dispatches draft"| node_answer_generation
node_answer_generation -->|"runs workflow"| node_ai_graphs
node_ai_graphs -.->|"requests draft"| node_llm
node_ai_graphs -.->|"queries context"| node_memory
node_answer_generation -->|"stores draft"| node_postgres
node_review -->|"loads queue and transitions"| node_postgres
node_review -.->|"remembers approved answer"| node_memory
node_problem_pages -->|"renders within"| node_webapp
node_submission_pages -->|"renders within"| node_webapp
node_doubt_pages -->|"renders within"| node_webapp
node_review_pages -->|"renders within"| node_webapp

click node_webapp "https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/layout.tsx"
click node_problem_pages "https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/problems/page.tsx"
click node_submission_pages "https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/submissions/page.tsx"
click node_doubt_pages "https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/doubts/page.tsx"
click node_review_pages "https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/teacher/review/page.tsx"
click node_api_app "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_problems "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/problems/problems.controller.ts"
click node_submissions "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/submissions/submissions.controller.ts"
click node_worker "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/queue/worker.ts"
click node_sandbox "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/sandbox/executor.factory.ts"
click node_grading_ai "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/submissions/grading.service.ts"
click node_doubts "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/doubts/doubts.controller.ts"
click node_answer_generation "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/answers/answers.service.ts"
click node_review "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/review/review.service.ts"
click node_ai_graphs "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/ai/graphs/answer.graph.ts"
click node_postgres "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/db/prisma.ts"
click node_job_queue "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/queue/job.repository.ts"
click node_memory "https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/ai/memory/index.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_webapp,node_problem_pages,node_submission_pages,node_doubt_pages,node_review_pages toneBlue
class node_api_app,node_auth,node_problems toneAmber
class node_submissions,node_worker,node_sandbox,node_grading_ai toneMint
class node_doubts,node_answer_generation,node_review,node_ai_graphs toneRose
class node_postgres,node_job_queue,node_memory,node_student,node_teacher,node_executor_runtime,node_llm toneIndigo
```

## Components

### Web portal

- [Student and teacher UI](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/layout.tsx): `apps/web/app/layout.tsx`
- [Problem pages](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/problems/page.tsx): `apps/web/app/problems/page.tsx`
- [Submission history](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/submissions/page.tsx): `apps/web/app/submissions/page.tsx`
- [Doubt board](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/doubts/page.tsx): `apps/web/app/doubts/page.tsx`
- [Teacher review UI](https://github.com/harshsharma07k/proctor/blob/main/apps/web/app/teacher/review/page.tsx): `apps/web/app/teacher/review/page.tsx`

### API and identity

- [HTTP API](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Problem catalog](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/problems/problems.controller.ts): `apps/api/src/modules/problems/problems.controller.ts`

### Code grading

- [Submission handling](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/submissions/submissions.controller.ts): `apps/api/src/modules/submissions/submissions.controller.ts`
- [Grading worker](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/queue/worker.ts): `apps/api/src/queue/worker.ts`
- [Code executor](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/sandbox/executor.factory.ts): `apps/api/src/sandbox/executor.factory.ts`
- [AI grading feedback](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/submissions/grading.service.ts): `apps/api/src/modules/submissions/grading.service.ts`

### Doubt answers

- [Doubt handling](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/doubts/doubts.controller.ts): `apps/api/src/modules/doubts/doubts.controller.ts`
- [Draft generation](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/answers/answers.service.ts): `apps/api/src/modules/answers/answers.service.ts`
- [Teacher review](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/review/review.service.ts): `apps/api/src/modules/review/review.service.ts`
- [AI workflows and guards](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/ai/graphs/answer.graph.ts): `apps/api/src/modules/ai/graphs/answer.graph.ts`

### State and integrations

- [PostgreSQL](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/db/prisma.ts): `apps/api/src/db/prisma.ts`
- [Grading jobs](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/queue/job.repository.ts): `apps/api/src/queue/job.repository.ts`
- [AI memory store](https://github.com/harshsharma07k/proctor/blob/main/apps/api/src/modules/ai/memory/index.ts): `apps/api/src/modules/ai/memory/index.ts`

### Other components

- **Student**
- **Teacher**
- **Sandbox runtime**
- **LLM provider**

## Connections

- Student → Student and teacher UI: uses
- Teacher → Student and teacher UI: uses
- Student and teacher UI → HTTP API: REST requests
- HTTP API → Authentication: routes auth
- HTTP API → Problem catalog: routes problems
- HTTP API → Submission handling: routes submissions
- HTTP API → Doubt handling: routes doubts
- HTTP API → Teacher review: routes review
- Authentication → PostgreSQL: reads and writes
- Problem catalog → PostgreSQL: reads catalog
- Submission handling → PostgreSQL: records submissions
- Submission handling → Grading jobs: enqueues grading
- Grading worker → Grading jobs: claims jobs
- Grading worker → Code executor: runs test cases
- Code executor → Sandbox runtime: executes code
- Grading worker → PostgreSQL: saves results
- AI grading feedback → LLM provider: requests feedback
- AI grading feedback → PostgreSQL: stores feedback
- Doubt handling → PostgreSQL: creates doubt
- Doubt handling → Draft generation: dispatches draft
- Draft generation → AI workflows and guards: runs workflow
- AI workflows and guards → LLM provider: requests draft
- AI workflows and guards → AI memory store: queries context
- Draft generation → PostgreSQL: stores draft
- Teacher review → PostgreSQL: loads queue and transitions
- Teacher review → AI memory store: remembers approved answer
- Problem pages → Student and teacher UI: renders within
- Submission history → Student and teacher UI: renders within
- Doubt board → Student and teacher UI: renders within
- Teacher review UI → Student and teacher UI: renders within