# kadircanyildirm-crypto/quaestor architecture

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

- Interactive diagram: https://gitdiagram.com/kadircanyildirm-crypto/quaestor
- Repository: https://github.com/kadircanyildirm-crypto/quaestor

## Overview

quaestor lets an institution commit to a private answer key before an exam, then prove grading against that key and the candidates’ answer sheets. The principal path batches a sitting, publishes reports and a Merkle root with one proof, and lets each candidate verify their own result and inclusion. A separate single-sheet guest supports per-candidate proofs; the WebAssembly bridge and explainer provide an interactive demonstration. Core modules and guest files are excerpted; some host-side proving and publication details are documented but not shown in source excerpts.

Main entry points: [`zk/program-batch/src/main.rs`](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/zk/program-batch/src/main.rs) (Batch SP1 guest), [`crates/grading-core/src/batch.rs`](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/batch.rs) (Batch and Merkle), [`crates/grading-core/src/score.rs`](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/score.rs) (Score calculation), [`crates/grading-wasm/src/lib.rs`](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-wasm/src/lib.rs) (WASM bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grading["Grading core"]
  node_models["Exam data models<br/>[model.rs]"]
  node_encoding["Canonical encoding<br/>[encode.rs]"]
  node_commit_hash["Commitments and hashes<br/>[commit.rs]"]
  node_scoring["Score calculation<br/>[score.rs]"]
  node_batch["Batch and Merkle<br/>[batch.rs]"]
  node_public_values["Public value ABI<br/>[public_values.rs]"]
end

subgraph group_proofs["Proof execution"]
  node_batch_guest["Batch SP1 guest<br/>[main.rs]"]
  node_single_guest["Single-sheet guest<br/>[main.rs]"]
  node_sp1["SP1 proof runtime"]
  node_proof["Batch proof"]
end

subgraph group_verification["Verification"]
  node_results["Published results"]
  node_check["Inclusion verification<br/>[public_values.rs]"]
end

subgraph group_demo["Browser demo"]
  node_wasm["WASM bindings<br/>[lib.rs]"]
  node_engine["Demo engine<br/>[engine.js]"]
  node_explainer["Interactive explainer<br/>[src.html]"]
end

node_institution(("Institution"))
node_candidate(("Candidate"))

node_institution -->|"commits key"| node_commit_hash
node_commit_hash -->|"encodes key"| node_encoding
node_institution -->|"supplies witness"| node_batch_guest
node_candidate -->|"submits answers"| node_batch_guest
node_batch_guest -->|"decodes inputs"| node_encoding
node_batch_guest -->|"grades sitting"| node_batch
node_batch -->|"scores sheets"| node_scoring
node_scoring -->|"binds hashes"| node_commit_hash
node_batch_guest -->|"encodes public values"| node_public_values
node_batch_guest -->|"executes in"| node_sp1
node_sp1 -->|"produces proof"| node_proof
node_batch -->|"provides reports and paths"| node_results
node_proof -->|"proof verified"| node_check
node_results -->|"supplies report and path"| node_check
node_candidate -->|"checks own result"| node_check
node_single_guest -->|"runs scoring"| node_scoring
node_single_guest -->|"encodes report"| node_public_values
node_wasm -->|"calls batch grading"| node_batch
node_wasm -->|"calls scoring"| node_scoring
node_engine -->|"calls byte API"| node_wasm
node_explainer -.->|"uses demo engine"| node_engine
node_encoding -->|"serializes data"| node_models

click node_models "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/model.rs"
click node_encoding "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/encode.rs"
click node_commit_hash "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/commit.rs"
click node_scoring "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/score.rs"
click node_batch "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/batch.rs"
click node_public_values "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/public_values.rs"
click node_batch_guest "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/zk/program-batch/src/main.rs"
click node_single_guest "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/zk/program/src/main.rs"
click node_check "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/public_values.rs"
click node_wasm "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-wasm/src/lib.rs"
click node_engine "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/explainer/engine.js"
click node_explainer "https://github.com/kadircanyildirm-crypto/quaestor/blob/main/explainer/src.html"

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_models,node_encoding,node_commit_hash,node_scoring,node_batch,node_public_values toneBlue
class node_batch_guest,node_single_guest,node_sp1,node_proof toneAmber
class node_results,node_check toneMint
class node_wasm,node_engine,node_explainer toneRose
class node_institution,node_candidate toneIndigo
```

## Components

### Grading core

- [Exam data models](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/model.rs): `crates/grading-core/src/model.rs`
- [Canonical encoding](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/encode.rs): `crates/grading-core/src/encode.rs`
- [Commitments and hashes](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/commit.rs): `crates/grading-core/src/commit.rs`
- [Score calculation](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/score.rs): `crates/grading-core/src/score.rs`
- [Batch and Merkle](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/batch.rs): `crates/grading-core/src/batch.rs`
- [Public value ABI](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/public_values.rs): `crates/grading-core/src/public_values.rs`

### Proof execution

- [Batch SP1 guest](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/zk/program-batch/src/main.rs): `zk/program-batch/src/main.rs`
- [Single-sheet guest](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/zk/program/src/main.rs): `zk/program/src/main.rs`
- **SP1 proof runtime**
- **Batch proof**

### Verification

- **Published results**
- [Inclusion verification](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-core/src/public_values.rs): `crates/grading-core/src/public_values.rs`

### Browser demo

- [WASM bindings](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/crates/grading-wasm/src/lib.rs): `crates/grading-wasm/src/lib.rs`
- [Demo engine](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/explainer/engine.js): `explainer/engine.js`
- [Interactive explainer](https://github.com/kadircanyildirm-crypto/quaestor/blob/main/explainer/src.html): `explainer/src.html`

### Other components

- **Institution**
- **Candidate**

## Connections

- Institution → Commitments and hashes: commits key (evidence: `README.md`)
- Commitments and hashes → Canonical encoding: encodes key (evidence: `crates/grading-core/src/commit.rs`)
- Institution → Batch SP1 guest: supplies witness (evidence: `README.md`)
- Candidate → Batch SP1 guest: submits answers (evidence: `README.md`)
- Batch SP1 guest → Canonical encoding: decodes inputs (evidence: `zk/program-batch/src/main.rs`)
- Batch SP1 guest → Batch and Merkle: grades sitting (evidence: `zk/program-batch/src/main.rs`)
- Batch and Merkle → Score calculation: scores sheets (evidence: `crates/grading-core/src/batch.rs`)
- Score calculation → Commitments and hashes: binds hashes (evidence: `crates/grading-core/src/score.rs`)
- Batch SP1 guest → Public value ABI: encodes public values (evidence: `zk/program-batch/src/main.rs`)
- Batch SP1 guest → SP1 proof runtime: executes in (evidence: `README.md`)
- SP1 proof runtime → Batch proof: produces proof (evidence: `README.md`)
- Batch and Merkle → Published results: provides reports and paths (evidence: `README.md`)
- Batch proof → Inclusion verification: proof verified (evidence: `README.md`)
- Published results → Inclusion verification: supplies report and path (evidence: `README.md`)
- Candidate → Inclusion verification: checks own result (evidence: `README.md`)
- Single-sheet guest → Score calculation: runs scoring (evidence: `zk/program/src/main.rs`)
- Single-sheet guest → Public value ABI: encodes report (evidence: `zk/program/src/main.rs`)
- WASM bindings → Batch and Merkle: calls batch grading (evidence: `crates/grading-wasm/src/lib.rs`)
- WASM bindings → Score calculation: calls scoring (evidence: `crates/grading-wasm/src/lib.rs`)
- Demo engine → WASM bindings: calls byte API (evidence: `explainer/engine.js`)
- Interactive explainer → Demo engine: uses demo engine (evidence: `README.md`)
- Canonical encoding → Exam data models: serializes data (evidence: `crates/grading-core/src/encode.rs`)
