# aalaswad275-byte/bloom-adapt-engine architecture

> Architecture diagram of the GitHub repository aalaswad275-byte/bloom-adapt-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aalaswad275-byte/bloom-adapt-engine
- Repository: https://github.com/aalaswad275-byte/bloom-adapt-engine

## Overview

AdaptiveMind is an assessment and learning platform: instructors manage classes and author/share assessments; students take assessments and review outcomes; administrators oversee institutions and performance. The frontend is routed through a React/Convex application, with Convex providing backend functions and persisted state. Adaptive assessment logic and webcam proctoring are distinct runtime subsystems. The graph emphasizes documented routes and sampled imports; links from unsampled pages to backend functions are omitted rather than inferred.

Main entry points: [`src/main.tsx`](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/main.tsx) (App routing), [`src/hooks/useExamMonitor.ts`](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/hooks/useExamMonitor.ts) (Exam monitoring hook), [`src/lib/monitoring/yoloClient.ts`](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/yoloClient.ts) (YOLO client), [`src/pages/Auth.tsx`](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/Auth.tsx) (Sign-in)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Assessment experience"]
  node_app["App routing<br/>[main.tsx]"]
  node_auth["Sign-in<br/>[Auth.tsx]"]
  node_instructor_portal["Instructor portal"]
  node_authoring["Assessment authoring"]
  node_question_editors["Question editors"]
  node_shared_questions["Shared questions"]
  node_assessment_details["Assessment details"]
  node_taking["Assessment taking<br/>[TakeAssessment.tsx]"]
  node_exam["Exam session<br/>[Exam.tsx]"]
  node_results["Student results"]
end

subgraph group_backend["Backend and identity"]
  node_convex["Convex backend"]
  node_schema[("Application data<br/>[schema.ts]")]
  node_users["User functions<br/>[users.ts]"]
  node_auth_hook["Auth hook<br/>[use-auth.ts]"]
end

subgraph group_intelligence["Adaptive and monitoring"]
  node_irt["Adaptive IRT<br/>[engine.ts]"]
  node_monitor_hook["Exam monitoring hook<br/>[useExamMonitor.ts]"]
  node_monitor_engine["Violation engine<br/>[engine.ts]"]
  node_browser_detector["Browser detector<br/>[browserDetector.ts]"]
  node_yolo_client["YOLO client<br/>[yoloClient.ts]"]
  node_yolo_service["YOLO service<br/>[app.py]"]
end

subgraph group_oversight["Administration"]
  node_admin["Admin console<br/>[AdminDashboard.tsx]"]
  node_admin_analytics["Admin analytics<br/>[Analytics.tsx]"]
  node_class_report["Class performance"]
end

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

node_student -->|"opens"| node_app
node_instructor -->|"opens"| node_app
node_app -.->|"routes"| node_auth
node_app -->|"routes"| node_exam
node_app -->|"routes"| node_instructor_portal
node_app -->|"routes"| node_class_report
node_auth -->|"uses"| node_auth_hook
node_auth_hook -->|"queries"| node_users
node_authoring -->|"renders"| node_question_editors
node_assessment_details -->|"imports"| node_irt
node_monitor_hook -->|"uses"| node_browser_detector
node_monitor_hook -->|"uses"| node_yolo_client
node_monitor_hook -.->|"uses"| node_monitor_engine
node_yolo_client -.->|"sends detections"| node_yolo_service
node_yolo_client -.->|"falls back"| node_browser_detector
node_convex -.->|"defines data"| node_schema
node_admin -.->|"offers"| node_admin_analytics

click node_app "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/main.tsx"
click node_auth "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/Auth.tsx"
click node_instructor_portal "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/InstructorPortal.tsx"
click node_authoring "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/InstructorAssessments.tsx"
click node_question_editors "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/components/DragDropQuestionEditor.tsx"
click node_shared_questions "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/SharedQuestions.tsx"
click node_assessment_details "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/AssessmentDetails.tsx"
click node_taking "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/TakeAssessment.tsx"
click node_exam "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/Exam.tsx"
click node_results "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/AssessmentResults.tsx"
click node_convex "https://github.com/aalaswad275-byte/bloom-adapt-engine/tree/main/src/convex"
click node_schema "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/convex/schema.ts"
click node_users "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/convex/users.ts"
click node_auth_hook "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/hooks/use-auth.ts"
click node_irt "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/irt/engine.ts"
click node_monitor_hook "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/hooks/useExamMonitor.ts"
click node_monitor_engine "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/engine.ts"
click node_browser_detector "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/browserDetector.ts"
click node_yolo_client "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/yoloClient.ts"
click node_yolo_service "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/monitoring-service/app.py"
click node_admin "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/admin/AdminDashboard.tsx"
click node_admin_analytics "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/admin/Analytics.tsx"
click node_class_report "https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/ClassPerformanceReport.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_auth,node_instructor_portal,node_authoring,node_question_editors,node_shared_questions,node_assessment_details,node_taking,node_exam,node_results toneBlue
class node_convex,node_schema,node_users,node_auth_hook toneAmber
class node_irt,node_monitor_hook,node_monitor_engine,node_browser_detector,node_yolo_client,node_yolo_service toneMint
class node_admin,node_admin_analytics,node_class_report toneRose
class node_student,node_instructor toneIndigo
```

## Components

### Assessment experience

- [App routing](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/main.tsx): `src/main.tsx`
- [Sign-in](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/Auth.tsx): `src/pages/Auth.tsx`
- [Instructor portal](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/InstructorPortal.tsx): `src/pages/InstructorPortal.tsx`
- [Assessment authoring](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/InstructorAssessments.tsx): `src/pages/InstructorAssessments.tsx`
- [Question editors](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/components/DragDropQuestionEditor.tsx): `src/components/DragDropQuestionEditor.tsx`
- [Shared questions](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/SharedQuestions.tsx): `src/pages/SharedQuestions.tsx`
- [Assessment details](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/AssessmentDetails.tsx): `src/pages/AssessmentDetails.tsx`
- [Assessment taking](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/TakeAssessment.tsx): `src/pages/TakeAssessment.tsx`
- [Exam session](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/Exam.tsx): `src/pages/Exam.tsx`
- [Student results](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/AssessmentResults.tsx): `src/pages/AssessmentResults.tsx`

### Backend and identity

- [Convex backend](https://github.com/aalaswad275-byte/bloom-adapt-engine/tree/main/src/convex): `src/convex`
- [Application data](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/convex/schema.ts): `src/convex/schema.ts`
- [User functions](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/convex/users.ts): `src/convex/users.ts`
- [Auth hook](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/hooks/use-auth.ts): `src/hooks/use-auth.ts`

### Adaptive and monitoring

- [Adaptive IRT](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/irt/engine.ts): `src/lib/irt/engine.ts`
- [Exam monitoring hook](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/hooks/useExamMonitor.ts): `src/hooks/useExamMonitor.ts`
- [Violation engine](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/engine.ts): `src/lib/monitoring/engine.ts`
- [Browser detector](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/browserDetector.ts): `src/lib/monitoring/browserDetector.ts`
- [YOLO client](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/lib/monitoring/yoloClient.ts): `src/lib/monitoring/yoloClient.ts`
- [YOLO service](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/monitoring-service/app.py): `monitoring-service/app.py`

### Administration

- [Admin console](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/admin/AdminDashboard.tsx): `src/pages/admin/AdminDashboard.tsx`
- [Admin analytics](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/admin/Analytics.tsx): `src/pages/admin/Analytics.tsx`
- [Class performance](https://github.com/aalaswad275-byte/bloom-adapt-engine/blob/main/src/pages/ClassPerformanceReport.tsx): `src/pages/ClassPerformanceReport.tsx`

### Other components

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

## Connections

- Student → App routing: opens (evidence: `src/main.tsx`)
- Instructor → App routing: opens (evidence: `src/main.tsx`)
- App routing → Sign-in: routes (evidence: `src/main.tsx`)
- App routing → Exam session: routes (evidence: `src/main.tsx`)
- App routing → Instructor portal: routes (evidence: `src/main.tsx`)
- App routing → Class performance: routes (evidence: `src/main.tsx`)
- Sign-in → Auth hook: uses (evidence: `src/pages/Auth.tsx`)
- Auth hook → User functions: queries (evidence: `src/hooks/use-auth.ts`)
- Assessment authoring → Question editors: renders (evidence: `src/pages/InstructorAssessments.tsx`)
- Assessment details → Adaptive IRT: imports (evidence: `src/pages/AssessmentDetails.tsx`)
- Exam monitoring hook → Browser detector: uses (evidence: `src/hooks/useExamMonitor.ts`)
- Exam monitoring hook → YOLO client: uses (evidence: `src/hooks/useExamMonitor.ts`)
- Exam monitoring hook → Violation engine: uses
- YOLO client → YOLO service: sends detections
- YOLO client → Browser detector: falls back
- Convex backend → Application data: defines data
- Admin console → Admin analytics: offers
