# laksh1441942-wq/exam-shield architecture

> Architecture diagram of the GitHub repository laksh1441942-wq/exam-shield, 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/laksh1441942-wq/exam-shield
- Repository: https://github.com/laksh1441942-wq/exam-shield

## Overview

ExamShield manages a question-paper lifecycle: administrators create exams, upload and parse controlled-format PDFs, generate shuffled variants, encrypt and anchor them, then configure key custody and release controls. After approvals and the on-chain time-lock, centres retrieve released exams through the secure terminal, where authorized decryption, integrity checks, watermarking, and audit logging apply. The API routes orchestrate domain services and persist state. The README documents the end-to-end workflow and capabilities; unsampled blockchain contract and route details are represented only where documented.

Main entry points: [`backend/routes/exams.py`](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/exams.py) (Exam lifecycle routes), [`backend/main.py`](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/main.py) (FastAPI application), [`backend/database.py`](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/database.py) (SQL database), [`frontend/js/terminal.js`](https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/terminal.js) (Secure terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web clients"]
  node_dashboard["Admin dashboard<br/>[dashboard.js]"]
  node_terminal_ui["Secure terminal UI<br/>[terminal.js]"]
  node_api_client["Frontend API client<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_sessions["Signed sessions<br/>[session.py]"]
end

subgraph group_lifecycle["Exam lifecycle"]
  node_exam_routes["Exam lifecycle routes<br/>[exams.py]"]
  node_terminal_routes["Terminal listing<br/>[terminal.py]"]
  node_pdf_parse["Question PDF parsing<br/>[pdf_service.py]"]
  node_variants["Question variants<br/>[variant_service.py]"]
end

subgraph group_security["Release and security"]
  node_crypto["Encryption and hashes<br/>[crypto_service.py]"]
  node_shamir["Shamir key shares<br/>[shamir_service.py]"]
  node_watermark["Centre watermarking"]
  node_chain_adapter["Blockchain adapter"]
  node_contract["Release contract<br/>[ExamShield.sol]"]
end

subgraph group_persistence["Persistence and audit"]
  node_database[("SQL database<br/>[database.py]")]
  node_models["Exam and identity models"]
  node_audit["Audit trail<br/>[audit_service.py]"]
  node_audit_routes["Audit API<br/>[audit.py]"]
  node_artifact_store[("Paper artifact storage")]
end

node_admin(("Super Admin"))
node_centre(("Exam Centre"))

node_admin -->|"uses"| node_dashboard
node_centre -->|"uses"| node_terminal_ui
node_dashboard -.->|"requests API"| node_api_client
node_terminal_ui -.->|"requests API"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"mounts routes"| node_auth
node_app -->|"mounts routes"| node_exam_routes
node_app -->|"mounts routes"| node_terminal_routes
node_app -->|"mounts routes"| node_audit_routes
node_auth -->|"manages sessions"| node_sessions
node_auth -->|"logs events"| node_audit
node_exam_routes -->|"parses uploads"| node_pdf_parse
node_exam_routes -->|"generates variants"| node_variants
node_exam_routes -->|"encrypts artifacts"| node_crypto
node_exam_routes -->|"splits and rebuilds"| node_shamir
node_exam_routes -->|"stamps papers"| node_watermark
node_exam_routes -->|"checks and records"| node_chain_adapter
node_chain_adapter -->|"calls contract"| node_contract
node_exam_routes -->|"reads and writes"| node_database
node_terminal_routes -->|"reads exams"| node_database
node_database -->|"registers schema"| node_models
node_exam_routes -->|"stores artifacts"| node_artifact_store
node_exam_routes -->|"records lifecycle"| node_audit
node_audit_routes -->|"reads audit records"| node_database
node_audit_routes -->|"queries audit model"| node_models
node_terminal_ui -->|"requests decryption"| node_exam_routes

click node_dashboard "https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/dashboard.js"
click node_terminal_ui "https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/terminal.js"
click node_api_client "https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/api.js"
click node_app "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/main.py"
click node_auth "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/auth.py"
click node_sessions "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/utils/session.py"
click node_exam_routes "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/exams.py"
click node_terminal_routes "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/terminal.py"
click node_pdf_parse "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/pdf_service.py"
click node_variants "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/variant_service.py"
click node_crypto "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/crypto_service.py"
click node_shamir "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/shamir_service.py"
click node_watermark "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/watermark_service.py"
click node_chain_adapter "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/blockchain_service.py"
click node_contract "https://github.com/laksh1441942-wq/exam-shield/blob/main/blockchain/contracts/ExamShield.sol"
click node_database "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/database.py"
click node_models "https://github.com/laksh1441942-wq/exam-shield/tree/main/backend/models"
click node_audit "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/audit_service.py"
click node_audit_routes "https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/audit.py"
click node_artifact_store "https://github.com/laksh1441942-wq/exam-shield/tree/main/storage"

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_dashboard,node_terminal_ui,node_api_client toneBlue
class node_app,node_auth,node_sessions toneAmber
class node_exam_routes,node_terminal_routes,node_pdf_parse,node_variants toneMint
class node_crypto,node_shamir,node_watermark,node_chain_adapter,node_contract toneRose
class node_database,node_models,node_audit,node_audit_routes,node_artifact_store,node_admin,node_centre toneIndigo
```

## Components

### Web clients

- [Admin dashboard](https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/dashboard.js): `frontend/js/dashboard.js`
- [Secure terminal UI](https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/terminal.js): `frontend/js/terminal.js`
- [Frontend API client](https://github.com/laksh1441942-wq/exam-shield/blob/main/frontend/js/api.js): `frontend/js/api.js`

### API and identity

- [FastAPI application](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Signed sessions](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/utils/session.py): `backend/utils/session.py`

### Exam lifecycle

- [Exam lifecycle routes](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/exams.py): `backend/routes/exams.py`
- [Terminal listing](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/terminal.py): `backend/routes/terminal.py`
- [Question PDF parsing](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/pdf_service.py): `backend/services/pdf_service.py`
- [Question variants](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/variant_service.py): `backend/services/variant_service.py`

### Release and security

- [Encryption and hashes](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/crypto_service.py): `backend/services/crypto_service.py`
- [Shamir key shares](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/shamir_service.py): `backend/services/shamir_service.py`
- [Centre watermarking](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/watermark_service.py): `backend/services/watermark_service.py`
- [Blockchain adapter](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/blockchain_service.py): `backend/services/blockchain_service.py`
- [Release contract](https://github.com/laksh1441942-wq/exam-shield/blob/main/blockchain/contracts/ExamShield.sol): `blockchain/contracts/ExamShield.sol`

### Persistence and audit

- [SQL database](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/database.py): `backend/database.py`
- [Exam and identity models](https://github.com/laksh1441942-wq/exam-shield/tree/main/backend/models): `backend/models`
- [Audit trail](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/services/audit_service.py): `backend/services/audit_service.py`
- [Audit API](https://github.com/laksh1441942-wq/exam-shield/blob/main/backend/routes/audit.py): `backend/routes/audit.py`
- [Paper artifact storage](https://github.com/laksh1441942-wq/exam-shield/tree/main/storage): `storage`

### Other components

- **Super Admin**
- **Exam Centre**

## Connections

- Super Admin → Admin dashboard: uses (evidence: `README.md`)
- Exam Centre → Secure terminal UI: uses (evidence: `README.md`)
- Admin dashboard → Frontend API client: requests API
- Secure terminal UI → Frontend API client: requests API
- Frontend API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Authentication routes: mounts routes (evidence: `backend/main.py`)
- FastAPI application → Exam lifecycle routes: mounts routes (evidence: `backend/main.py`)
- FastAPI application → Terminal listing: mounts routes (evidence: `backend/main.py`)
- FastAPI application → Audit API: mounts routes (evidence: `backend/main.py`)
- Authentication routes → Signed sessions: manages sessions (evidence: `backend/routes/auth.py`)
- Authentication routes → Audit trail: logs events (evidence: `backend/routes/auth.py`)
- Exam lifecycle routes → Question PDF parsing: parses uploads (evidence: `backend/routes/exams.py`)
- Exam lifecycle routes → Question variants: generates variants (evidence: `backend/routes/exams.py`)
- Exam lifecycle routes → Encryption and hashes: encrypts artifacts (evidence: `backend/routes/exams.py`)
- Exam lifecycle routes → Shamir key shares: splits and rebuilds (evidence: `backend/routes/exams.py`)
- Exam lifecycle routes → Centre watermarking: stamps papers (evidence: `backend/routes/exams.py`)
- Exam lifecycle routes → Blockchain adapter: checks and records (evidence: `backend/routes/exams.py`)
- Blockchain adapter → Release contract: calls contract (evidence: `backend/services/blockchain_service.py`)
- Exam lifecycle routes → SQL database: reads and writes (evidence: `backend/routes/exams.py`)
- Terminal listing → SQL database: reads exams (evidence: `backend/routes/terminal.py`)
- SQL database → Exam and identity models: registers schema (evidence: `backend/database.py`)
- Exam lifecycle routes → Paper artifact storage: stores artifacts (evidence: `README.md`)
- Exam lifecycle routes → Audit trail: records lifecycle (evidence: `README.md`)
- Audit API → SQL database: reads audit records (evidence: `backend/routes/audit.py`)
- Audit API → Exam and identity models: queries audit model (evidence: `backend/routes/audit.py`)
- Secure terminal UI → Exam lifecycle routes: requests decryption (evidence: `README.md`)
