# deva1559/validator architecture

> Architecture diagram of the GitHub repository deva1559/validator, 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/deva1559/validator
- Repository: https://github.com/deva1559/validator

## Overview

Model Validator AI is an educator-facing platform for deterministic notebook audits. Faculty submit student details and an .ipynb assignment; the backend inspects notebook cells for dataset hygiene, training procedure, leakage, and metric evidence, then scores the run against configurable baselines and stores results for review. The UI also exposes dashboards, student records, a validation queue, leaderboard, and exportable audit reports. The main API excerpt is partial, so some frontend-to-backend links are shown as unverified rather than inferred from matching feature names.

Main entry points: [`backend/main.py`](https://github.com/deva1559/validator/blob/main/backend/main.py) (Validation API), [`frontend/src/App.tsx`](https://github.com/deva1559/validator/blob/main/frontend/src/App.tsx) (Application shell), [`frontend/src/config.ts`](https://github.com/deva1559/validator/blob/main/frontend/src/config.ts) (API configuration), [`frontend/src/components/UploadProjects.tsx`](https://github.com/deva1559/validator/blob/main/frontend/src/components/UploadProjects.tsx) (Project upload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Review interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_sidebar["Navigation<br/>[Sidebar.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
end

subgraph group_submission["Submission and audit"]
  node_upload_ui["Project upload<br/>[UploadProjects.tsx]"]
  node_api_config["API configuration<br/>[config.ts]"]
  node_api["Validation API<br/>[main.py]"]
  node_audit_engine["Notebook audit engine<br/>[evidence.py]"]
end

subgraph group_scoring["Scoring and records"]
  node_baseline_ui["Baseline settings<br/>[BaselineConfig.tsx]"]
  node_baseline_scoring["Baseline scoring<br/>[evidence.py]"]
  node_records[("Validation records<br/>[database.py]")]
end

subgraph group_insights["Audit review"]
  node_queue["Validation queue"]
  node_students["Student records<br/>[Students.tsx]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.tsx]"]
  node_reports["Audit reports<br/>[Reports.tsx]"]
end

node_faculty(("Faculty"))

node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_upload_ui
node_app -->|"renders"| node_baseline_ui
node_app -->|"renders"| node_queue
node_app -->|"renders"| node_students
node_app -->|"renders"| node_leaderboard
node_app -->|"renders"| node_reports
node_faculty -.->|"submits notebook"| node_upload_ui
node_upload_ui -.->|"uploads assignment"| node_api
node_api -->|"analyzes notebook"| node_audit_engine
node_audit_engine -->|"writes evidence"| node_records
node_api -->|"reads and updates"| node_records
node_baseline_ui -.->|"updates baselines"| node_api
node_api -->|"re-evaluates runs"| node_baseline_scoring
node_baseline_scoring -->|"stores scores"| node_records
node_queue -.->|"requests leaderboard"| node_api
node_dashboard -.->|"loads metrics"| node_api
node_students -.->|"loads student data"| node_api
node_leaderboard -.->|"loads rankings"| node_api
node_reports -.->|"loads audit dossier"| node_api
node_upload_ui -->|"uses endpoint config"| node_api_config
node_queue -->|"uses endpoint config"| node_api_config
node_students -->|"uses endpoint config"| node_api_config
node_dashboard -.->|"uses endpoint config"| node_api_config
node_leaderboard -.->|"uses endpoint config"| node_api_config
node_reports -.->|"uses endpoint config"| node_api_config
node_baseline_ui -->|"uses endpoint config"| node_api_config

click node_app "https://github.com/deva1559/validator/blob/main/frontend/src/App.tsx"
click node_sidebar "https://github.com/deva1559/validator/blob/main/frontend/src/components/Sidebar.tsx"
click node_dashboard "https://github.com/deva1559/validator/blob/main/frontend/src/components/Dashboard.tsx"
click node_upload_ui "https://github.com/deva1559/validator/blob/main/frontend/src/components/UploadProjects.tsx"
click node_api_config "https://github.com/deva1559/validator/blob/main/frontend/src/config.ts"
click node_api "https://github.com/deva1559/validator/blob/main/backend/main.py"
click node_audit_engine "https://github.com/deva1559/validator/blob/main/backend/evidence.py"
click node_baseline_ui "https://github.com/deva1559/validator/blob/main/frontend/src/components/BaselineConfig.tsx"
click node_baseline_scoring "https://github.com/deva1559/validator/blob/main/backend/evidence.py"
click node_records "https://github.com/deva1559/validator/blob/main/backend/database.py"
click node_queue "https://github.com/deva1559/validator/blob/main/frontend/src/components/ValidationQueue.tsx"
click node_students "https://github.com/deva1559/validator/blob/main/frontend/src/components/Students.tsx"
click node_leaderboard "https://github.com/deva1559/validator/blob/main/frontend/src/components/Leaderboard.tsx"
click node_reports "https://github.com/deva1559/validator/blob/main/frontend/src/components/Reports.tsx"

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_sidebar,node_dashboard toneBlue
class node_upload_ui,node_api_config,node_api,node_audit_engine toneAmber
class node_baseline_ui,node_baseline_scoring,node_records toneMint
class node_queue,node_students,node_leaderboard,node_reports toneRose
class node_faculty toneIndigo
```

## Components

### Review interface

- [Application shell](https://github.com/deva1559/validator/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Navigation](https://github.com/deva1559/validator/blob/main/frontend/src/components/Sidebar.tsx): `frontend/src/components/Sidebar.tsx`
- [Dashboard](https://github.com/deva1559/validator/blob/main/frontend/src/components/Dashboard.tsx): `frontend/src/components/Dashboard.tsx`

### Submission and audit

- [Project upload](https://github.com/deva1559/validator/blob/main/frontend/src/components/UploadProjects.tsx): `frontend/src/components/UploadProjects.tsx`
- [API configuration](https://github.com/deva1559/validator/blob/main/frontend/src/config.ts): `frontend/src/config.ts`
- [Validation API](https://github.com/deva1559/validator/blob/main/backend/main.py): `backend/main.py`
- [Notebook audit engine](https://github.com/deva1559/validator/blob/main/backend/evidence.py): `backend/evidence.py`

### Scoring and records

- [Baseline settings](https://github.com/deva1559/validator/blob/main/frontend/src/components/BaselineConfig.tsx): `frontend/src/components/BaselineConfig.tsx`
- [Baseline scoring](https://github.com/deva1559/validator/blob/main/backend/evidence.py): `backend/evidence.py`
- [Validation records](https://github.com/deva1559/validator/blob/main/backend/database.py): `backend/database.py`

### Audit review

- [Validation queue](https://github.com/deva1559/validator/blob/main/frontend/src/components/ValidationQueue.tsx): `frontend/src/components/ValidationQueue.tsx`
- [Student records](https://github.com/deva1559/validator/blob/main/frontend/src/components/Students.tsx): `frontend/src/components/Students.tsx`
- [Leaderboard](https://github.com/deva1559/validator/blob/main/frontend/src/components/Leaderboard.tsx): `frontend/src/components/Leaderboard.tsx`
- [Audit reports](https://github.com/deva1559/validator/blob/main/frontend/src/components/Reports.tsx): `frontend/src/components/Reports.tsx`

### Other components

- **Faculty**

## Connections

- Application shell → Navigation: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Dashboard: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Project upload: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Baseline settings: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Validation queue: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Student records: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Leaderboard: renders (evidence: `frontend/src/App.tsx`)
- Application shell → Audit reports: renders (evidence: `frontend/src/App.tsx`)
- Faculty → Project upload: submits notebook (evidence: `README.md`)
- Project upload → Validation API: uploads assignment
- Validation API → Notebook audit engine: analyzes notebook (evidence: `backend/main.py`)
- Notebook audit engine → Validation records: writes evidence (evidence: `backend/evidence.py`)
- Validation API → Validation records: reads and updates (evidence: `backend/main.py`)
- Baseline settings → Validation API: updates baselines
- Validation API → Baseline scoring: re-evaluates runs (evidence: `backend/main.py`)
- Baseline scoring → Validation records: stores scores (evidence: `backend/evidence.py`)
- Validation queue → Validation API: requests leaderboard
- Dashboard → Validation API: loads metrics
- Student records → Validation API: loads student data
- Leaderboard → Validation API: loads rankings
- Audit reports → Validation API: loads audit dossier
- Project upload → API configuration: uses endpoint config (evidence: `frontend/src/components/UploadProjects.tsx`)
- Validation queue → API configuration: uses endpoint config (evidence: `frontend/src/components/ValidationQueue.tsx`)
- Student records → API configuration: uses endpoint config (evidence: `frontend/src/components/Students.tsx`)
- Dashboard → API configuration: uses endpoint config (evidence: `frontend/src/components/Dashboard.tsx`)
- Leaderboard → API configuration: uses endpoint config (evidence: `frontend/src/components/Leaderboard.tsx`)
- Audit reports → API configuration: uses endpoint config (evidence: `frontend/src/components/Reports.tsx`)
- Baseline settings → API configuration: uses endpoint config (evidence: `frontend/src/components/BaselineConfig.tsx`)
