# sreekanthbathala/examageis architecture

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

## Overview

ExamAegis takes students from authentication and exam-session creation into live webcam, microphone, and browser-event monitoring. The monitor orchestrates specialist detectors, while a temporal violation engine applies thresholds, records incidents, and captures high-severity screenshots. Students receive live feedback; instructors review sessions, timelines, integrity scores, and JSON exports. The graph follows documented routes and sampled calls; some browser-to-endpoint wiring and report UI details are supported only by the README, not inspected source excerpts.

Main entry points: [`app/api/routes_monitor.py`](https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_monitor.py) (WebSocket monitor), [`app/models/database.py`](https://github.com/sreekanthbathala/examageis/blob/main/app/models/database.py) (SQL database), [`app/main.py`](https://github.com/sreekanthbathala/examageis/blob/main/app/main.py) (FastAPI app), [`app/core/violation_engine.py`](https://github.com/sreekanthbathala/examageis/blob/main/app/core/violation_engine.py) (Violation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser clients"]
  node_student_ui["Exam room<br/>[index.html]"]
  node_webcam["Webcam capture<br/>[webcam.js]"]
  node_socket_client["Socket and audio<br/>[socket_client.js]"]
  node_focus_monitor["Focus monitor<br/>[focus_monitor.js]"]
  node_fullscreen_monitor["Fullscreen monitor"]
  node_admin_ui["Admin dashboard"]
  node_dashboard_js["Dashboard rendering<br/>[dashboard.js]"]
end

subgraph group_api["API workflows"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[routes_auth.py]"]
  node_exam["Exam sessions<br/>[routes_exam.py]"]
end

subgraph group_monitor["Live proctoring"]
  node_monitor_route["WebSocket monitor<br/>[routes_monitor.py]"]
  node_face["Face detection<br/>[face_detection.py]"]
  node_gaze["Eye gaze<br/>[eye_gaze.py]"]
  node_blink["Blink detection<br/>[blink_detection.py]"]
  node_head_pose["Head pose<br/>[head_pose.py]"]
  node_mouth["Mouth tracking<br/>[mouth_tracking.py]"]
  node_objects["Object detection"]
  node_audio["Audio detection<br/>[audio_detection.py]"]
  node_violations["Violation engine"]
  node_frame_utils["Frame utilities<br/>[frame_utils.py]"]
  node_config["Threshold settings<br/>[config.py]"]
end

subgraph group_persistence["Session and records"]
  node_db[("SQL database<br/>[database.py]")]
  node_student_model["Student records<br/>[student.py]"]
  node_session_model["Exam sessions<br/>[exam_session.py]"]
  node_violation_model["Violation logs<br/>[violation_log.py]"]
end

subgraph group_review["Incident review"]
  node_report["Reports and exports<br/>[routes_report.py]"]
  node_integrity["Integrity scoring<br/>[integrity_score.py]"]
end

node_student(("Student"))
node_instructor(("Instructor"))

node_student -->|"uses"| node_student_ui
node_instructor -->|"uses"| node_admin_ui
node_student_ui -->|"captures video"| node_webcam
node_student_ui -->|"streams media"| node_socket_client
node_focus_monitor -.->|"reports events"| node_socket_client
node_fullscreen_monitor -.->|"reports events"| node_socket_client
node_socket_client -->|"sends frames and audio"| node_monitor_route
node_monitor_route -->|"returns alerts"| node_socket_client
node_admin_ui -->|"renders dashboard"| node_dashboard_js
node_dashboard_js -.->|"requests reports"| node_report
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_exam
node_app -->|"registers routes"| node_monitor_route
node_app -->|"registers routes"| node_report
node_app -->|"initializes"| node_db
node_auth -->|"queries and writes"| node_db
node_auth -->|"authenticates"| node_student_model
node_exam -->|"checks identity"| node_auth
node_exam -->|"creates and updates"| node_session_model
node_exam -->|"clears session state"| node_violations
node_monitor_route -->|"loads session"| node_db
node_monitor_route -->|"decodes frames"| node_frame_utils
node_monitor_route -->|"detects faces"| node_face
node_monitor_route -->|"estimates gaze"| node_gaze
node_monitor_route -->|"measures blinks"| node_blink
node_monitor_route -->|"estimates pose"| node_head_pose
node_monitor_route -->|"measures mouth"| node_mouth
node_monitor_route -->|"detects objects"| node_objects
node_monitor_route -->|"analyzes audio"| node_audio
node_monitor_route -->|"processes detections"| node_violations
node_violations -->|"records incidents"| node_violation_model
node_violations -->|"saves screenshots"| node_frame_utils
node_violations -->|"reads thresholds"| node_config
node_db -->|"registers schema"| node_student_model
node_db -->|"registers schema"| node_session_model
node_db -->|"registers schema"| node_violation_model
node_report -->|"checks identity"| node_auth
node_report -->|"queries records"| node_db
node_report -->|"calculates score"| node_integrity
node_integrity -->|"scores incidents"| node_violation_model

click node_student_ui "https://github.com/sreekanthbathala/examageis/blob/main/frontend/index.html"
click node_webcam "https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/webcam.js"
click node_socket_client "https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/socket_client.js"
click node_focus_monitor "https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/focus_monitor.js"
click node_fullscreen_monitor "https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/fullscreen_monitor.js"
click node_admin_ui "https://github.com/sreekanthbathala/examageis/blob/main/frontend/admin_dashboard.html"
click node_dashboard_js "https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/dashboard.js"
click node_app "https://github.com/sreekanthbathala/examageis/blob/main/app/main.py"
click node_auth "https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_auth.py"
click node_exam "https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_exam.py"
click node_monitor_route "https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_monitor.py"
click node_face "https://github.com/sreekanthbathala/examageis/blob/main/app/core/face_detection.py"
click node_gaze "https://github.com/sreekanthbathala/examageis/blob/main/app/core/eye_gaze.py"
click node_blink "https://github.com/sreekanthbathala/examageis/blob/main/app/core/blink_detection.py"
click node_head_pose "https://github.com/sreekanthbathala/examageis/blob/main/app/core/head_pose.py"
click node_mouth "https://github.com/sreekanthbathala/examageis/blob/main/app/core/mouth_tracking.py"
click node_objects "https://github.com/sreekanthbathala/examageis/blob/main/app/core/object_detection.py"
click node_audio "https://github.com/sreekanthbathala/examageis/blob/main/app/core/audio_detection.py"
click node_violations "https://github.com/sreekanthbathala/examageis/blob/main/app/core/violation_engine.py"
click node_frame_utils "https://github.com/sreekanthbathala/examageis/blob/main/app/utils/frame_utils.py"
click node_config "https://github.com/sreekanthbathala/examageis/blob/main/app/config.py"
click node_db "https://github.com/sreekanthbathala/examageis/blob/main/app/models/database.py"
click node_student_model "https://github.com/sreekanthbathala/examageis/blob/main/app/models/student.py"
click node_session_model "https://github.com/sreekanthbathala/examageis/blob/main/app/models/exam_session.py"
click node_violation_model "https://github.com/sreekanthbathala/examageis/blob/main/app/models/violation_log.py"
click node_report "https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_report.py"
click node_integrity "https://github.com/sreekanthbathala/examageis/blob/main/app/core/integrity_score.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_student_ui,node_webcam,node_socket_client,node_focus_monitor,node_fullscreen_monitor,node_admin_ui,node_dashboard_js toneBlue
class node_app,node_auth,node_exam toneAmber
class node_monitor_route,node_face,node_gaze,node_blink,node_head_pose,node_mouth,node_objects,node_audio,node_violations,node_frame_utils,node_config toneMint
class node_db,node_student_model,node_session_model,node_violation_model toneRose
class node_report,node_integrity,node_student,node_instructor toneIndigo
```

## Components

### Browser clients

- [Exam room](https://github.com/sreekanthbathala/examageis/blob/main/frontend/index.html): `frontend/index.html`
- [Webcam capture](https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/webcam.js): `frontend/js/webcam.js`
- [Socket and audio](https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/socket_client.js): `frontend/js/socket_client.js`
- [Focus monitor](https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/focus_monitor.js): `frontend/js/focus_monitor.js`
- [Fullscreen monitor](https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/fullscreen_monitor.js): `frontend/js/fullscreen_monitor.js`
- [Admin dashboard](https://github.com/sreekanthbathala/examageis/blob/main/frontend/admin_dashboard.html): `frontend/admin_dashboard.html`
- [Dashboard rendering](https://github.com/sreekanthbathala/examageis/blob/main/frontend/js/dashboard.js): `frontend/js/dashboard.js`

### API workflows

- [FastAPI app](https://github.com/sreekanthbathala/examageis/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_auth.py): `app/api/routes_auth.py`
- [Exam sessions](https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_exam.py): `app/api/routes_exam.py`

### Live proctoring

- [WebSocket monitor](https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_monitor.py): `app/api/routes_monitor.py`
- [Face detection](https://github.com/sreekanthbathala/examageis/blob/main/app/core/face_detection.py): `app/core/face_detection.py`
- [Eye gaze](https://github.com/sreekanthbathala/examageis/blob/main/app/core/eye_gaze.py): `app/core/eye_gaze.py`
- [Blink detection](https://github.com/sreekanthbathala/examageis/blob/main/app/core/blink_detection.py): `app/core/blink_detection.py`
- [Head pose](https://github.com/sreekanthbathala/examageis/blob/main/app/core/head_pose.py): `app/core/head_pose.py`
- [Mouth tracking](https://github.com/sreekanthbathala/examageis/blob/main/app/core/mouth_tracking.py): `app/core/mouth_tracking.py`
- [Object detection](https://github.com/sreekanthbathala/examageis/blob/main/app/core/object_detection.py): `app/core/object_detection.py`
- [Audio detection](https://github.com/sreekanthbathala/examageis/blob/main/app/core/audio_detection.py): `app/core/audio_detection.py`
- [Violation engine](https://github.com/sreekanthbathala/examageis/blob/main/app/core/violation_engine.py): `app/core/violation_engine.py`
- [Frame utilities](https://github.com/sreekanthbathala/examageis/blob/main/app/utils/frame_utils.py): `app/utils/frame_utils.py`
- [Threshold settings](https://github.com/sreekanthbathala/examageis/blob/main/app/config.py): `app/config.py`

### Session and records

- [SQL database](https://github.com/sreekanthbathala/examageis/blob/main/app/models/database.py): `app/models/database.py`
- [Student records](https://github.com/sreekanthbathala/examageis/blob/main/app/models/student.py): `app/models/student.py`
- [Exam sessions](https://github.com/sreekanthbathala/examageis/blob/main/app/models/exam_session.py): `app/models/exam_session.py`
- [Violation logs](https://github.com/sreekanthbathala/examageis/blob/main/app/models/violation_log.py): `app/models/violation_log.py`

### Incident review

- [Reports and exports](https://github.com/sreekanthbathala/examageis/blob/main/app/api/routes_report.py): `app/api/routes_report.py`
- [Integrity scoring](https://github.com/sreekanthbathala/examageis/blob/main/app/core/integrity_score.py): `app/core/integrity_score.py`

### Other components

- **Student**
- **Instructor**

## Connections

- Student → Exam room: uses (evidence: `README.md`)
- Instructor → Admin dashboard: uses (evidence: `README.md`)
- Exam room → Webcam capture: captures video (evidence: `README.md`)
- Exam room → Socket and audio: streams media (evidence: `README.md`)
- Focus monitor → Socket and audio: reports events
- Fullscreen monitor → Socket and audio: reports events
- Socket and audio → WebSocket monitor: sends frames and audio (evidence: `README.md`)
- WebSocket monitor → Socket and audio: returns alerts (evidence: `app/api/routes_monitor.py`)
- Admin dashboard → Dashboard rendering: renders dashboard (evidence: `README.md`)
- Dashboard rendering → Reports and exports: requests reports
- FastAPI app → Authentication: registers routes (evidence: `app/main.py`)
- FastAPI app → Exam sessions: registers routes (evidence: `app/main.py`)
- FastAPI app → WebSocket monitor: registers routes (evidence: `app/main.py`)
- FastAPI app → Reports and exports: registers routes (evidence: `app/main.py`)
- FastAPI app → SQL database: initializes (evidence: `app/main.py`)
- Authentication → SQL database: queries and writes (evidence: `app/api/routes_auth.py`)
- Authentication → Student records: authenticates (evidence: `app/api/routes_auth.py`)
- Exam sessions → Authentication: checks identity (evidence: `app/api/routes_exam.py`)
- Exam sessions → Exam sessions: creates and updates (evidence: `app/api/routes_exam.py`)
- Exam sessions → Violation engine: clears session state (evidence: `app/api/routes_exam.py`)
- WebSocket monitor → SQL database: loads session (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Frame utilities: decodes frames (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Face detection: detects faces (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Eye gaze: estimates gaze (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Blink detection: measures blinks (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Head pose: estimates pose (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Mouth tracking: measures mouth (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Object detection: detects objects (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Audio detection: analyzes audio (evidence: `app/api/routes_monitor.py`)
- WebSocket monitor → Violation engine: processes detections (evidence: `app/api/routes_monitor.py`)
- Violation engine → Violation logs: records incidents (evidence: `app/core/violation_engine.py`)
- Violation engine → Frame utilities: saves screenshots (evidence: `app/core/violation_engine.py`)
- Violation engine → Threshold settings: reads thresholds (evidence: `app/core/violation_engine.py`)
- SQL database → Student records: registers schema (evidence: `app/models/database.py`)
- SQL database → Exam sessions: registers schema (evidence: `app/models/database.py`)
- SQL database → Violation logs: registers schema (evidence: `app/models/database.py`)
- Reports and exports → Authentication: checks identity (evidence: `app/api/routes_report.py`)
- Reports and exports → SQL database: queries records (evidence: `app/api/routes_report.py`)
- Reports and exports → Integrity scoring: calculates score (evidence: `app/api/routes_report.py`)
- Integrity scoring → Violation logs: scores incidents (evidence: `app/core/integrity_score.py`)
