# abdulqadir-b/smart-queue-system architecture

> Architecture diagram of the GitHub repository abdulqadir-b/smart-queue-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulqadir-b/smart-queue-system
- Repository: https://github.com/abdulqadir-b/smart-queue-system

## Overview

SQM lets customers find a service queue, join it and track a token; staff advance and complete service, while administrators manage queues and review analytics. The React app calls the Express API for these workflows, with MongoDB-backed records and Socket.io updates for connected clients. The graph preserves authentication, queue-state controls, and customer alerts as separate capabilities. Controller excerpts are partial, so uncertain controller-to-model wiring and unsampled frontend service calls are not expanded; documented but unsampled analytics and management routes are shown at their exact tree paths.

Main entry points: [`backend/index.js`](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/index.js) (Express server), [`frontend/src/App.js`](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/App.js) (React app), [`backend/models/index.js`](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/models/index.js) (Queue and token models), [`frontend/src/services/ApiService.js`](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/services/ApiService.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["React app<br/>[App.js]"]
  node_customer_view["Customer workflow<br/>[CustomerView.jsx]"]
  node_staff_view["Staff workflow<br/>[StaffView.jsx]"]
  node_admin_view["Admin workspace<br/>[AdminView.jsx]"]
  node_api_client["API client<br/>[ApiService.js]"]
  node_socket_client["Socket context<br/>[SocketContext.js]"]
  node_auto_notify["Turn alerts"]
end

subgraph group_api["API runtime"]
  node_server["Express server<br/>[index.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_queue_routes["Queue routes"]
  node_token_routes["Token routes<br/>[tokenRoutes.js]"]
  node_state_routes["Queue state routes"]
  node_analytics_routes["Analytics routes<br/>[analyticsRoutes.js]"]
end

subgraph group_domain["Queue domain"]
  node_auth_controller["Authentication<br/>[authController.js]"]
  node_queue_controller["Queue operations"]
  node_token_controller["Token operations<br/>[tokenController.js]"]
  node_state_controller["Pause and reset"]
  node_analytics_controller["Queue analytics"]
end

subgraph group_realtime["Realtime updates"]
  node_socket_service["Socket service<br/>[socketService.js]"]
end

subgraph group_state["Persistent state"]
  node_models["Queue and token models<br/>[index.js]"]
  node_mongo[("MongoDB")]
end

node_customer(("Customer"))
node_staff(("Staff"))
node_admin(("Administrator"))

node_customer -->|"uses"| node_app
node_staff -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes"| node_customer_view
node_app -->|"routes"| node_staff_view
node_app -->|"routes"| node_admin_view
node_customer_view -->|"requests"| node_api_client
node_staff_view -->|"requests"| node_api_client
node_admin_view -->|"requests"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_server -->|"mounts API"| node_auth_routes
node_server -->|"mounts API"| node_queue_routes
node_server -->|"mounts API"| node_token_routes
node_server -->|"mounts API"| node_state_routes
node_server -->|"mounts API"| node_analytics_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_queue_routes -->|"dispatches"| node_queue_controller
node_token_routes -->|"dispatches"| node_token_controller
node_state_routes -->|"dispatches"| node_state_controller
node_analytics_routes -->|"dispatches"| node_analytics_controller
node_auth_controller -->|"reads and writes"| node_models
node_queue_controller -->|"reads and writes"| node_models
node_token_controller -->|"reads and writes"| node_models
node_state_controller -->|"reads and writes"| node_models
node_analytics_controller -->|"queries"| node_models
node_models -->|"persists records"| node_mongo
node_token_controller -->|"emits updates"| node_socket_service
node_state_controller -->|"emits updates"| node_socket_service
node_socket_client -->|"connects realtime"| node_server
node_server -->|"initializes"| node_socket_service
node_auto_notify -->|"subscribes"| node_socket_client
node_socket_service -->|"broadcasts events"| node_socket_client

click node_app "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/App.js"
click node_customer_view "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/CustomerView.jsx"
click node_staff_view "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/StaffView.jsx"
click node_admin_view "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/AdminView.jsx"
click node_api_client "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/services/ApiService.js"
click node_socket_client "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/context/SocketContext.js"
click node_auto_notify "https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/components/customer/AutoNotificationManager.jsx"
click node_server "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/index.js"
click node_auth_routes "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/authRoutes.js"
click node_auth_controller "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/authController.js"
click node_queue_routes "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/queueManagementRoutes.js"
click node_token_routes "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/tokenRoutes.js"
click node_state_routes "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/queueStateRoutes.js"
click node_analytics_routes "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/analyticsRoutes.js"
click node_queue_controller "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/queueManagementController.js"
click node_token_controller "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/tokenController.js"
click node_state_controller "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/queueStateController.js"
click node_analytics_controller "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/analyticsController.js"
click node_socket_service "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/services/socketService.js"
click node_models "https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/models/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_app,node_customer_view,node_staff_view,node_admin_view,node_api_client,node_socket_client,node_auto_notify toneBlue
class node_server,node_auth_routes,node_queue_routes,node_token_routes,node_state_routes,node_analytics_routes toneAmber
class node_auth_controller,node_queue_controller,node_token_controller,node_state_controller,node_analytics_controller toneMint
class node_socket_service toneRose
class node_models,node_mongo,node_customer,node_staff,node_admin toneIndigo
```

## Components

### Web client

- [React app](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Customer workflow](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/CustomerView.jsx): `frontend/src/pages/CustomerView.jsx`
- [Staff workflow](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/StaffView.jsx): `frontend/src/pages/StaffView.jsx`
- [Admin workspace](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/pages/AdminView.jsx): `frontend/src/pages/AdminView.jsx`
- [API client](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/services/ApiService.js): `frontend/src/services/ApiService.js`
- [Socket context](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/context/SocketContext.js): `frontend/src/context/SocketContext.js`
- [Turn alerts](https://github.com/abdulqadir-b/smart-queue-system/blob/main/frontend/src/components/customer/AutoNotificationManager.jsx): `frontend/src/components/customer/AutoNotificationManager.jsx`

### API runtime

- [Express server](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/index.js): `backend/index.js`
- [Auth routes](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/authRoutes.js): `backend/routes/authRoutes.js`
- [Queue routes](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/queueManagementRoutes.js): `backend/routes/queueManagementRoutes.js`
- [Token routes](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/tokenRoutes.js): `backend/routes/tokenRoutes.js`
- [Queue state routes](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/queueStateRoutes.js): `backend/routes/queueStateRoutes.js`
- [Analytics routes](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/routes/analyticsRoutes.js): `backend/routes/analyticsRoutes.js`

### Queue domain

- [Authentication](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/authController.js): `backend/controllers/authController.js`
- [Queue operations](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/queueManagementController.js): `backend/controllers/queueManagementController.js`
- [Token operations](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/tokenController.js): `backend/controllers/tokenController.js`
- [Pause and reset](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/queueStateController.js): `backend/controllers/queueStateController.js`
- [Queue analytics](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/controllers/analyticsController.js): `backend/controllers/analyticsController.js`

### Realtime updates

- [Socket service](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/services/socketService.js): `backend/services/socketService.js`

### Persistent state

- [Queue and token models](https://github.com/abdulqadir-b/smart-queue-system/blob/main/backend/models/index.js): `backend/models/index.js`
- **MongoDB**

### Other components

- **Customer**
- **Staff**
- **Administrator**

## Connections

- Customer → React app: uses
- Staff → React app: uses
- Administrator → React app: uses
- React app → Customer workflow: routes
- React app → Staff workflow: routes
- React app → Admin workspace: routes
- Customer workflow → API client: requests
- Staff workflow → API client: requests
- Admin workspace → API client: requests
- API client → Express server: HTTP requests
- Express server → Auth routes: mounts API
- Express server → Queue routes: mounts API
- Express server → Token routes: mounts API
- Express server → Queue state routes: mounts API
- Express server → Analytics routes: mounts API
- Auth routes → Authentication: dispatches
- Queue routes → Queue operations: dispatches
- Token routes → Token operations: dispatches
- Queue state routes → Pause and reset: dispatches
- Analytics routes → Queue analytics: dispatches
- Authentication → Queue and token models: reads and writes
- Queue operations → Queue and token models: reads and writes
- Token operations → Queue and token models: reads and writes
- Pause and reset → Queue and token models: reads and writes
- Queue analytics → Queue and token models: queries
- Queue and token models → MongoDB: persists records
- Token operations → Socket service: emits updates
- Pause and reset → Socket service: emits updates
- Socket context → Express server: connects realtime
- Express server → Socket service: initializes
- Turn alerts → Socket context: subscribes
- Socket service → Socket context: broadcasts events