# ciannnnnn/hackathon_2026 architecture

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

## Overview

EduPulse AI is a role-based student-support platform. Teachers record dated academic snapshots; Laravel assesses support needs, persists results, and serves teacher analysis and student dashboards. Administrators provision accounts, while students review progress and study plans. Laravel is the public application and coordinates MySQL and the private ML/RAG services. The README also describes Gemini tutoring, PDF materials, and quizzes, but those implementations are not present in the supplied tree; those branches are shown as documented integrations. Some internal links rely on the SOURCE INDEX or README rather than inspected implementation excerpts.

Main entry points: [`web/routes/web.php`](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/routes/web.php) (Web routes), [`web/app/Services/DashboardDataService.php`](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/DashboardDataService.php) (Dashboard data), [`web/app/Services/AccountProvisioningService.php`](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/AccountProvisioningService.php) (Account provisioning), [`web/app/Models/StudentPerformance.php`](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/StudentPerformance.php) (Performance snapshots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Laravel application"]
  node_routes["Web routes<br/>[web.php]"]
  node_teacherboard["Teacher dashboard"]
  node_studentboard["Student dashboard"]
  node_teachercontroller["Teacher student views"]
  node_mysql[("MySQL database")]
end

subgraph group_academic["Academic support"]
  node_studentmodel["Student records<br/>[Student.php]"]
  node_performance["Performance snapshots"]
  node_analysis["Support analysis"]
  node_assessment["Support assessment"]
  node_teacherroster["Teacher student analysis"]
  node_perfcontroller["Performance recording"]
  node_dashdata["Dashboard data"]
end

subgraph group_identity["Accounts and access"]
  node_auth["Session authentication"]
  node_registration["Student registration"]
  node_accounts["Account provisioning"]
  node_adminusers["User administration"]
  node_roles["Role authorization"]
  node_users["User accounts<br/>[User.php]"]
end

subgraph group_ml["ML service"]
  node_mlclient["ML client"]
  node_mlapi["Prediction API<br/>[app.py]"]
  node_predict["Classifier inference<br/>[prediction.py]"]
  node_features["Feature preparation<br/>[features.py]"]
end

subgraph group_learning["Learning integrations"]
  node_rag["PDF retrieval service"]
  node_gemini["Gemini AI"]
  node_materials["Teacher learning materials"]
  node_tutor["Grounded AI tutor"]
  node_quiz["Generated quizzes"]
  node_studyplan["Personalized study plans"]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_admin(("Administrator"))

node_teacher -->|"uses"| node_routes
node_student -->|"uses"| node_routes
node_admin -->|"uses"| node_routes
node_routes -->|"routes to"| node_auth
node_routes -->|"routes to"| node_registration
node_routes -->|"routes to"| node_adminusers
node_routes -->|"routes to"| node_perfcontroller
node_routes -->|"routes to"| node_teacherboard
node_routes -->|"routes to"| node_studentboard
node_routes -->|"routes to"| node_teachercontroller
node_registration -->|"creates account"| node_accounts
node_adminusers -->|"creates account"| node_accounts
node_accounts -->|"provisions"| node_users
node_auth -.->|"authenticates"| node_users
node_routes -->|"applies role checks"| node_roles
node_adminusers -->|"queries and updates"| node_users
node_perfcontroller -->|"upserts snapshot"| node_performance
node_perfcontroller -->|"assesses snapshot"| node_assessment
node_assessment -->|"requests prediction"| node_mlclient
node_assessment -->|"stores assessment"| node_analysis
node_mlclient -.->|"calls privately"| node_mlapi
node_mlapi -->|"dispatches prediction"| node_predict
node_predict -->|"uses features"| node_features
node_teachercontroller -->|"loads analysis"| node_teacherroster
node_teacherroster -->|"queries students"| node_studentmodel
node_teacherroster -->|"loads snapshots"| node_performance
node_teacherboard -->|"loads dashboard data"| node_dashdata
node_studentboard -->|"loads dashboard data"| node_dashdata
node_dashdata -->|"queries records"| node_studentmodel
node_dashdata -->|"aggregates snapshots"| node_performance
node_dashdata -->|"loads active plan"| node_studyplan
node_accounts -.->|"persists accounts"| node_mysql
node_performance -.->|"persists snapshots"| node_mysql
node_materials -.->|"submitted for extraction"| node_rag
node_rag -.->|"supplies retrieval context"| node_tutor
node_gemini -.->|"grounds tutor responses"| node_tutor
node_gemini -.->|"generates quizzes"| node_quiz
node_gemini -.->|"supports plans"| node_studyplan

click node_routes "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/routes/web.php"
click node_auth "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/Auth/AuthenticatedSessionController.php"
click node_registration "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/Auth/RegisteredStudentController.php"
click node_accounts "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/AccountProvisioningService.php"
click node_adminusers "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/AdminUserController.php"
click node_roles "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Middleware/EnsureUserHasRole.php"
click node_users "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/User.php"
click node_studentmodel "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/Student.php"
click node_performance "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/StudentPerformance.php"
click node_analysis "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/StudentSupportAnalysis.php"
click node_assessment "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/AcademicSupportAssessmentService.php"
click node_teacherroster "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/TeacherStudentService.php"
click node_perfcontroller "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/StudentPerformanceController.php"
click node_dashdata "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/DashboardDataService.php"
click node_teacherboard "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/TeacherDashboardController.php"
click node_studentboard "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/StudentDashboardController.php"
click node_teachercontroller "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/TeacherStudentController.php"
click node_mlclient "https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/MachineLearningService.php"
click node_mlapi "https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/app.py"
click node_predict "https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/prediction.py"
click node_features "https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/features.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_routes,node_teacherboard,node_studentboard,node_teachercontroller,node_mysql toneBlue
class node_studentmodel,node_performance,node_analysis,node_assessment,node_teacherroster,node_perfcontroller,node_dashdata toneAmber
class node_auth,node_registration,node_accounts,node_adminusers,node_roles,node_users toneMint
class node_mlclient,node_mlapi,node_predict,node_features toneRose
class node_rag,node_gemini,node_materials,node_tutor,node_quiz,node_studyplan,node_teacher,node_student,node_admin toneIndigo
```

## Components

### Laravel application

- [Web routes](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/routes/web.php): `web/routes/web.php`
- [Teacher dashboard](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/TeacherDashboardController.php): `web/app/Http/Controllers/TeacherDashboardController.php`
- [Student dashboard](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/StudentDashboardController.php): `web/app/Http/Controllers/StudentDashboardController.php`
- [Teacher student views](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/TeacherStudentController.php): `web/app/Http/Controllers/TeacherStudentController.php`
- **MySQL database**

### Academic support

- [Student records](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/Student.php): `web/app/Models/Student.php`
- [Performance snapshots](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/StudentPerformance.php): `web/app/Models/StudentPerformance.php`
- [Support analysis](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/StudentSupportAnalysis.php): `web/app/Models/StudentSupportAnalysis.php`
- [Support assessment](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/AcademicSupportAssessmentService.php): `web/app/Services/AcademicSupportAssessmentService.php`
- [Teacher student analysis](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/TeacherStudentService.php): `web/app/Services/TeacherStudentService.php`
- [Performance recording](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/StudentPerformanceController.php): `web/app/Http/Controllers/StudentPerformanceController.php`
- [Dashboard data](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/DashboardDataService.php): `web/app/Services/DashboardDataService.php`

### Accounts and access

- [Session authentication](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/Auth/AuthenticatedSessionController.php): `web/app/Http/Controllers/Auth/AuthenticatedSessionController.php`
- [Student registration](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/Auth/RegisteredStudentController.php): `web/app/Http/Controllers/Auth/RegisteredStudentController.php`
- [Account provisioning](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/AccountProvisioningService.php): `web/app/Services/AccountProvisioningService.php`
- [User administration](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Controllers/AdminUserController.php): `web/app/Http/Controllers/AdminUserController.php`
- [Role authorization](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Http/Middleware/EnsureUserHasRole.php): `web/app/Http/Middleware/EnsureUserHasRole.php`
- [User accounts](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Models/User.php): `web/app/Models/User.php`

### ML service

- [ML client](https://github.com/ciannnnnn/hackathon_2026/blob/main/web/app/Services/MachineLearningService.php): `web/app/Services/MachineLearningService.php`
- [Prediction API](https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/app.py): `ml-service/app.py`
- [Classifier inference](https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/prediction.py): `ml-service/prediction.py`
- [Feature preparation](https://github.com/ciannnnnn/hackathon_2026/blob/main/ml-service/features.py): `ml-service/features.py`

### Learning integrations

- **PDF retrieval service**
- **Gemini AI**
- **Teacher learning materials**
- **Grounded AI tutor**
- **Generated quizzes**
- **Personalized study plans**

### Other components

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

## Connections

- Teacher → Web routes: uses (evidence: `web/routes/web.php`)
- Student → Web routes: uses (evidence: `web/routes/web.php`)
- Administrator → Web routes: uses (evidence: `web/routes/web.php`)
- Web routes → Session authentication: routes to (evidence: `web/routes/web.php`)
- Web routes → Student registration: routes to (evidence: `web/routes/web.php`)
- Web routes → User administration: routes to (evidence: `web/routes/web.php`)
- Web routes → Performance recording: routes to (evidence: `web/routes/web.php`)
- Web routes → Teacher dashboard: routes to (evidence: `web/routes/web.php`)
- Web routes → Student dashboard: routes to (evidence: `web/routes/web.php`)
- Web routes → Teacher student views: routes to (evidence: `web/routes/web.php`)
- Student registration → Account provisioning: creates account (evidence: `web/app/Http/Controllers/Auth/RegisteredStudentController.php`)
- User administration → Account provisioning: creates account (evidence: `web/app/Http/Controllers/AdminUserController.php`)
- Account provisioning → User accounts: provisions (evidence: `web/app/Services/AccountProvisioningService.php`)
- Session authentication → User accounts: authenticates
- Web routes → Role authorization: applies role checks
- User administration → User accounts: queries and updates (evidence: `web/app/Http/Controllers/AdminUserController.php`)
- Performance recording → Performance snapshots: upserts snapshot (evidence: `web/app/Http/Controllers/StudentPerformanceController.php`)
- Performance recording → Support assessment: assesses snapshot (evidence: `web/app/Http/Controllers/StudentPerformanceController.php`)
- Support assessment → ML client: requests prediction (evidence: `web/app/Services/AcademicSupportAssessmentService.php`)
- Support assessment → Support analysis: stores assessment (evidence: `web/app/Services/AcademicSupportAssessmentService.php`)
- ML client → Prediction API: calls privately (evidence: `README.md`)
- Prediction API → Classifier inference: dispatches prediction (evidence: `ml-service/app.py`)
- Classifier inference → Feature preparation: uses features (evidence: `ml-service/prediction.py`)
- Teacher student views → Teacher student analysis: loads analysis (evidence: `web/app/Http/Controllers/TeacherStudentController.php`)
- Teacher student analysis → Student records: queries students (evidence: `web/app/Services/TeacherStudentService.php`)
- Teacher student analysis → Performance snapshots: loads snapshots (evidence: `web/app/Services/TeacherStudentService.php`)
- Teacher dashboard → Dashboard data: loads dashboard data (evidence: `web/app/Http/Controllers/TeacherDashboardController.php`)
- Student dashboard → Dashboard data: loads dashboard data (evidence: `web/app/Http/Controllers/StudentDashboardController.php`)
- Dashboard data → Student records: queries records (evidence: `web/app/Services/DashboardDataService.php`)
- Dashboard data → Performance snapshots: aggregates snapshots (evidence: `web/app/Services/DashboardDataService.php`)
- Dashboard data → Personalized study plans: loads active plan (evidence: `web/app/Services/DashboardDataService.php`)
- Account provisioning → MySQL database: persists accounts (evidence: `README.md`)
- Performance snapshots → MySQL database: persists snapshots (evidence: `README.md`)
- Teacher learning materials → PDF retrieval service: submitted for extraction (evidence: `README.md`)
- PDF retrieval service → Grounded AI tutor: supplies retrieval context (evidence: `README.md`)
- Gemini AI → Grounded AI tutor: grounds tutor responses (evidence: `README.md`)
- Gemini AI → Generated quizzes: generates quizzes (evidence: `README.md`)
- Gemini AI → Personalized study plans: supports plans (evidence: `README.md`)
