# hasritha-r/aiproctor architecture

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

- Interactive diagram: https://gitdiagram.com/hasritha-r/aiproctor
- Repository: https://github.com/hasritha-r/aiproctor

## Overview

ProctorAI supports student exam-taking with AI-assisted grading and live proctoring, plus an administrator review and verdict workflow. Students register or log in, check their camera, choose an exam, take it under monitoring, and receive results; administrators inspect risk-ranked sessions, events, and snapshots before acting. The graph combines documented product capabilities with source-indexed backend calls and sampled frontend/AI wiring. Several routes, integrations, and storage interactions are not shown in excerpts, so those links are omitted or marked unverified.

Main entry points: [`frontend/src/App.jsx`](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/App.jsx) (Web routes), [`ai-service/main.py`](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/main.py) (AI endpoints), [`frontend/src/pages/ExamRoom.jsx`](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/ExamRoom.jsx) (Exam room), [`backend/src/main/java/com/proctai/repository`](https://github.com/hasritha-r/aiproctor/tree/main/backend/src/main/java/com/proctai/repository) (Exam and user records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student experience"]
  node_web_app["Web routes<br/>[App.jsx]"]
  node_auth_ui["Registration and login"]
  node_camera["Camera check<br/>[CameraSetup.jsx]"]
  node_exam_select["Exam selection<br/>[ExamList.jsx]"]
  node_exam_room["Exam room<br/>[ExamRoom.jsx]"]
  node_monitor_hook["Browser monitoring<br/>[useProctoring.js]"]
  node_student_result["Results<br/>[Result.jsx]"]
  node_frontend_api["Frontend API clients"]
end

subgraph group_admin["Admin review"]
  node_admin_dashboard["Risk dashboard<br/>[AdminDashboard.jsx]"]
  node_student_review["Session review<br/>[StudentReview.jsx]"]
  node_admin_api["Admin API client<br/>[adminApi.js]"]
  node_admin_controller["Admin routes"]
  node_admin_service["Admin decisions<br/>[AdminService.java]"]
end

subgraph group_backend["Exam backend"]
  node_auth_controller["Authentication routes"]
  node_auth_service["Account and tokens<br/>[AuthService.java]"]
  node_exam_controller["Exam routes"]
  node_exam_service["Exam sessions<br/>[ExamService.java]"]
  node_scoring["Scoring and submission"]
end

subgraph group_proctor["Proctoring and AI"]
  node_proctor_service["Event and risk processing"]
  node_ws_controller["WebSocket frame intake"]
  node_ai_client["AI service client"]
  node_ai_api["AI endpoints<br/>[main.py]"]
  node_face_analysis["Face analysis<br/>[face_analyzer.py]"]
  node_question_generation["Question generation"]
  node_ai_grading["Theory grading<br/>[grader.py]"]
  node_risk_model["Risk scoring<br/>[anomaly_model.py]"]
end

subgraph group_data["Domain storage"]
  node_domain_store[("Exam and user records")]
end

node_student_actor(("Student"))
node_admin_actor(("Administrator"))

node_student_actor -->|"registers or logs in"| node_auth_ui
node_auth_ui -->|"continues to"| node_camera
node_camera -->|"continues to"| node_exam_select
node_exam_select -->|"starts exam"| node_exam_room
node_exam_room -->|"submits answers"| node_student_result
node_web_app -->|"routes to"| node_auth_ui
node_web_app -->|"routes to"| node_camera
node_web_app -->|"routes to"| node_exam_select
node_web_app -->|"routes to"| node_exam_room
node_web_app -->|"routes to"| node_student_result
node_exam_room -.->|"monitors session"| node_monitor_hook
node_monitor_hook -->|"logs behavior"| node_frontend_api
node_admin_actor -->|"reviews sessions"| node_admin_dashboard
node_admin_dashboard -.->|"opens review"| node_student_review
node_student_review -->|"loads events and submits verdict"| node_admin_api
node_auth_controller -->|"delegates"| node_auth_service
node_auth_service -->|"reads and saves users"| node_domain_store
node_exam_controller -->|"delegates exam actions"| node_exam_service
node_exam_controller -->|"submits answers"| node_scoring
node_scoring -->|"reads and saves results"| node_domain_store
node_scoring -->|"grades theory"| node_ai_client
node_admin_controller -->|"delegates"| node_admin_service
node_admin_service -->|"reads and updates records"| node_domain_store
node_ws_controller -->|"dispatches frames"| node_proctor_service
node_proctor_service -->|"analyzes frames and risk"| node_ai_client
node_proctor_service -->|"stores events and risk"| node_domain_store
node_ai_api -->|"registers face route"| node_face_analysis
node_ai_client -.->|"calls AI endpoints"| node_ai_api
node_ai_api -.->|"grades theory"| node_ai_grading
node_ai_api -.->|"generates questions"| node_question_generation
node_ai_api -.->|"computes anomalies"| node_risk_model

click node_web_app "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/App.jsx"
click node_auth_ui "https://github.com/hasritha-r/aiproctor/tree/main/frontend/src/pages"
click node_camera "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/CameraSetup.jsx"
click node_exam_select "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/ExamList.jsx"
click node_exam_room "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/ExamRoom.jsx"
click node_monitor_hook "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/hooks/useProctoring.js"
click node_student_result "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/Result.jsx"
click node_frontend_api "https://github.com/hasritha-r/aiproctor/tree/main/frontend/src/api"
click node_admin_dashboard "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_student_review "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/StudentReview.jsx"
click node_admin_api "https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/api/adminApi.js"
click node_auth_controller "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/AuthController.java"
click node_auth_service "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AuthService.java"
click node_exam_controller "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/ExamController.java"
click node_exam_service "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ExamService.java"
click node_scoring "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ScoringService.java"
click node_admin_controller "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/AdminController.java"
click node_admin_service "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AdminService.java"
click node_proctor_service "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ProctoringService.java"
click node_ws_controller "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/websocket/ProctoringWebSocketController.java"
click node_ai_client "https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AiClientService.java"
click node_ai_api "https://github.com/hasritha-r/aiproctor/blob/main/ai-service/main.py"
click node_face_analysis "https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/face_analyzer.py"
click node_question_generation "https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/question_generator.py"
click node_domain_store "https://github.com/hasritha-r/aiproctor/tree/main/backend/src/main/java/com/proctai/repository"
click node_ai_grading "https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/grader.py"
click node_risk_model "https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/anomaly_model.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_web_app,node_auth_ui,node_camera,node_exam_select,node_exam_room,node_monitor_hook,node_student_result,node_frontend_api toneBlue
class node_admin_dashboard,node_student_review,node_admin_api,node_admin_controller,node_admin_service toneAmber
class node_auth_controller,node_auth_service,node_exam_controller,node_exam_service,node_scoring toneMint
class node_proctor_service,node_ws_controller,node_ai_client,node_ai_api,node_face_analysis,node_question_generation,node_ai_grading,node_risk_model toneRose
class node_domain_store,node_student_actor,node_admin_actor toneIndigo
```

## Components

### Student experience

- [Web routes](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Registration and login](https://github.com/hasritha-r/aiproctor/tree/main/frontend/src/pages): `frontend/src/pages`
- [Camera check](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/CameraSetup.jsx): `frontend/src/pages/CameraSetup.jsx`
- [Exam selection](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/ExamList.jsx): `frontend/src/pages/ExamList.jsx`
- [Exam room](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/ExamRoom.jsx): `frontend/src/pages/ExamRoom.jsx`
- [Browser monitoring](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/hooks/useProctoring.js): `frontend/src/hooks/useProctoring.js`
- [Results](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/Result.jsx): `frontend/src/pages/Result.jsx`
- [Frontend API clients](https://github.com/hasritha-r/aiproctor/tree/main/frontend/src/api): `frontend/src/api`

### Admin review

- [Risk dashboard](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [Session review](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/pages/StudentReview.jsx): `frontend/src/pages/StudentReview.jsx`
- [Admin API client](https://github.com/hasritha-r/aiproctor/blob/main/frontend/src/api/adminApi.js): `frontend/src/api/adminApi.js`
- [Admin routes](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/AdminController.java): `backend/src/main/java/com/proctai/controller/AdminController.java`
- [Admin decisions](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AdminService.java): `backend/src/main/java/com/proctai/service/AdminService.java`

### Exam backend

- [Authentication routes](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/AuthController.java): `backend/src/main/java/com/proctai/controller/AuthController.java`
- [Account and tokens](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AuthService.java): `backend/src/main/java/com/proctai/service/AuthService.java`
- [Exam routes](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/controller/ExamController.java): `backend/src/main/java/com/proctai/controller/ExamController.java`
- [Exam sessions](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ExamService.java): `backend/src/main/java/com/proctai/service/ExamService.java`
- [Scoring and submission](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ScoringService.java): `backend/src/main/java/com/proctai/service/ScoringService.java`

### Proctoring and AI

- [Event and risk processing](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/ProctoringService.java): `backend/src/main/java/com/proctai/service/ProctoringService.java`
- [WebSocket frame intake](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/websocket/ProctoringWebSocketController.java): `backend/src/main/java/com/proctai/websocket/ProctoringWebSocketController.java`
- [AI service client](https://github.com/hasritha-r/aiproctor/blob/main/backend/src/main/java/com/proctai/service/AiClientService.java): `backend/src/main/java/com/proctai/service/AiClientService.java`
- [AI endpoints](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/main.py): `ai-service/main.py`
- [Face analysis](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/face_analyzer.py): `ai-service/models/face_analyzer.py`
- [Question generation](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/question_generator.py): `ai-service/models/question_generator.py`
- [Theory grading](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/grader.py): `ai-service/models/grader.py`
- [Risk scoring](https://github.com/hasritha-r/aiproctor/blob/main/ai-service/models/anomaly_model.py): `ai-service/models/anomaly_model.py`

### Domain storage

- [Exam and user records](https://github.com/hasritha-r/aiproctor/tree/main/backend/src/main/java/com/proctai/repository): `backend/src/main/java/com/proctai/repository`

### Other components

- **Student**
- **Administrator**

## Connections

- Student → Registration and login: registers or logs in
- Registration and login → Camera check: continues to
- Camera check → Exam selection: continues to
- Exam selection → Exam room: starts exam
- Exam room → Results: submits answers
- Web routes → Registration and login: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Camera check: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Exam selection: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Exam room: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Results: routes to (evidence: `frontend/src/App.jsx`)
- Exam room → Browser monitoring: monitors session
- Browser monitoring → Frontend API clients: logs behavior (evidence: `frontend/src/hooks/useProctoring.js`)
- Administrator → Risk dashboard: reviews sessions
- Risk dashboard → Session review: opens review
- Session review → Admin API client: loads events and submits verdict (evidence: `frontend/src/pages/StudentReview.jsx`)
- Authentication routes → Account and tokens: delegates (evidence: `backend/src/main/java/com/proctai/controller/AuthController.java`)
- Account and tokens → Exam and user records: reads and saves users (evidence: `backend/src/main/java/com/proctai/service/AuthService.java`)
- Exam routes → Exam sessions: delegates exam actions (evidence: `backend/src/main/java/com/proctai/controller/ExamController.java`)
- Exam routes → Scoring and submission: submits answers (evidence: `backend/src/main/java/com/proctai/controller/ExamController.java`)
- Scoring and submission → Exam and user records: reads and saves results (evidence: `backend/src/main/java/com/proctai/service/ScoringService.java`)
- Scoring and submission → AI service client: grades theory (evidence: `backend/src/main/java/com/proctai/service/ScoringService.java`)
- Admin routes → Admin decisions: delegates (evidence: `backend/src/main/java/com/proctai/controller/AdminController.java`)
- Admin decisions → Exam and user records: reads and updates records (evidence: `backend/src/main/java/com/proctai/service/AdminService.java`)
- WebSocket frame intake → Event and risk processing: dispatches frames (evidence: `backend/src/main/java/com/proctai/websocket/ProctoringWebSocketController.java`)
- Event and risk processing → AI service client: analyzes frames and risk (evidence: `backend/src/main/java/com/proctai/service/ProctoringService.java`)
- Event and risk processing → Exam and user records: stores events and risk (evidence: `backend/src/main/java/com/proctai/service/ProctoringService.java`)
- AI endpoints → Face analysis: registers face route (evidence: `ai-service/main.py`)
- AI service client → AI endpoints: calls AI endpoints
- AI endpoints → Theory grading: grades theory
- AI endpoints → Question generation: generates questions
- AI endpoints → Risk scoring: computes anomalies
