# hemachandhar-a/snuc_quickq architecture

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

- Interactive diagram: https://gitdiagram.com/hemachandhar-a/snuc_quickq
- Repository: https://github.com/hemachandhar-a/snuc_quickq

## Overview

Hostel Mess Hub is a role-based, real-time queue intelligence platform. Staff and simulated or optional video sensors provide operational inputs; the backend models queue state, wait forecasts, incidents, fairness and sustainability, then exposes REST analytics and live events. Students see queue, alerts and sustainability information; staff monitor and manage operations; administrators review forecasts, heatmaps, audits and KPIs. The README documents major capabilities not all shown in sampled source; those are represented at their documented subsystem paths. Some unsampled wiring is therefore left unasserted or dashed.

Main entry points: [`backend/src/index.js`](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/index.js) (HTTP and socket server), [`backend/src/socket/socketHandler.js`](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/socket/socketHandler.js) (Live event delivery), [`backend/src/services/intelligenceEngine.js`](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/intelligenceEngine.js) (Queue intelligence), [`frontend/src/router.jsx`](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/router.jsx) (Role routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Role-based web app"]
  node_student["Student views"]
  node_staffui["Staff console"]
  node_admin["Admin analytics"]
  node_login["Login and roles<br/>[LoginPage.jsx]"]
  node_authstate["Auth state<br/>[authStore.js]"]
  node_liveui["Live state<br/>[realtimeStore.js]"]
  node_restclient["REST client<br/>[client.js]"]
  node_socketclient["Socket client<br/>[socket.js]"]
  node_routing["Role routing<br/>[router.jsx]"]
end

subgraph group_api["Backend API"]
  node_server["HTTP and socket server<br/>[index.js]"]
  node_authapi["Authentication API<br/>[auth.js]"]
  node_systemapi["System API<br/>[system.js]"]
  node_staffapi["Staff operations API<br/>[staff.js]"]
  node_aiapi["AI endpoints<br/>[ai.js]"]
  node_analyticsapi["Analytics API<br/>[analytics.js]"]
end

subgraph group_ops["Queue operations"]
  node_engine["Queue intelligence"]
  node_sensors["Simulation sensors"]
  node_detection["Video detection"]
  node_pythonyolo["YOLO detector<br/>[yolo_detect.py]"]
  node_eventbus["Operational events<br/>[eventBus.js]"]
  node_socketserver["Live event delivery<br/>[socketHandler.js]"]
end

subgraph group_insight["Intelligence and analytics"]
  node_ml["Rule-based predictions<br/>[mlPlaceholder.js]"]
  node_sustain["Sustainability simulation"]
  node_analyticsstore[("In-memory analytics<br/>[analyticsStore.js]")]
end

subgraph group_persist["State and detection"]
  node_db[("SQLite state and feeds<br/>[index.js]")]
end

node_user(("Student, staff, admin"))

node_user -->|"opens app"| node_routing
node_routing -->|"routes to"| node_login
node_routing -->|"routes to"| node_student
node_routing -->|"routes to"| node_staffui
node_routing -->|"routes to"| node_admin
node_login -->|"sets credentials"| node_authstate
node_login -->|"calls login"| node_restclient
node_student -->|"requests data"| node_restclient
node_staffui -->|"requests operations"| node_restclient
node_admin -->|"requests analytics"| node_restclient
node_server -->|"mounts route"| node_authapi
node_server -->|"mounts route"| node_systemapi
node_server -->|"mounts route"| node_staffapi
node_server -->|"mounts route"| node_aiapi
node_server -->|"mounts route"| node_analyticsapi
node_server -->|"attaches handlers"| node_socketserver
node_server -->|"starts simulation"| node_sensors
node_server -->|"starts detection"| node_detection
node_staffapi -->|"manages incidents"| node_engine
node_staffapi -->|"reads and writes"| node_db
node_staffapi -->|"reads analytics"| node_analyticsstore
node_systemapi -->|"reads status"| node_engine
node_aiapi -->|"delegates predictions"| node_ml
node_analyticsapi -.->|"serves analytics"| node_analyticsstore
node_sensors -->|"updates queue"| node_engine
node_engine -->|"calculates waits"| node_ml
node_engine -->|"reads staff state"| node_db
node_engine -->|"emits events"| node_eventbus
node_sensors -->|"emits updates"| node_eventbus
node_detection -->|"publishes detections"| node_eventbus
node_detection -->|"runs detector"| node_pythonyolo
node_socketserver -->|"subscribes events"| node_eventbus
node_socketserver -->|"reads initial state"| node_engine
node_socketserver -->|"reads staff state"| node_db
node_socketserver -->|"computes initial wait"| node_ml
node_server -->|"records events"| node_analyticsstore
node_sensors -->|"uses sustainability logic"| node_sustain
node_restclient -.->|"HTTP requests"| node_server
node_socketclient -.->|"receives live events"| node_socketserver
node_socketserver -.->|"updates live state"| node_liveui
node_liveui -->|"supplies live data"| node_student
node_liveui -->|"supplies live data"| node_staffui

click node_student "https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Student"
click node_staffui "https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Staff"
click node_admin "https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Admin"
click node_login "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/pages/Login/LoginPage.jsx"
click node_authstate "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/store/authStore.js"
click node_liveui "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/store/realtimeStore.js"
click node_restclient "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/api/client.js"
click node_socketclient "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/api/socket.js"
click node_routing "https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/router.jsx"
click node_server "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/index.js"
click node_authapi "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/auth.js"
click node_systemapi "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/system.js"
click node_staffapi "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/staff.js"
click node_aiapi "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/ai.js"
click node_analyticsapi "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/analytics.js"
click node_engine "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/intelligenceEngine.js"
click node_sensors "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/simulatedSensors.js"
click node_detection "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/detectionService.js"
click node_pythonyolo "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/python/yolo_detect.py"
click node_eventbus "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/eventBus.js"
click node_socketserver "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/socket/socketHandler.js"
click node_ml "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/mlPlaceholder.js"
click node_sustain "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/sustainabilitySim.js"
click node_analyticsstore "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/store/analyticsStore.js"
click node_db "https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/db/index.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_student,node_staffui,node_admin,node_login,node_authstate,node_liveui,node_restclient,node_socketclient,node_routing toneBlue
class node_server,node_authapi,node_systemapi,node_staffapi,node_aiapi,node_analyticsapi toneAmber
class node_engine,node_sensors,node_detection,node_pythonyolo,node_eventbus,node_socketserver toneMint
class node_ml,node_sustain,node_analyticsstore toneRose
class node_db,node_user toneIndigo
```

## Components

### Role-based web app

- [Student views](https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Student): `frontend/src/pages/Student`
- [Staff console](https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Staff): `frontend/src/pages/Staff`
- [Admin analytics](https://github.com/hemachandhar-a/snuc_quickq/tree/main/frontend/src/pages/Admin): `frontend/src/pages/Admin`
- [Login and roles](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/pages/Login/LoginPage.jsx): `frontend/src/pages/Login/LoginPage.jsx`
- [Auth state](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`
- [Live state](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/store/realtimeStore.js): `frontend/src/store/realtimeStore.js`
- [REST client](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Socket client](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/api/socket.js): `frontend/src/api/socket.js`
- [Role routing](https://github.com/hemachandhar-a/snuc_quickq/blob/main/frontend/src/router.jsx): `frontend/src/router.jsx`

### Backend API

- [HTTP and socket server](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/index.js): `backend/src/index.js`
- [Authentication API](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [System API](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/system.js): `backend/src/routes/system.js`
- [Staff operations API](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/staff.js): `backend/src/routes/staff.js`
- [AI endpoints](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/ai.js): `backend/src/routes/ai.js`
- [Analytics API](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/routes/analytics.js): `backend/src/routes/analytics.js`

### Queue operations

- [Queue intelligence](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/intelligenceEngine.js): `backend/src/services/intelligenceEngine.js`
- [Simulation sensors](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/simulatedSensors.js): `backend/src/services/simulatedSensors.js`
- [Video detection](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/detectionService.js): `backend/src/services/detectionService.js`
- [YOLO detector](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/python/yolo_detect.py): `backend/python/yolo_detect.py`
- [Operational events](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/eventBus.js): `backend/src/services/eventBus.js`
- [Live event delivery](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/socket/socketHandler.js): `backend/src/socket/socketHandler.js`

### Intelligence and analytics

- [Rule-based predictions](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/mlPlaceholder.js): `backend/src/services/mlPlaceholder.js`
- [Sustainability simulation](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/services/sustainabilitySim.js): `backend/src/services/sustainabilitySim.js`
- [In-memory analytics](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/store/analyticsStore.js): `backend/src/store/analyticsStore.js`

### State and detection

- [SQLite state and feeds](https://github.com/hemachandhar-a/snuc_quickq/blob/main/backend/src/db/index.js): `backend/src/db/index.js`

### Other components

- **Student, staff, admin**

## Connections

- Student, staff, admin → Role routing: opens app (evidence: `frontend/src/router.jsx`)
- Role routing → Login and roles: routes to (evidence: `frontend/src/router.jsx`)
- Role routing → Student views: routes to (evidence: `frontend/src/router.jsx`)
- Role routing → Staff console: routes to (evidence: `frontend/src/router.jsx`)
- Role routing → Admin analytics: routes to (evidence: `frontend/src/router.jsx`)
- Login and roles → Auth state: sets credentials (evidence: `frontend/src/store/authStore.js`)
- Login and roles → REST client: calls login (evidence: `frontend/src/pages/Login/LoginPage.jsx`)
- Student views → REST client: requests data (evidence: `frontend/src/pages/Student/Home/StudentHome.jsx`)
- Staff console → REST client: requests operations (evidence: `frontend/src/pages/Staff/Dashboard/StaffDashboard.jsx`)
- Admin analytics → REST client: requests analytics (evidence: `frontend/src/pages/Admin/Overview/AdminOverview.jsx`)
- HTTP and socket server → Authentication API: mounts route (evidence: `backend/src/index.js`)
- HTTP and socket server → System API: mounts route (evidence: `backend/src/index.js`)
- HTTP and socket server → Staff operations API: mounts route (evidence: `backend/src/index.js`)
- HTTP and socket server → AI endpoints: mounts route (evidence: `backend/src/index.js`)
- HTTP and socket server → Analytics API: mounts route (evidence: `backend/src/index.js`)
- HTTP and socket server → Live event delivery: attaches handlers (evidence: `backend/src/index.js`)
- HTTP and socket server → Simulation sensors: starts simulation (evidence: `backend/src/index.js`)
- HTTP and socket server → Video detection: starts detection (evidence: `backend/src/index.js`)
- Staff operations API → Queue intelligence: manages incidents (evidence: `backend/src/routes/staff.js`)
- Staff operations API → SQLite state and feeds: reads and writes (evidence: `backend/src/routes/staff.js`)
- Staff operations API → In-memory analytics: reads analytics (evidence: `backend/src/routes/staff.js`)
- System API → Queue intelligence: reads status (evidence: `backend/src/routes/system.js`)
- AI endpoints → Rule-based predictions: delegates predictions (evidence: `backend/src/routes/ai.js`)
- Analytics API → In-memory analytics: serves analytics
- Simulation sensors → Queue intelligence: updates queue (evidence: `backend/src/services/simulatedSensors.js`)
- Queue intelligence → Rule-based predictions: calculates waits (evidence: `backend/src/services/intelligenceEngine.js`)
- Queue intelligence → SQLite state and feeds: reads staff state (evidence: `backend/src/services/intelligenceEngine.js`)
- Queue intelligence → Operational events: emits events (evidence: `backend/src/services/intelligenceEngine.js`)
- Simulation sensors → Operational events: emits updates (evidence: `backend/src/services/simulatedSensors.js`)
- Video detection → Operational events: publishes detections (evidence: `backend/src/services/detectionService.js`)
- Video detection → YOLO detector: runs detector (evidence: `README.md`)
- Live event delivery → Operational events: subscribes events (evidence: `backend/src/socket/socketHandler.js`)
- Live event delivery → Queue intelligence: reads initial state (evidence: `backend/src/socket/socketHandler.js`)
- Live event delivery → SQLite state and feeds: reads staff state (evidence: `backend/src/socket/socketHandler.js`)
- Live event delivery → Rule-based predictions: computes initial wait (evidence: `backend/src/socket/socketHandler.js`)
- HTTP and socket server → In-memory analytics: records events (evidence: `backend/src/index.js`)
- Simulation sensors → Sustainability simulation: uses sustainability logic (evidence: `backend/src/services/simulatedSensors.js`)
- REST client → HTTP and socket server: HTTP requests
- Socket client → Live event delivery: receives live events (evidence: `README.md`)
- Live event delivery → Live state: updates live state
- Live state → Student views: supplies live data (evidence: `frontend/src/pages/Student/Home/StudentHome.jsx`)
- Live state → Staff console: supplies live data (evidence: `frontend/src/pages/Staff/Dashboard/StaffDashboard.jsx`)
