# ansh339412/marksure architecture

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

- Interactive diagram: https://gitdiagram.com/ansh339412/marksure
- Repository: https://github.com/ansh339412/marksure

## Overview

MarkSure publishes academic results as signed, Merkle-committed records, then supports student access, public QR verification, audit history, and dual-approval corrections. The main path runs from administrator publication through API validation and cryptographic commitment into Supabase; verification retrieves stored artifacts and checks them against the current record. The graph includes the role-based web workspaces and separate correction and audit branches. Some route and page implementations were not excerpted, so their capabilities and connections are included only where the README or source index supports them.

Main entry points: [`server/src/routes/admin.ts`](https://github.com/ansh339412/marksure/blob/main/server/src/routes/admin.ts) (Publication routes), [`server/src/index.ts`](https://github.com/ansh339412/marksure/blob/main/server/src/index.ts) (Express API), [`client/src/lib/api.ts`](https://github.com/ansh339412/marksure/blob/main/client/src/lib/api.ts) (HTTP client), [`server/src/services/verificationService.ts`](https://github.com/ansh339412/marksure/blob/main/server/src/services/verificationService.ts) (Verification service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspaces"]
  node_admin["Admin workspace<br/>[AdminDashboard.tsx]"]
  node_student["Student records"]
  node_verifyui["Verification workspace<br/>[VerifyPage.tsx]"]
  node_correctionui["Correction workspace"]
  node_auditui["Audit workspace"]
  node_authui["Session context<br/>[AuthContext.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_academic["Academic policy<br/>[academicPolicy.ts]"]
end

subgraph group_api["API workflows"]
  node_server["Express API<br/>[index.ts]"]
  node_authroutes["Authentication routes<br/>[authRoutes.ts]"]
  node_adminroutes["Publication routes<br/>[admin.ts]"]
  node_studentroutes["Student routes<br/>[student.ts]"]
  node_verifyroutes["Verification routes<br/>[verify.ts]"]
  node_correctionroutes["Correction routes<br/>[corrections.ts]"]
  node_auditroutes["Audit routes<br/>[audit.ts]"]
  node_authmw["Role authorization<br/>[auth.ts]"]
end

subgraph group_integrity["Integrity services"]
  node_correction["Correction service"]
  node_verification["Verification service"]
  node_ledger["Append-only ledger<br/>[ledger.ts]"]
  node_canonical["Canonical records<br/>[canonical.ts]"]
  node_hash["SHA-256 hashing<br/>[hash.ts]"]
  node_merkle["Merkle proofs<br/>[merkle.ts]"]
  node_signatures["Ed25519 signatures<br/>[signatures.ts]"]
  node_verifycrypto["Result verifier<br/>[verifyResult.ts]"]
end

subgraph group_data["Persistence"]
  node_supabase[("Supabase records<br/>[supabase.ts]")]
end

node_actor(("Institutional users"))

node_actor -.->|"publishes batch"| node_admin
node_actor -.->|"views results"| node_student
node_actor -.->|"checks result"| node_verifyui
node_actor -.->|"requests correction"| node_correctionui
node_actor -.->|"reviews history"| node_auditui
node_admin -.->|"submits records"| node_api_client
node_student -.->|"requests records"| node_api_client
node_verifyui -->|"requests verification"| node_api_client
node_correctionui -->|"submits approvals"| node_api_client
node_auditui -->|"requests audit"| node_api_client
node_authui -->|"restores session"| node_api_client
node_api_client -.->|"sends HTTP"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_adminroutes
node_server -->|"mounts routes"| node_studentroutes
node_server -->|"mounts routes"| node_verifyroutes
node_server -->|"mounts routes"| node_correctionroutes
node_server -->|"mounts routes"| node_auditroutes
node_authroutes -->|"checks identity"| node_authmw
node_adminroutes -->|"checks roles"| node_authmw
node_adminroutes -->|"records publication"| node_ledger
node_adminroutes -->|"checks results"| node_verification
node_correctionroutes -->|"processes requests"| node_correction
node_correctionroutes -->|"records corrections"| node_ledger
node_verifyroutes -->|"verifies result"| node_verification
node_auditroutes -->|"checks integrity"| node_verification
node_verification -->|"loads artifacts"| node_supabase
node_verification -->|"checks snapshot"| node_verifycrypto
node_correction -->|"preserves history"| node_ledger
node_adminroutes -->|"normalizes records"| node_canonical
node_adminroutes -->|"hashes records"| node_hash
node_adminroutes -->|"builds commitment"| node_merkle
node_adminroutes -->|"signs publication"| node_signatures
node_correctionroutes -->|"checks approvals"| node_signatures
node_canonical -->|"serializes input"| node_hash
node_signatures -->|"canonicalizes payload"| node_canonical
node_signatures -->|"hashes payload"| node_hash
node_merkle -->|"hashes tree nodes"| node_hash
node_verifycrypto -->|"validates proof"| node_merkle
node_verifycrypto -->|"validates signature"| node_signatures

click node_admin "https://github.com/ansh339412/marksure/blob/main/client/src/pages/AdminDashboard.tsx"
click node_student "https://github.com/ansh339412/marksure/blob/main/client/src/pages/StudentDashboard.tsx"
click node_verifyui "https://github.com/ansh339412/marksure/blob/main/client/src/pages/VerifyPage.tsx"
click node_correctionui "https://github.com/ansh339412/marksure/blob/main/client/src/pages/CorrectionsPage.tsx"
click node_auditui "https://github.com/ansh339412/marksure/blob/main/client/src/pages/AuditDashboardPage.tsx"
click node_authui "https://github.com/ansh339412/marksure/blob/main/client/src/context/AuthContext.tsx"
click node_api_client "https://github.com/ansh339412/marksure/blob/main/client/src/lib/api.ts"
click node_academic "https://github.com/ansh339412/marksure/blob/main/client/src/lib/academicPolicy.ts"
click node_server "https://github.com/ansh339412/marksure/blob/main/server/src/index.ts"
click node_authroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/authRoutes.ts"
click node_adminroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/admin.ts"
click node_studentroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/student.ts"
click node_verifyroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/verify.ts"
click node_correctionroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/corrections.ts"
click node_auditroutes "https://github.com/ansh339412/marksure/blob/main/server/src/routes/audit.ts"
click node_authmw "https://github.com/ansh339412/marksure/blob/main/server/src/middleware/auth.ts"
click node_correction "https://github.com/ansh339412/marksure/blob/main/server/src/services/correctionService.ts"
click node_verification "https://github.com/ansh339412/marksure/blob/main/server/src/services/verificationService.ts"
click node_ledger "https://github.com/ansh339412/marksure/blob/main/server/src/services/ledger.ts"
click node_canonical "https://github.com/ansh339412/marksure/blob/main/server/src/crypto/canonical.ts"
click node_hash "https://github.com/ansh339412/marksure/blob/main/server/src/crypto/hash.ts"
click node_merkle "https://github.com/ansh339412/marksure/blob/main/server/src/crypto/merkle.ts"
click node_signatures "https://github.com/ansh339412/marksure/blob/main/server/src/crypto/signatures.ts"
click node_verifycrypto "https://github.com/ansh339412/marksure/blob/main/server/src/crypto/verifyResult.ts"
click node_supabase "https://github.com/ansh339412/marksure/blob/main/server/src/config/supabase.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_admin,node_student,node_verifyui,node_correctionui,node_auditui,node_authui,node_api_client,node_academic,node_actor toneBlue
class node_server,node_authroutes,node_adminroutes,node_studentroutes,node_verifyroutes,node_correctionroutes,node_auditroutes,node_authmw toneAmber
class node_correction,node_verification,node_ledger,node_canonical,node_hash,node_merkle,node_signatures,node_verifycrypto toneMint
class node_supabase toneRose
```

## Components

### Web workspaces

- [Admin workspace](https://github.com/ansh339412/marksure/blob/main/client/src/pages/AdminDashboard.tsx): `client/src/pages/AdminDashboard.tsx`
- [Student records](https://github.com/ansh339412/marksure/blob/main/client/src/pages/StudentDashboard.tsx): `client/src/pages/StudentDashboard.tsx`
- [Verification workspace](https://github.com/ansh339412/marksure/blob/main/client/src/pages/VerifyPage.tsx): `client/src/pages/VerifyPage.tsx`
- [Correction workspace](https://github.com/ansh339412/marksure/blob/main/client/src/pages/CorrectionsPage.tsx): `client/src/pages/CorrectionsPage.tsx`
- [Audit workspace](https://github.com/ansh339412/marksure/blob/main/client/src/pages/AuditDashboardPage.tsx): `client/src/pages/AuditDashboardPage.tsx`
- [Session context](https://github.com/ansh339412/marksure/blob/main/client/src/context/AuthContext.tsx): `client/src/context/AuthContext.tsx`
- [HTTP client](https://github.com/ansh339412/marksure/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`
- [Academic policy](https://github.com/ansh339412/marksure/blob/main/client/src/lib/academicPolicy.ts): `client/src/lib/academicPolicy.ts`

### API workflows

- [Express API](https://github.com/ansh339412/marksure/blob/main/server/src/index.ts): `server/src/index.ts`
- [Authentication routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/authRoutes.ts): `server/src/routes/authRoutes.ts`
- [Publication routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/admin.ts): `server/src/routes/admin.ts`
- [Student routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/student.ts): `server/src/routes/student.ts`
- [Verification routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/verify.ts): `server/src/routes/verify.ts`
- [Correction routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/corrections.ts): `server/src/routes/corrections.ts`
- [Audit routes](https://github.com/ansh339412/marksure/blob/main/server/src/routes/audit.ts): `server/src/routes/audit.ts`
- [Role authorization](https://github.com/ansh339412/marksure/blob/main/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`

### Integrity services

- [Correction service](https://github.com/ansh339412/marksure/blob/main/server/src/services/correctionService.ts): `server/src/services/correctionService.ts`
- [Verification service](https://github.com/ansh339412/marksure/blob/main/server/src/services/verificationService.ts): `server/src/services/verificationService.ts`
- [Append-only ledger](https://github.com/ansh339412/marksure/blob/main/server/src/services/ledger.ts): `server/src/services/ledger.ts`
- [Canonical records](https://github.com/ansh339412/marksure/blob/main/server/src/crypto/canonical.ts): `server/src/crypto/canonical.ts`
- [SHA-256 hashing](https://github.com/ansh339412/marksure/blob/main/server/src/crypto/hash.ts): `server/src/crypto/hash.ts`
- [Merkle proofs](https://github.com/ansh339412/marksure/blob/main/server/src/crypto/merkle.ts): `server/src/crypto/merkle.ts`
- [Ed25519 signatures](https://github.com/ansh339412/marksure/blob/main/server/src/crypto/signatures.ts): `server/src/crypto/signatures.ts`
- [Result verifier](https://github.com/ansh339412/marksure/blob/main/server/src/crypto/verifyResult.ts): `server/src/crypto/verifyResult.ts`

### Persistence

- [Supabase records](https://github.com/ansh339412/marksure/blob/main/server/src/config/supabase.ts): `server/src/config/supabase.ts`

### Other components

- **Institutional users**

## Connections

- Institutional users → Admin workspace: publishes batch
- Institutional users → Student records: views results
- Institutional users → Verification workspace: checks result
- Institutional users → Correction workspace: requests correction
- Institutional users → Audit workspace: reviews history
- Admin workspace → HTTP client: submits records (evidence: `client/src/pages/AdminDashboard.tsx`)
- Student records → HTTP client: requests records
- Verification workspace → HTTP client: requests verification (evidence: `client/src/pages/VerifyPage.tsx`)
- Correction workspace → HTTP client: submits approvals (evidence: `client/src/pages/CorrectionsPage.tsx`)
- Audit workspace → HTTP client: requests audit (evidence: `client/src/pages/AuditDashboardPage.tsx`)
- Session context → HTTP client: restores session (evidence: `client/src/context/AuthContext.tsx`)
- HTTP client → Express API: sends HTTP
- Express API → Authentication routes: mounts routes (evidence: `server/src/index.ts`)
- Express API → Publication routes: mounts routes (evidence: `server/src/index.ts`)
- Express API → Student routes: mounts routes (evidence: `server/src/index.ts`)
- Express API → Verification routes: mounts routes (evidence: `server/src/index.ts`)
- Express API → Correction routes: mounts routes (evidence: `server/src/index.ts`)
- Express API → Audit routes: mounts routes (evidence: `server/src/index.ts`)
- Authentication routes → Role authorization: checks identity (evidence: `server/src/routes/authRoutes.ts`)
- Publication routes → Role authorization: checks roles (evidence: `server/src/routes/admin.ts`)
- Publication routes → Append-only ledger: records publication (evidence: `server/src/routes/admin.ts`)
- Publication routes → Verification service: checks results (evidence: `server/src/routes/admin.ts`)
- Correction routes → Correction service: processes requests (evidence: `server/src/routes/corrections.ts`)
- Correction routes → Append-only ledger: records corrections (evidence: `server/src/routes/corrections.ts`)
- Verification routes → Verification service: verifies result (evidence: `server/src/routes/verify.ts`)
- Audit routes → Verification service: checks integrity (evidence: `server/src/routes/audit.ts`)
- Verification service → Supabase records: loads artifacts (evidence: `server/src/services/verificationService.ts`)
- Verification service → Result verifier: checks snapshot (evidence: `server/src/services/verificationService.ts`)
- Correction service → Append-only ledger: preserves history (evidence: `server/src/services/correctionService.ts`)
- Publication routes → Canonical records: normalizes records (evidence: `server/src/routes/admin.ts`)
- Publication routes → SHA-256 hashing: hashes records (evidence: `server/src/routes/admin.ts`)
- Publication routes → Merkle proofs: builds commitment (evidence: `server/src/routes/admin.ts`)
- Publication routes → Ed25519 signatures: signs publication (evidence: `server/src/routes/admin.ts`)
- Correction routes → Ed25519 signatures: checks approvals (evidence: `server/src/routes/corrections.ts`)
- Canonical records → SHA-256 hashing: serializes input (evidence: `server/src/crypto/hash.ts`)
- Ed25519 signatures → Canonical records: canonicalizes payload (evidence: `server/src/crypto/signatures.ts`)
- Ed25519 signatures → SHA-256 hashing: hashes payload (evidence: `server/src/crypto/signatures.ts`)
- Merkle proofs → SHA-256 hashing: hashes tree nodes (evidence: `server/src/crypto/merkle.ts`)
- Result verifier → Merkle proofs: validates proof (evidence: `server/src/crypto/verifyResult.ts`)
- Result verifier → Ed25519 signatures: validates signature (evidence: `server/src/crypto/verifyResult.ts`)
