Queue Management System (QMS)

Universal Queue Management System - A completely generic, white-label Queue Management System that works for any business: Banks, Hospitals, Government Offices, Salons, Restaurants, Universities, DMVs, Clinics, etc.

This is a monorepo containing both the backend (NestJS) and frontend (Next.js) applications.

Technology Stack

Backend

Framework: Node.js 20 + NestJS 10
Database: Microsoft SQL Server (via TypeORM)
Real-Time: Socket.io
Authentication: JWT + Refresh Tokens
SMS: Twilio
Email: Resend
Documentation: Swagger/OpenAPI

Frontend

Framework: Next.js 14
Styling: Tailwind CSS
State Management: Zustand
Real-Time: Socket.io Client
UI Components: Custom components with Framer Motion

Core Principles

One separate queue per Agent/Counter (not one big queue)
Customers choose Service Category → automatically routed to least busy Agent in that category
Agents can only see and control their own queue
Admin has full visibility and override capability
Real-time everywhere (Dashboards, Display Screens, Customer Status)
Ticket printing + SMS + Email virtual tickets
Public REST API for 3rd-party systems
Analytics & Reports available only to Admin
Zero trust – Agents cannot modify other queues

Quick Start

For a quick setup, follow these essential steps:

Install Prerequisites: Node.js 20.x and Microsoft SQL Server
Install Dependencies: npm install (root) and npm install (frontend)
Configure Environment: Create .env with database and JWT settings (see Environment Variables)
Setup Database: Run npm run setup:db to create database and admin user
Start Backend: npm run start:dev (runs on port 3000)
Start Frontend: cd frontend && npm run dev (runs on port 3001)
Login: Use masteradmin / admin (change password immediately!)

For detailed instructions, see the Installation section below.

Prerequisites

Before starting, ensure you have the following installed:

Node.js 20.x (LTS recommended)
Microsoft SQL Server (2017 or later) - SQL Server Express is sufficient for development
npm (comes with Node.js)

Installation

Step 1: Clone and Install Dependencies

# Install backend dependencies
npm install

# Install frontend dependencies
cd frontend
npm install
cd ..

Step 2: Configure Environment Variables

Backend Configuration

Create a .env file in the root directory with the following variables:

# Database Configuration (MS SQL Server)
DB_HOST=localhost
DB_PORT=1433
DB_USERNAME=sa
DB_PASSWORD=YourSQLServerPassword
DB_DATABASE=qms_db
DB_ENCRYPT=true
DB_TRUST_CERT=true

# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key-change-in-production-min-32-chars
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-in-production-min-32-chars
JWT_REFRESH_EXPIRES_IN=7d

# Encryption Key (for sensitive data encryption)
# Generate a secure 64-character hex key for production
ENCRYPTION_KEY=your-generated-64-character-hex-key-or-leave-empty-for-dev-default

# Application
PORT=3000
NODE_ENV=development

# Optional: Redis (for Socket.io scaling in production)
# REDIS_HOST=localhost
# REDIS_PORT=6379

# Optional: Twilio SMS Configuration
# TWILIO_ACCOUNT_SID=your-twilio-account-sid
# TWILIO_AUTH_TOKEN=your-twilio-auth-token
# TWILIO_PHONE_NUMBER=+1234567890

# Optional: Resend Email Configuration
# RESEND_API_KEY=your-resend-api-key
# RESEND_FROM_EMAIL=noreply@yourdomain.com

Important Notes:

Replace YourSQLServerPassword with your actual SQL Server password
For production, generate strong secrets for JWT_SECRET and JWT_REFRESH_SECRET (minimum 32 characters)
Generate a secure ENCRYPTION_KEY for production (64-character hex string)
For local development with SQL Server Express, you may need to set DB_TRUST_CERT=true and DB_ENCRYPT=false

Frontend Configuration

Create a frontend/.env.local file:

NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_SOCKET_URL=http://localhost:3000

Step 3: Database Setup

Prerequisites for Database Setup

Ensure SQL Server is running - Start SQL Server service on your machine
Verify SQL Server Authentication - Ensure SQL Server is configured for Mixed Mode authentication (SQL Server and Windows Authentication)
Check SQL Server Port - Default port is 1433. Verify it's open and accessible

Running the Database Setup Script

The setup script will:

Create the database if it doesn't exist
Create all required tables (Users, Categories, AgentCategories, Tickets)
Create a default admin user

# Run the database setup script
npm run setup:db

What the script does:

Connects to SQL Server using credentials from .env
Creates the qms_db database if it doesn't exist
Initializes encryption service
Creates all database tables using TypeORM
Creates default admin user with credentials:
- Username/Email: masteradmin
- Password: admin

⚠️ Security Warning: Change the default admin password immediately after first login!

Troubleshooting Database Setup

Connection Refused Error:

Ensure SQL Server service is running
Check that port 1433 is correct (or your custom port)
Verify host, username, and password in .env file
Ensure SQL Server allows TCP/IP connections (check SQL Server Configuration Manager)

Authentication Failed:

Verify username and password are correct
Ensure SQL Server authentication is enabled (Mixed Mode)
Check that the user has CREATE DATABASE privileges
For SQL Server Express, ensure you're using the sa account or a user with sufficient privileges

Database Already Exists:

The script will not fail if the database exists
It will update tables if schema has changed
It will update the admin user if it exists

Port Warning:

If you see a warning about port 3306 or 5432, you may have incorrect database settings
MS SQL Server default port is 1433
Update your .env file with correct MS SQL Server settings

Manual Database Setup (Alternative)

If you prefer to set up the database manually:

Create the database:
```
CREATE DATABASE qms_db;
```
Update .env with your database credentials
Run the application - Tables will be created automatically if synchronize: true is enabled (development only)
Create admin user - Use the script or manually insert:
```
npm run setup:db
```

Running the Application

Backend

# Development
npm run start:dev

# Production
npm run build
npm run start:prod

The API will be available at http://localhost:3000 Swagger documentation at http://localhost:3000/api

Frontend

# Navigate to frontend directory
cd frontend

# Development
npm run dev

# Production
npm run build
npm start

The frontend will be available at http://localhost:3001 (or next available port)

API Endpoints

Public Endpoints (No Authentication)

POST /queue/check-in - Customer check-in, create ticket
GET /queue/status - Get public status page
GET /queue/ticket/:tokenNumber - Get ticket by token number
GET /categories/public - Get active categories

Authentication

POST /auth/login - Login (Agent/Admin)
POST /auth/refresh - Refresh access token

Agent Endpoints

GET /queue/agent/my-queue - Get my queue
POST /queue/agent/call-next - Call next ticket
PATCH /queue/agent/:ticketId/serving - Mark as serving
PATCH /queue/agent/:ticketId/complete - Mark as completed
PATCH /queue/agent/:ticketId/no-show - Mark as no-show
PUT /queue/agent/reorder - Reorder my queue
POST /queue/agent/:ticketId/transfer/:newAgentId - Transfer ticket

Admin Endpoints

Users Management

POST /users - Create user
GET /users - Get all users
GET /users/agents - Get all agents
GET /users/:id - Get user by ID
PUT /users/:id - Update user
DELETE /users/:id - Delete user

Categories Management

POST /categories - Create category
GET /categories - Get all categories
GET /categories/:id - Get category by ID
PUT /categories/:id - Update category
DELETE /categories/:id - Delete category
POST /categories/:categoryId/assign-agent/:agentId - Assign agent to category
DELETE /categories/:categoryId/remove-agent/:agentId - Remove agent from category

Queue Management

GET /queue/admin/all - Get all queues
GET /queue/admin/ticket/:id - Get ticket by ID
PATCH /queue/admin/:ticketId/override - Admin override any ticket

Analytics

GET /analytics/dashboard - Get dashboard statistics
GET /analytics/avg-wait-time - Average wait time
GET /analytics/avg-service-time - Average service time
GET /analytics/peak-hours - Peak hours heatmap
GET /analytics/abandonment-rate - Abandonment rate
GET /analytics/agent-performance - Agent performance ranking
GET /analytics/category-stats - Category statistics
GET /analytics/export/excel - Export to Excel

Real-Time Events (Socket.io)

Connect to ws://localhost:3000/queue namespace:

Client Events

join-agent-room - Join agent's room (requires agentId)
join-category-room - Join category room (requires categoryId)
join-public-room - Join public status room

Server Events

ticket:created - New ticket created
ticket:called - Ticket called
ticket:serving - Ticket being served
ticket:completed - Ticket completed
ticket:no-show - Ticket marked as no-show
ticket:transferred - Ticket transferred
queue:updated - Queue updated
status:updated - Public status updated

Frontend Features

Customer Flow: Check-in, category selection, token generation, status page
Agent Dashboard: Queue management, call next, mark as serving/completed
Admin Panel: Users, categories, queues, analytics management
Real-time Updates: Socket.io integration for live updates
Responsive Design: Tailwind CSS for modern UI

Frontend Project Structure

frontend/
  app/
    customer/          # Customer flow pages
      check-in/        # Check-in form
      token/[token]    # Token display page
    agent/             # Agent pages
      login/           # Agent login
      dashboard/       # Agent dashboard
    admin/             # Admin pages
      login/           # Admin login
      dashboard/       # Admin dashboard
      users/           # Users management
      categories/      # Categories management
      queues/          # All queues view
      analytics/       # Analytics dashboard
    status/            # Public status page
  lib/
    api.ts             # API client
    auth.ts            # Authentication utilities
    socket.ts          # Socket.io client

User Roles

Customer/Public: Can check-in and view status (no login required)
Agent: Can manage own queue, call next, mark as serving/completed/no-show, reorder queue, transfer tickets
Admin: Full access to all features, user management, categories, analytics, override capabilities

Key Features

Automatic Routing

When a customer checks in and selects a category, the system automatically:

Finds all active agents assigned to that category
Calculates which agent has the fewest pending tickets
Routes the ticket to that agent
Generates a unique token number
Sends SMS/Email notifications (if configured)