# hamnmni0/examguard architecture

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

- Interactive diagram: https://gitdiagram.com/hamnmni0/examguard
- Repository: https://github.com/hamnmni0/examguard
- Video tour (about a minute): https://gitdiagram.com/hamnmni0/examguard/video

## Overview

ExamGuard supports instructor account access, exam-session administration, student camera monitoring, live proctoring, and post-session review of flagged events and recordings. The main workflow is an instructor creating a session and sharing its link; a student joins, streams camera frames and recording chunks, and the backend detects and stores events for live viewing and later reporting. Backend wiring is grounded in sampled source; several page and domain implementations were not sampled, so uncertain internal links are omitted.

Main entry points: [`backend/app/sessions.py`](https://github.com/hamnmni0/examguard/blob/main/backend/app/sessions.py) (Session API), [`frontend/src/App.jsx`](https://github.com/hamnmni0/examguard/blob/main/frontend/src/App.jsx) (Route application), [`frontend/src/pages/StudentMonitor.jsx`](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/StudentMonitor.jsx) (Student monitor), [`backend/app/sockets.py`](https://github.com/hamnmni0/examguard/blob/main/backend/app/sockets.py) (Live socket handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["Route application<br/>[App.jsx]"]
  node_home["Home page<br/>[Home.jsx]"]
end

subgraph group_identity["Instructor access"]
  node_login["Login page<br/>[Login.jsx]"]
  node_signup["Signup page<br/>[Signup.jsx]"]
  node_guard["Protected routes<br/>[ProtectedRoute.jsx]"]
  node_authpage["Account screens<br/>[Login.jsx]"]
  node_auth["Account API<br/>[auth.py]"]
end

subgraph group_sessions["Exam sessions"]
  node_dashboard["Session dashboard<br/>[Dashboard.jsx]"]
  node_api["Flask application<br/>[run.py]"]
  node_sessionsapi["Session API<br/>[sessions.py]"]
  node_models[("Relational data models<br/>[models.py]")]
end

subgraph group_monitoring["Monitoring and review"]
  node_studentmonitor["Student monitor<br/>[StudentMonitor.jsx]"]
  node_liveview["Live view<br/>[LiveView.jsx]"]
  node_report["Session report<br/>[SessionReport.jsx]"]
  node_socketservice["Live socket handlers<br/>[sockets.py]"]
  node_detection["Frame detection<br/>[detection.py]"]
  node_scorer["Suspicion scoring<br/>[scorer.py]"]
  node_recordings["Recording files<br/>[sessions.py]"]
end

node_professor(("Instructor"))
node_student(("Student"))
node_browsercamera["Browser camera"]

node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_studentmonitor
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_signup
node_app -->|"routes to"| node_report
node_app -->|"routes to"| node_liveview
node_dashboard -->|"protected by"| node_guard
node_report -->|"protected by"| node_guard
node_liveview -->|"protected by"| node_guard
node_professor -->|"signs in"| node_login
node_professor -->|"registers"| node_signup
node_login -->|"requests token"| node_auth
node_signup -->|"creates account"| node_auth
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_sessionsapi
node_api -->|"registers handlers"| node_socketservice
node_auth -->|"reads and writes"| node_models
node_dashboard -->|"manages sessions"| node_sessionsapi
node_sessionsapi -->|"reads and writes"| node_models
node_professor -->|"administers exams"| node_dashboard
node_dashboard -->|"shares monitor link"| node_studentmonitor
node_student -->|"joins exam"| node_studentmonitor
node_studentmonitor -->|"captures video"| node_browsercamera
node_studentmonitor -->|"joins and uploads chunks"| node_sessionsapi
node_sessionsapi -->|"appends and serves"| node_recordings
node_studentmonitor -->|"sends frames"| node_socketservice
node_liveview -->|"watches session"| node_socketservice
node_socketservice -->|"analyzes frames"| node_detection
node_socketservice -->|"stores flagged events"| node_models
node_socketservice -->|"emits live updates"| node_liveview
node_report -->|"fetches details"| node_sessionsapi
node_sessionsapi -->|"scores on end"| node_scorer
node_scorer -->|"reads event data"| node_models
node_sessionsapi -->|"loads report data"| node_models
node_report -->|"downloads recording"| node_recordings

click node_app "https://github.com/hamnmni0/examguard/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Home.jsx"
click node_login "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Login.jsx"
click node_signup "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Signup.jsx"
click node_guard "https://github.com/hamnmni0/examguard/blob/main/frontend/src/ProtectedRoute.jsx"
click node_authpage "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Dashboard.jsx"
click node_studentmonitor "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/StudentMonitor.jsx"
click node_liveview "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/LiveView.jsx"
click node_report "https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/SessionReport.jsx"
click node_api "https://github.com/hamnmni0/examguard/blob/main/backend/run.py"
click node_auth "https://github.com/hamnmni0/examguard/blob/main/backend/app/auth.py"
click node_sessionsapi "https://github.com/hamnmni0/examguard/blob/main/backend/app/sessions.py"
click node_socketservice "https://github.com/hamnmni0/examguard/blob/main/backend/app/sockets.py"
click node_detection "https://github.com/hamnmni0/examguard/blob/main/backend/app/detection.py"
click node_scorer "https://github.com/hamnmni0/examguard/blob/main/backend/app/scorer.py"
click node_models "https://github.com/hamnmni0/examguard/blob/main/backend/app/models.py"
click node_recordings "https://github.com/hamnmni0/examguard/blob/main/backend/app/sessions.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_home,node_browsercamera toneBlue
class node_login,node_signup,node_guard,node_authpage,node_auth toneAmber
class node_dashboard,node_api,node_sessionsapi,node_models toneMint
class node_studentmonitor,node_liveview,node_report,node_socketservice,node_detection,node_scorer,node_recordings toneRose
class node_professor,node_student toneIndigo
```

## Components

### Web app

- [Route application](https://github.com/hamnmni0/examguard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Home page](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`

### Instructor access

- [Login page](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Signup page](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Signup.jsx): `frontend/src/pages/Signup.jsx`
- [Protected routes](https://github.com/hamnmni0/examguard/blob/main/frontend/src/ProtectedRoute.jsx): `frontend/src/ProtectedRoute.jsx`
- [Account screens](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Account API](https://github.com/hamnmni0/examguard/blob/main/backend/app/auth.py): `backend/app/auth.py`

### Exam sessions

- [Session dashboard](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Flask application](https://github.com/hamnmni0/examguard/blob/main/backend/run.py): `backend/run.py`
- [Session API](https://github.com/hamnmni0/examguard/blob/main/backend/app/sessions.py): `backend/app/sessions.py`
- [Relational data models](https://github.com/hamnmni0/examguard/blob/main/backend/app/models.py): `backend/app/models.py`

### Monitoring and review

- [Student monitor](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/StudentMonitor.jsx): `frontend/src/pages/StudentMonitor.jsx`
- [Live view](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/LiveView.jsx): `frontend/src/pages/LiveView.jsx`
- [Session report](https://github.com/hamnmni0/examguard/blob/main/frontend/src/pages/SessionReport.jsx): `frontend/src/pages/SessionReport.jsx`
- [Live socket handlers](https://github.com/hamnmni0/examguard/blob/main/backend/app/sockets.py): `backend/app/sockets.py`
- [Frame detection](https://github.com/hamnmni0/examguard/blob/main/backend/app/detection.py): `backend/app/detection.py`
- [Suspicion scoring](https://github.com/hamnmni0/examguard/blob/main/backend/app/scorer.py): `backend/app/scorer.py`
- [Recording files](https://github.com/hamnmni0/examguard/blob/main/backend/app/sessions.py): `backend/app/sessions.py`

### Other components

- **Instructor**
- **Student**
- **Browser camera**

## Connections

- Route application → Home page: routes to
- Route application → Student monitor: routes to
- Route application → Session dashboard: routes to
- Route application → Login page: routes to
- Route application → Signup page: routes to
- Route application → Session report: routes to
- Route application → Live view: routes to
- Session dashboard → Protected routes: protected by
- Session report → Protected routes: protected by
- Live view → Protected routes: protected by
- Instructor → Login page: signs in
- Instructor → Signup page: registers
- Login page → Account API: requests token
- Signup page → Account API: creates account
- Flask application → Account API: registers routes
- Flask application → Session API: registers routes
- Flask application → Live socket handlers: registers handlers
- Account API → Relational data models: reads and writes
- Session dashboard → Session API: manages sessions
- Session API → Relational data models: reads and writes
- Instructor → Session dashboard: administers exams
- Session dashboard → Student monitor: shares monitor link
- Student → Student monitor: joins exam
- Student monitor → Browser camera: captures video
- Student monitor → Session API: joins and uploads chunks
- Session API → Recording files: appends and serves
- Student monitor → Live socket handlers: sends frames
- Live view → Live socket handlers: watches session
- Live socket handlers → Frame detection: analyzes frames
- Live socket handlers → Relational data models: stores flagged events
- Live socket handlers → Live view: emits live updates
- Session report → Session API: fetches details
- Session API → Suspicion scoring: scores on end
- Suspicion scoring → Relational data models: reads event data
- Session API → Relational data models: loads report data
- Session report → Recording files: downloads recording