# varunbv-gif/subjective-eval-3 architecture

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

- Interactive diagram: https://gitdiagram.com/varunbv-gif/subjective-eval-3
- Repository: https://github.com/varunbv-gif/subjective-eval-3

## Overview

This is a handwritten-answer-sheet grading product: students submit pages for a known paper, and a staged worker builds or retrieves a rubric, grades answers, locates annotations, validates the result, and stores a versioned outcome. The React client includes student-facing homework and voice-companion experiences, plus a marked-sheet review interface; operations can review and publish corrected results. The graph reflects documented stage order and relationships visible in excerpts, the source index, or README. Several route and UI capabilities are represented at subsystem level because their implementations were not sampled.

Main entry points: [`worker/stages.py`](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/stages.py) (Stage orchestration), [`api/routes`](https://github.com/varunbv-gif/subjective-eval-3/tree/main/api/routes) (Product routes), [`web/src/App.tsx`](https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/App.tsx) (Client shell), [`api/container.py`](https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/container.py) (Service composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student client"]
  node_webapp["Client shell<br/>[App.tsx]"]
  node_homework["Homework experience<br/>[Dashboard.tsx]"]
  node_companion["Voice companion<br/>[Companion.tsx]"]
  node_sheetviewer["Marked-sheet viewer<br/>[ReviewSheet.tsx]"]
end

subgraph group_api["API and accounts"]
  node_apiapp["HTTP application<br/>[app.py]"]
  node_routes["Product routes"]
  node_auth["Account and sessions<br/>[auth.py]"]
  node_container["Service composition<br/>[container.py]"]
end

subgraph group_pipeline["Grading pipeline"]
  node_jobqueue["Job queue<br/>[queue.py]"]
  node_workerloop["Worker poller<br/>[loop.py]"]
  node_stages["Stage orchestration<br/>[stages.py]"]
  node_modelcalls["Model grading calls<br/>[calls.py]"]
  node_annotation["Answer localization<br/>[annotator.py]"]
end

subgraph group_domain["Grading domain"]
  node_rubric["Rubric normalization<br/>[rubric.py]"]
  node_grading["Grade normalization<br/>[grading.py]"]
  node_validation["Result validation<br/>[validate.py]"]
  node_summary["Student summary<br/>[summary.py]"]
end

subgraph group_adapters["Infrastructure adapters"]
  node_imaging["Page preparation<br/>[pages.py]"]
  node_database[("Versioned records<br/>[models.py]")]
  node_repositories["Database queries<br/>[repositories.py]"]
  node_media["Media storage<br/>[gcs.py]"]
  node_llm["LLM adapter<br/>[client.py]"]
end

node_student(("Student"))
node_reviewer(("Operations reviewer"))

node_student -->|"starts homework"| node_webapp
node_webapp -->|"shows dashboard"| node_homework
node_webapp -->|"opens companion"| node_companion
node_webapp -->|"shows demo"| node_sheetviewer
node_student -->|"submits pages"| node_routes
node_routes -->|"enqueues grading"| node_jobqueue
node_workerloop -.->|"claims jobs"| node_jobqueue
node_workerloop -->|"runs stages"| node_stages
node_stages -->|"prepares pages"| node_imaging
node_stages -->|"requests grading"| node_modelcalls
node_modelcalls -->|"calls model"| node_llm
node_stages -->|"builds rubric"| node_rubric
node_modelcalls -->|"normalizes grade"| node_grading
node_stages -->|"localizes answers"| node_annotation
node_stages -->|"validates result"| node_validation
node_stages -->|"builds summary"| node_summary
node_stages -->|"persists stages"| node_repositories
node_repositories -->|"queries records"| node_database
node_stages -->|"reads page media"| node_media
node_routes -->|"reads and writes"| node_repositories
node_routes -->|"reapplies choices"| node_grading
node_routes -->|"rebuilds summary"| node_summary
node_reviewer -->|"publishes verdict"| node_routes
node_apiapp -->|"mounts routes"| node_routes
node_apiapp -->|"builds services"| node_container
node_auth -->|"uses sessions"| node_container
node_container -->|"configures adapter"| node_llm
node_container -->|"configures store"| node_media

click node_webapp "https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/App.tsx"
click node_homework "https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/dashboard/Dashboard.tsx"
click node_companion "https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/companion/Companion.tsx"
click node_sheetviewer "https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/review/ReviewSheet.tsx"
click node_apiapp "https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/app.py"
click node_routes "https://github.com/varunbv-gif/subjective-eval-3/tree/main/api/routes"
click node_auth "https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/routes/auth.py"
click node_container "https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/container.py"
click node_jobqueue "https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/queue.py"
click node_workerloop "https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/loop.py"
click node_stages "https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/stages.py"
click node_imaging "https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/imaging/pages.py"
click node_modelcalls "https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/calls.py"
click node_annotation "https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/annotator.py"
click node_rubric "https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/rubric.py"
click node_grading "https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/grading.py"
click node_validation "https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/validate.py"
click node_summary "https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/summary.py"
click node_database "https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/db/models.py"
click node_repositories "https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/db/repositories.py"
click node_media "https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/storage/gcs.py"
click node_llm "https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/llm/client.py"

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_homework,node_companion,node_sheetviewer,node_reviewer toneBlue
class node_apiapp,node_routes,node_auth,node_container toneAmber
class node_jobqueue,node_workerloop,node_stages,node_modelcalls,node_annotation toneMint
class node_rubric,node_grading,node_validation,node_summary toneRose
class node_imaging,node_database,node_repositories,node_media,node_llm,node_student toneIndigo
```

## Components

### Student client

- [Client shell](https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Homework experience](https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/dashboard/Dashboard.tsx): `web/src/dashboard/Dashboard.tsx`
- [Voice companion](https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/companion/Companion.tsx): `web/src/companion/Companion.tsx`
- [Marked-sheet viewer](https://github.com/varunbv-gif/subjective-eval-3/blob/main/web/src/review/ReviewSheet.tsx): `web/src/review/ReviewSheet.tsx`

### API and accounts

- [HTTP application](https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/app.py): `api/app.py`
- [Product routes](https://github.com/varunbv-gif/subjective-eval-3/tree/main/api/routes): `api/routes`
- [Account and sessions](https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/routes/auth.py): `api/routes/auth.py`
- [Service composition](https://github.com/varunbv-gif/subjective-eval-3/blob/main/api/container.py): `api/container.py`

### Grading pipeline

- [Job queue](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/queue.py): `worker/queue.py`
- [Worker poller](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/loop.py): `worker/loop.py`
- [Stage orchestration](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/stages.py): `worker/stages.py`
- [Model grading calls](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/calls.py): `worker/calls.py`
- [Answer localization](https://github.com/varunbv-gif/subjective-eval-3/blob/main/worker/annotator.py): `worker/annotator.py`

### Grading domain

- [Rubric normalization](https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/rubric.py): `core/rubric.py`
- [Grade normalization](https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/grading.py): `core/grading.py`
- [Result validation](https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/validate.py): `core/validate.py`
- [Student summary](https://github.com/varunbv-gif/subjective-eval-3/blob/main/core/summary.py): `core/summary.py`

### Infrastructure adapters

- [Page preparation](https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/imaging/pages.py): `adapters/imaging/pages.py`
- [Versioned records](https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/db/models.py): `adapters/db/models.py`
- [Database queries](https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/db/repositories.py): `adapters/db/repositories.py`
- [Media storage](https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/storage/gcs.py): `adapters/storage/gcs.py`
- [LLM adapter](https://github.com/varunbv-gif/subjective-eval-3/blob/main/adapters/llm/client.py): `adapters/llm/client.py`

### Other components

- **Student**
- **Operations reviewer**

## Connections

- Student → Client shell: starts homework (evidence: `web/src/App.tsx`)
- Client shell → Homework experience: shows dashboard (evidence: `web/src/App.tsx`)
- Client shell → Voice companion: opens companion (evidence: `web/src/App.tsx`)
- Client shell → Marked-sheet viewer: shows demo (evidence: `web/src/App.tsx`)
- Student → Product routes: submits pages (evidence: `README.md`)
- Product routes → Job queue: enqueues grading (evidence: `api/routes/admin.py`)
- Worker poller → Job queue: claims jobs
- Worker poller → Stage orchestration: runs stages
- Stage orchestration → Page preparation: prepares pages (evidence: `worker/stages.py`)
- Stage orchestration → Model grading calls: requests grading (evidence: `worker/stages.py`)
- Model grading calls → LLM adapter: calls model (evidence: `worker/calls.py`)
- Stage orchestration → Rubric normalization: builds rubric (evidence: `worker/stages.py`)
- Model grading calls → Grade normalization: normalizes grade (evidence: `worker/calls.py`)
- Stage orchestration → Answer localization: localizes answers (evidence: `worker/stages.py`)
- Stage orchestration → Result validation: validates result (evidence: `worker/stages.py`)
- Stage orchestration → Student summary: builds summary (evidence: `worker/stages.py`)
- Stage orchestration → Database queries: persists stages (evidence: `worker/stages.py`)
- Database queries → Versioned records: queries records (evidence: `adapters/db/repositories.py`)
- Stage orchestration → Media storage: reads page media (evidence: `worker/stages.py`)
- Product routes → Database queries: reads and writes (evidence: `api/routes/review.py`)
- Product routes → Grade normalization: reapplies choices (evidence: `api/routes/review.py`)
- Product routes → Student summary: rebuilds summary (evidence: `api/routes/review.py`)
- Operations reviewer → Product routes: publishes verdict (evidence: `api/routes/review.py`)
- HTTP application → Product routes: mounts routes (evidence: `api/app.py`)
- HTTP application → Service composition: builds services (evidence: `api/app.py`)
- Account and sessions → Service composition: uses sessions (evidence: `api/routes/auth.py`)
- Service composition → LLM adapter: configures adapter (evidence: `api/container.py`)
- Service composition → Media storage: configures store (evidence: `api/container.py`)