# shirohafomi/spsh architecture

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

- Interactive diagram: https://gitdiagram.com/shirohafomi/spsh
- Repository: https://github.com/shirohafomi/spsh

## Overview

Student Performance & Study Habits is a role-based student analytics and study-support application. Users authenticate in the React/Vite SPA, then use student, teacher, or administrator capabilities that call an Express API backed by MySQL; prediction and simulation capabilities are served by a unified ML service. Major documented branches include schema-adaptive dashboards, ML monitoring, goals, assignments, sessions, journals, notifications, and saved what-if scenarios. The tree, README, and excerpts support the API and sampled service relationships; unsampled integrations are shown only as unverified where noted.

Main entry points: [`src/routes/apiRoutes.js`](https://github.com/shirohafomi/spsh/blob/main/src/routes/apiRoutes.js) (API routing), [`src/config/db.js`](https://github.com/shirohafomi/spsh/blob/main/src/config/db.js) (MySQL database), [`src/controllers/studentController.js`](https://github.com/shirohafomi/spsh/blob/main/src/controllers/studentController.js) (Student handlers), [`src/services/mlService.js`](https://github.com/shirohafomi/spsh/blob/main/src/services/mlService.js) (Prediction and simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_spa["React SPA routes<br/>[App.jsx]"]
  node_auth_ui["Session UI<br/>[useAuth.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_api_server["Express application<br/>[app.js]"]
  node_routing["API routing<br/>[apiRoutes.js]"]
  node_auth_controller["Authentication handlers<br/>[apiController.js]"]
  node_student_controller["Student handlers"]
  node_admin_controller["Admin operations<br/>[adminController.js]"]
  node_auth_service["User and role service<br/>[authService.js]"]
  node_auth_sessions["Refresh sessions"]
end

subgraph group_analytics["Student analytics"]
  node_student_data["Student records and analytics<br/>[studentService.js]"]
  node_schema["Dataset schema mapping<br/>[schemaMap.js]"]
  node_ai_counsel["AI counsel"]
  node_ml_monitor["ML drift monitoring<br/>[mlDriftService.js]"]
end

subgraph group_study["Study support"]
  node_assignments["Assignments"]
  node_goals["Goals and check-ins"]
  node_sessions["Study sessions"]
  node_assignment_service["Assignment service"]
  node_goal_service["Goal service"]
  node_session_service["Session service"]
  node_notifications["Notification center"]
  node_journal["Learning journal"]
end

subgraph group_platform["Persistence and ML"]
  node_ml_service["Prediction and simulation<br/>[mlService.js]"]
  node_prediction_history["Prediction history"]
  node_ml_runtime["Python prediction runtime<br/>[inference.py]"]
  node_database[("MySQL database<br/>[db.js]")]
end

node_users(("Students and staff"))

node_users -->|"uses"| node_spa
node_spa -->|"provides routes"| node_auth_ui
node_auth_ui -->|"requests session"| node_api_client
node_spa -.->|"calls API"| node_api_client
node_api_client -->|"sends requests"| node_routing
node_api_server -->|"mounts routes"| node_routing
node_routing -->|"routes auth"| node_auth_controller
node_routing -->|"routes student actions"| node_student_controller
node_routing -->|"routes admin actions"| node_admin_controller
node_routing -->|"routes assignments"| node_assignments
node_routing -->|"routes goals"| node_goals
node_routing -->|"routes sessions"| node_sessions
node_auth_controller -->|"authenticates users"| node_auth_service
node_auth_service -->|"manages sessions"| node_auth_sessions
node_student_controller -->|"loads student data"| node_student_data
node_student_controller -->|"requests predictions"| node_ml_service
node_student_controller -->|"records predictions"| node_prediction_history
node_student_controller -->|"requests counsel"| node_ai_counsel
node_admin_controller -->|"queries risk data"| node_student_data
node_admin_controller -->|"checks ML health"| node_ml_service
node_ml_service -->|"loads student profile"| node_student_data
node_ml_service -.->|"invokes inference"| node_ml_runtime
node_student_data -->|"adapts columns"| node_schema
node_student_data -->|"reads and writes"| node_database
node_auth_service -->|"reads and writes"| node_database
node_auth_sessions -->|"stores sessions"| node_database
node_assignments -->|"manages coursework"| node_assignment_service
node_assignment_service -.->|"persists assignments"| node_database
node_goals -->|"manages progress"| node_goal_service
node_goal_service -->|"persists goals"| node_database
node_sessions -->|"manages timers"| node_session_service
node_session_service -->|"persists sessions"| node_database
node_users -.->|"writes reflections"| node_journal
node_users -.->|"receives alerts"| node_notifications
node_ml_service -.->|"tracks outcomes"| node_prediction_history
node_users -.->|"views model health"| node_ml_monitor

click node_spa "https://github.com/shirohafomi/spsh/blob/main/frontend/src/App.jsx"
click node_auth_ui "https://github.com/shirohafomi/spsh/blob/main/frontend/src/hooks/useAuth.jsx"
click node_api_client "https://github.com/shirohafomi/spsh/blob/main/frontend/src/api.js"
click node_api_server "https://github.com/shirohafomi/spsh/blob/main/src/app.js"
click node_routing "https://github.com/shirohafomi/spsh/blob/main/src/routes/apiRoutes.js"
click node_auth_controller "https://github.com/shirohafomi/spsh/blob/main/src/controllers/apiController.js"
click node_student_controller "https://github.com/shirohafomi/spsh/blob/main/src/controllers/studentController.js"
click node_admin_controller "https://github.com/shirohafomi/spsh/blob/main/src/controllers/adminController.js"
click node_assignments "https://github.com/shirohafomi/spsh/blob/main/src/controllers/assignmentController.js"
click node_goals "https://github.com/shirohafomi/spsh/blob/main/src/controllers/studyGoalController.js"
click node_sessions "https://github.com/shirohafomi/spsh/blob/main/src/controllers/studySessionController.js"
click node_student_data "https://github.com/shirohafomi/spsh/blob/main/src/services/studentService.js"
click node_schema "https://github.com/shirohafomi/spsh/blob/main/src/utils/schemaMap.js"
click node_ml_service "https://github.com/shirohafomi/spsh/blob/main/src/services/mlService.js"
click node_prediction_history "https://github.com/shirohafomi/spsh/blob/main/src/services/predictionHistoryService.js"
click node_ai_counsel "https://github.com/shirohafomi/spsh/blob/main/src/services/aiCounselService.js"
click node_auth_service "https://github.com/shirohafomi/spsh/blob/main/src/services/authService.js"
click node_auth_sessions "https://github.com/shirohafomi/spsh/blob/main/src/services/authSessionService.js"
click node_assignment_service "https://github.com/shirohafomi/spsh/blob/main/src/services/assignmentService.js"
click node_goal_service "https://github.com/shirohafomi/spsh/blob/main/src/services/studyGoalService.js"
click node_session_service "https://github.com/shirohafomi/spsh/blob/main/src/services/studySessionService.js"
click node_notifications "https://github.com/shirohafomi/spsh/blob/main/src/services/notificationService.js"
click node_journal "https://github.com/shirohafomi/spsh/blob/main/src/controllers/learningJournalController.js"
click node_ml_monitor "https://github.com/shirohafomi/spsh/blob/main/src/services/mlDriftService.js"
click node_ml_runtime "https://github.com/shirohafomi/spsh/blob/main/ml/inference.py"
click node_database "https://github.com/shirohafomi/spsh/blob/main/src/config/db.js"

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_spa,node_auth_ui,node_api_client toneBlue
class node_api_server,node_routing,node_auth_controller,node_student_controller,node_admin_controller,node_auth_service,node_auth_sessions toneAmber
class node_student_data,node_schema,node_ai_counsel,node_ml_monitor toneMint
class node_assignments,node_goals,node_sessions,node_assignment_service,node_goal_service,node_session_service,node_notifications,node_journal toneRose
class node_ml_service,node_prediction_history,node_ml_runtime,node_database,node_users toneIndigo
```

## Components

### Web application

- [React SPA routes](https://github.com/shirohafomi/spsh/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session UI](https://github.com/shirohafomi/spsh/blob/main/frontend/src/hooks/useAuth.jsx): `frontend/src/hooks/useAuth.jsx`
- [API client](https://github.com/shirohafomi/spsh/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and access

- [Express application](https://github.com/shirohafomi/spsh/blob/main/src/app.js): `src/app.js`
- [API routing](https://github.com/shirohafomi/spsh/blob/main/src/routes/apiRoutes.js): `src/routes/apiRoutes.js`
- [Authentication handlers](https://github.com/shirohafomi/spsh/blob/main/src/controllers/apiController.js): `src/controllers/apiController.js`
- [Student handlers](https://github.com/shirohafomi/spsh/blob/main/src/controllers/studentController.js): `src/controllers/studentController.js`
- [Admin operations](https://github.com/shirohafomi/spsh/blob/main/src/controllers/adminController.js): `src/controllers/adminController.js`
- [User and role service](https://github.com/shirohafomi/spsh/blob/main/src/services/authService.js): `src/services/authService.js`
- [Refresh sessions](https://github.com/shirohafomi/spsh/blob/main/src/services/authSessionService.js): `src/services/authSessionService.js`

### Student analytics

- [Student records and analytics](https://github.com/shirohafomi/spsh/blob/main/src/services/studentService.js): `src/services/studentService.js`
- [Dataset schema mapping](https://github.com/shirohafomi/spsh/blob/main/src/utils/schemaMap.js): `src/utils/schemaMap.js`
- [AI counsel](https://github.com/shirohafomi/spsh/blob/main/src/services/aiCounselService.js): `src/services/aiCounselService.js`
- [ML drift monitoring](https://github.com/shirohafomi/spsh/blob/main/src/services/mlDriftService.js): `src/services/mlDriftService.js`

### Study support

- [Assignments](https://github.com/shirohafomi/spsh/blob/main/src/controllers/assignmentController.js): `src/controllers/assignmentController.js`
- [Goals and check-ins](https://github.com/shirohafomi/spsh/blob/main/src/controllers/studyGoalController.js): `src/controllers/studyGoalController.js`
- [Study sessions](https://github.com/shirohafomi/spsh/blob/main/src/controllers/studySessionController.js): `src/controllers/studySessionController.js`
- [Assignment service](https://github.com/shirohafomi/spsh/blob/main/src/services/assignmentService.js): `src/services/assignmentService.js`
- [Goal service](https://github.com/shirohafomi/spsh/blob/main/src/services/studyGoalService.js): `src/services/studyGoalService.js`
- [Session service](https://github.com/shirohafomi/spsh/blob/main/src/services/studySessionService.js): `src/services/studySessionService.js`
- [Notification center](https://github.com/shirohafomi/spsh/blob/main/src/services/notificationService.js): `src/services/notificationService.js`
- [Learning journal](https://github.com/shirohafomi/spsh/blob/main/src/controllers/learningJournalController.js): `src/controllers/learningJournalController.js`

### Persistence and ML

- [Prediction and simulation](https://github.com/shirohafomi/spsh/blob/main/src/services/mlService.js): `src/services/mlService.js`
- [Prediction history](https://github.com/shirohafomi/spsh/blob/main/src/services/predictionHistoryService.js): `src/services/predictionHistoryService.js`
- [Python prediction runtime](https://github.com/shirohafomi/spsh/blob/main/ml/inference.py): `ml/inference.py`
- [MySQL database](https://github.com/shirohafomi/spsh/blob/main/src/config/db.js): `src/config/db.js`

### Other components

- **Students and staff**

## Connections

- Students and staff → React SPA routes: uses (evidence: `README.md`)
- React SPA routes → Session UI: provides routes (evidence: `frontend/src/App.jsx`)
- Session UI → API client: requests session (evidence: `frontend/src/hooks/useAuth.jsx`)
- React SPA routes → API client: calls API
- API client → API routing: sends requests (evidence: `README.md`)
- Express application → API routing: mounts routes (evidence: `src/app.js`)
- API routing → Authentication handlers: routes auth (evidence: `src/routes/apiRoutes.js`)
- API routing → Student handlers: routes student actions (evidence: `src/routes/apiRoutes.js`)
- API routing → Admin operations: routes admin actions (evidence: `src/routes/apiRoutes.js`)
- API routing → Assignments: routes assignments (evidence: `src/routes/apiRoutes.js`)
- API routing → Goals and check-ins: routes goals (evidence: `src/routes/apiRoutes.js`)
- API routing → Study sessions: routes sessions (evidence: `src/routes/apiRoutes.js`)
- Authentication handlers → User and role service: authenticates users (evidence: `src/controllers/apiController.js`)
- User and role service → Refresh sessions: manages sessions (evidence: `src/services/authService.js`)
- Student handlers → Student records and analytics: loads student data (evidence: `src/controllers/studentController.js`)
- Student handlers → Prediction and simulation: requests predictions (evidence: `src/controllers/studentController.js`)
- Student handlers → Prediction history: records predictions (evidence: `src/controllers/studentController.js`)
- Student handlers → AI counsel: requests counsel (evidence: `src/controllers/studentController.js`)
- Admin operations → Student records and analytics: queries risk data (evidence: `src/controllers/adminController.js`)
- Admin operations → Prediction and simulation: checks ML health (evidence: `src/controllers/adminController.js`)
- Prediction and simulation → Student records and analytics: loads student profile (evidence: `src/services/mlService.js`)
- Prediction and simulation → Python prediction runtime: invokes inference
- Student records and analytics → Dataset schema mapping: adapts columns (evidence: `src/services/studentService.js`)
- Student records and analytics → MySQL database: reads and writes (evidence: `src/services/studentService.js`)
- User and role service → MySQL database: reads and writes (evidence: `src/services/authService.js`)
- Refresh sessions → MySQL database: stores sessions (evidence: `src/services/authSessionService.js`)
- Assignments → Assignment service: manages coursework (evidence: `src/controllers/assignmentController.js`)
- Assignment service → MySQL database: persists assignments
- Goals and check-ins → Goal service: manages progress (evidence: `src/controllers/studyGoalController.js`)
- Goal service → MySQL database: persists goals (evidence: `src/services/studyGoalService.js`)
- Study sessions → Session service: manages timers (evidence: `src/controllers/studySessionController.js`)
- Session service → MySQL database: persists sessions (evidence: `src/services/studySessionService.js`)
- Students and staff → Learning journal: writes reflections
- Students and staff → Notification center: receives alerts
- Prediction and simulation → Prediction history: tracks outcomes
- Students and staff → ML drift monitoring: views model health
