# arnavmahajan630/certiproof-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/arnavmahajan630/certiproof-v2
- Repository: https://github.com/arnavmahajan630/certiproof-v2

## Overview

CertiProof is an exam-scoring system that binds rubric, candidate answer, model identity, score computation, and provenance into a publicly verifiable record. Teachers certify rubrics and review results; students submit answers and retrieve scorecards; auditors or scorecard holders can verify them. Evaluation is orchestrated by the Gateway: it records the submission, obtains Stage 0 embeddings, commits their witness hash to the audit chain, requests proof-bound scoring and explanations, persists results, and creates a scorecard. OCR is an optional, explicitly unverified input convenience. Wiring beyond the sampled source is included only where the README documents it.

Main entry points: [`gateway/src/routes/teacher.routes.js`](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/teacher.routes.js) (Teacher routes), [`ml-worker/app/routes.py`](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/routes.py) (Worker endpoints), [`gateway/src/services/evaluationPipeline.js`](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/evaluationPipeline.js) (Evaluation pipeline), [`gateway/src/services/verifyService.js`](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/verifyService.js) (Verification service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Role views<br/>[App.jsx]"]
  node_teacher_ui["Teacher view<br/>[Teacher.jsx]"]
  node_student_ui["Student view<br/>[Student.jsx]"]
  node_auditor_ui["Auditor view<br/>[Auditor.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_gateway["Gateway API"]
  node_gateway_app["Express app<br/>[app.js]"]
  node_teacher_routes["Teacher routes<br/>[teacher.routes.js]"]
  node_student_routes["Student routes<br/>[student.routes.js]"]
  node_auditor_routes["Auditor routes<br/>[auditor.routes.js]"]
  node_evaluation["Evaluation pipeline"]
  node_ml_client["Worker client<br/>[mlWorkerClient.js]"]
  node_scorecard["Scorecard service"]
end

subgraph group_compute["Scoring worker"]
  node_ml_routes["Worker endpoints<br/>[routes.py]"]
  node_preprocessing["Stage 0 embeddings<br/>[preprocessing.py]"]
  node_rcajx_model["RCAJ-X scoring<br/>[model.py]"]
  node_explain["Evidence explanations<br/>[explain.py]"]
  node_ocr["OCR transcription<br/>[gemini_client.py]"]
end

subgraph group_integrity["Proof and records"]
  node_db[("SQLite records<br/>[client.js]")]
  node_audit_chain["Audit chain<br/>[auditChain.js]"]
  node_verify["Verification service<br/>[verifyService.js]"]
  node_zk["EZKL proof pipeline"]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_auditor(("Auditor"))
node_browser(("Browser"))
node_gemini["Gemini API"]
node_sqlite[("SQLite store")]

node_teacher -->|"uses"| node_teacher_ui
node_student -->|"uses"| node_student_ui
node_auditor -->|"uses"| node_auditor_ui
node_browser -->|"loads"| node_app
node_app -->|"selects"| node_teacher_ui
node_app -->|"selects"| node_student_ui
node_app -->|"selects"| node_auditor_ui
node_teacher_ui -->|"requests"| node_api_client
node_student_ui -->|"requests"| node_api_client
node_auditor_ui -->|"requests"| node_api_client
node_api_client -->|"REST"| node_gateway_app
node_gateway_app -->|"dispatches"| node_teacher_routes
node_gateway_app -->|"dispatches"| node_student_routes
node_gateway_app -->|"dispatches"| node_auditor_routes
node_teacher_routes -->|"gets model identity"| node_ml_client
node_teacher_routes -->|"certifies rubric"| node_db
node_teacher_routes -->|"starts evaluation"| node_evaluation
node_teacher_routes -.->|"transcribes scan"| node_ml_client
node_student_routes -->|"starts evaluation"| node_evaluation
node_evaluation -->|"reads rubric; saves results"| node_db
node_evaluation -->|"appends submission and witness"| node_audit_chain
node_evaluation -->|"requests embedding, proof, score"| node_ml_client
node_evaluation -->|"generates scorecard"| node_scorecard
node_scorecard -->|"stores scorecard metadata"| node_db
node_teacher_routes -->|"records override"| node_audit_chain
node_auditor_routes -->|"requests verification"| node_verify
node_student_routes -->|"checks scorecard"| node_verify
node_verify -->|"loads evaluation bundle"| node_db
node_verify -->|"checks chain"| node_audit_chain
node_verify -->|"recomputes commitment; verifies proof"| node_ml_client
node_ml_client -->|"HTTP requests"| node_ml_routes
node_ml_routes -->|"embeds answer"| node_preprocessing
node_ml_routes -->|"scores inputs"| node_rcajx_model
node_ml_routes -->|"derives explanations"| node_explain
node_ml_routes -->|"proves; verifies; recomputes commitment"| node_zk
node_ml_routes -.->|"transcribes image"| node_ocr
node_ocr -.->|"sends image and prompt"| node_gemini
node_db -->|"reads and writes"| node_sqlite

click node_app "https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/App.jsx"
click node_teacher_ui "https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Teacher.jsx"
click node_student_ui "https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Student.jsx"
click node_auditor_ui "https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Auditor.jsx"
click node_api_client "https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/api/client.js"
click node_gateway_app "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/app.js"
click node_teacher_routes "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/teacher.routes.js"
click node_student_routes "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/student.routes.js"
click node_auditor_routes "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/auditor.routes.js"
click node_evaluation "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/evaluationPipeline.js"
click node_ml_client "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/mlWorkerClient.js"
click node_db "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/db/client.js"
click node_audit_chain "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/auditChain.js"
click node_scorecard "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/scorecardService.js"
click node_verify "https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/verifyService.js"
click node_ml_routes "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/routes.py"
click node_preprocessing "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/preprocessing.py"
click node_rcajx_model "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/model.py"
click node_explain "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/explain.py"
click node_zk "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/zk/rcajx_ezkl_pipeline.py"
click node_ocr "https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/ocr/gemini_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_app,node_teacher_ui,node_student_ui,node_auditor_ui,node_api_client,node_browser toneBlue
class node_gateway_app,node_teacher_routes,node_student_routes,node_auditor_routes,node_evaluation,node_ml_client,node_scorecard,node_sqlite toneAmber
class node_ml_routes,node_preprocessing,node_rcajx_model,node_explain,node_ocr,node_gemini toneMint
class node_db,node_audit_chain,node_verify,node_zk toneRose
class node_teacher,node_student,node_auditor toneIndigo
```

## Components

### User interface

- [Role views](https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Teacher view](https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Teacher.jsx): `frontend/src/views/Teacher.jsx`
- [Student view](https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Student.jsx): `frontend/src/views/Student.jsx`
- [Auditor view](https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/views/Auditor.jsx): `frontend/src/views/Auditor.jsx`
- [API client](https://github.com/arnavmahajan630/certiproof-v2/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Gateway API

- [Express app](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/app.js): `gateway/src/app.js`
- [Teacher routes](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/teacher.routes.js): `gateway/src/routes/teacher.routes.js`
- [Student routes](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/student.routes.js): `gateway/src/routes/student.routes.js`
- [Auditor routes](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/routes/auditor.routes.js): `gateway/src/routes/auditor.routes.js`
- [Evaluation pipeline](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/evaluationPipeline.js): `gateway/src/services/evaluationPipeline.js`
- [Worker client](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/mlWorkerClient.js): `gateway/src/services/mlWorkerClient.js`
- [Scorecard service](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/scorecardService.js): `gateway/src/services/scorecardService.js`

### Scoring worker

- [Worker endpoints](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/routes.py): `ml-worker/app/routes.py`
- [Stage 0 embeddings](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/preprocessing.py): `ml-worker/app/rcajx/preprocessing.py`
- [RCAJ-X scoring](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/model.py): `ml-worker/app/rcajx/model.py`
- [Evidence explanations](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/rcajx/explain.py): `ml-worker/app/rcajx/explain.py`
- [OCR transcription](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/ocr/gemini_client.py): `ml-worker/app/ocr/gemini_client.py`

### Proof and records

- [SQLite records](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/db/client.js): `gateway/src/db/client.js`
- [Audit chain](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/auditChain.js): `gateway/src/services/auditChain.js`
- [Verification service](https://github.com/arnavmahajan630/certiproof-v2/blob/main/gateway/src/services/verifyService.js): `gateway/src/services/verifyService.js`
- [EZKL proof pipeline](https://github.com/arnavmahajan630/certiproof-v2/blob/main/ml-worker/app/zk/rcajx_ezkl_pipeline.py): `ml-worker/app/zk/rcajx_ezkl_pipeline.py`

### Other components

- **Teacher**
- **Student**
- **Auditor**
- **Browser**
- **Gemini API**
- **SQLite store**

## Connections

- Teacher → Teacher view: uses
- Student → Student view: uses
- Auditor → Auditor view: uses
- Browser → Role views: loads
- Role views → Teacher view: selects
- Role views → Student view: selects
- Role views → Auditor view: selects
- Teacher view → API client: requests
- Student view → API client: requests
- Auditor view → API client: requests
- API client → Express app: REST
- Express app → Teacher routes: dispatches
- Express app → Student routes: dispatches
- Express app → Auditor routes: dispatches
- Teacher routes → Worker client: gets model identity
- Teacher routes → SQLite records: certifies rubric
- Teacher routes → Evaluation pipeline: starts evaluation
- Teacher routes → Worker client: transcribes scan
- Student routes → Evaluation pipeline: starts evaluation
- Evaluation pipeline → SQLite records: reads rubric; saves results
- Evaluation pipeline → Audit chain: appends submission and witness
- Evaluation pipeline → Worker client: requests embedding, proof, score
- Evaluation pipeline → Scorecard service: generates scorecard
- Scorecard service → SQLite records: stores scorecard metadata
- Teacher routes → Audit chain: records override
- Auditor routes → Verification service: requests verification
- Student routes → Verification service: checks scorecard
- Verification service → SQLite records: loads evaluation bundle
- Verification service → Audit chain: checks chain
- Verification service → Worker client: recomputes commitment; verifies proof
- Worker client → Worker endpoints: HTTP requests
- Worker endpoints → Stage 0 embeddings: embeds answer
- Worker endpoints → RCAJ-X scoring: scores inputs
- Worker endpoints → Evidence explanations: derives explanations
- Worker endpoints → EZKL proof pipeline: proves; verifies; recomputes commitment
- Worker endpoints → OCR transcription: transcribes image
- OCR transcription → Gemini API: sends image and prompt
- SQLite records → SQLite store: reads and writes