QueueLess is a comprehensive, multi‑tenant queue management platform designed for businesses of all types – hospitals, banks, shops, restaurants, and more. It allows administrators to create and manage multiple locations (places), providers to handle queues in real time, and users to join queues, track their position, receive notifications, and provide feedback. The system features live updates via WebSocket, email/push notifications, Razorpay payment integration, role‑based access control, and detailed analytics.

1. Features
2. Tech Stack
3. Architecture Overview
4. Screenshots & Demo
5. Getting Started
   • Prerequisites
   • Installation
   • Environment Variables
   • Running Locally
   • Docker Setup
6. API Documentation
7. WebSocket Real‑Time Updates
8. Testing
9. Deployment
10. Troubleshooting
11. Future Roadmap
12. Contributing
13. License
14. Code of Conduct

• Search & Discover: Find places by name, type, location, or rating.
• Join Queues: Choose regular, group, or emergency tokens (with provider approval).
• Real‑time Updates: Live position, wait time, and status changes via WebSocket.
• Notifications: Email and push notifications before your turn, and when a queue becomes short.
• Feedback: Rate your experience with detailed dimensions (staff, service, wait time).
• Favorites: Save favourite places for quick access.
• Token History: View past tokens and ratings.
• Per‑Queue Notification Preferences: Customise when and how you are notified for each queue.

• Queue Management: Create, pause, resume, and reset queues.
• Token Handling: Serve next, complete, cancel tokens; view user details for each token.
• Emergency Approvals: Approve or reject emergency tokens with optional reason.
• Dashboard: Real‑time statistics, drag‑and‑drop reorder, export reports (PDF/Excel).
• Analytics: Token volume over time, busiest hours, average wait time trends.

• Place Management: Create and update places with images, location, contact info, business hours.
• Service Management: Define services under each place (e.g., cardiology, haircut) with average service time.
• Provider Management: Add providers (via token purchase), update their details, assign places, enable/disable accounts, reset passwords.
• Dashboard: Overview of all places, queues, providers, payment history, and analytics charts.
• Export: Generate admin reports in PDF/Excel.
• Alert Configuration: Set wait time thresholds to receive email alerts.
• Geographic Heat Map: Visualise queue load across all places.

• Authentication & Authorization: JWT‑based with roles: USER, PROVIDER, ADMIN. Email verification via OTP.
• Payments: Razorpay integration for purchasing admin/provider tokens.
• Audit Logging: All critical actions are logged for compliance and debugging.
• Rate Limiting: Per‑user and IP‑based limits to prevent abuse.
• Caching: Redis cache for places, services, queues.
• Monitoring: Prometheus metrics, Grafana dashboards, Loki logs.

QueueLess follows a client‑server architecture with a Spring Boot backend and a React frontend.

• Backend: Exposes RESTful API and STOMP WebSocket endpoints. Business logic is encapsulated in services. Data persistence uses MongoDB (with geospatial queries). Redis is used for caching and temporary OTP storage.
• Frontend: Single‑page application built with React and Redux for state management. WebSocket client maintains live connections for queue updates.
• Real‑time Updates: When a queue changes (token added, served, completed), the backend broadcasts the updated queue via WebSocket to all subscribed clients.
• Security: All endpoints except public ones require a JWT token. Role‑based access is enforced with method‑level annotations (@AdminOnly, @ProviderOnly, etc.).
• Payments: Admin/Provider tokens are purchased via Razorpay; the backend generates and validates the tokens.
• Push Notifications: Firebase Cloud Messaging is used for sending notifications when a user’s turn is approaching or when a queue becomes short.

• User – can be USER, PROVIDER, or ADMIN.
• Place – represents a physical location (hospital, shop) with geo‑coordinates.
• Service – a specific service offered at a place (e.g., “Cardiology Consultation”).
• Queue – linked to a service and provider, contains a list of tokens.
• Token – represents a user’s spot in a queue; can be regular, group, or emergency.
• Feedback – submitted for completed tokens, includes multi‑dimensional ratings.
• AuditLog – records important actions for traceability.
• NotificationPreference – per‑queue notification settings for users.

(All screenshots are from the running application. Click on each collapsible section to view.)

Schemas

Interactive OpenAPI documentation for all controllers and models.

Queue Metrics

Spring Boot Metrics

Cache & Performance

Logs Drilldown

All Metrics

Visualise metrics and logs from Prometheus and Loki.

Live Queue Updates

All screenshots are from the running application.

• Java 25 (or newer)
• Node.js 20+ and npm
• MongoDB (local or Atlas)
• Redis (local or cloud)
• Razorpay account (for payments)
• Firebase project (for push notifications)
• SMTP server (e.g., Gmail) for emails

1. Clone the repository

   git clone https://github.com/harman-04/QueueLess.git cd QueueLess

2. Backend setup

   cd backend/backend ./mvnw clean install

3. Frontend setup

   cd .. cd ../frontend/queue-less-frontend npm install

Create a .env file in both backend and frontend directories.

MONGODB_URI=mongodb://localhost:27017/queueless REDIS_HOST=localhost JWT_SECRET=your_jwt_secret_key_here JWT_EXPIRATION=86400000 RAZORPAY_KEY=rzp_test_xxxxxxxxxx RAZORPAY_SECRET=your_razorpay_secret MAIL_USERNAME=your_email@gmail.com MAIL_PASSWORD=your_app_password SSL_KEY_STORE_PASSWORD=changeit APP_FRONTEND_URL=https://localhost:5173

Note: For Gmail, use an App Password if 2FA is enabled.

VITE_API_BASE_URL=https://localhost:8443/api VITE_FIREBASE_API_KEY=your_firebase_api_key VITE_FIREBASE_AUTH_DOMAIN=your_firebase_auth_domain VITE_FIREBASE_PROJECT_ID=your_firebase_project_id VITE_FIREBASE_STORAGE_BUCKET=your_firebase_storage_bucket VITE_FIREBASE_MESSAGING_SENDER_ID=your_firebase_messaging_sender_id VITE_FIREBASE_APP_ID=your_firebase_app_id VITE_FIREBASE_VAPID_KEY=your_firebase_vapid_key VITE_RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxx

When running the full stack with Docker Compose, place a third .env file in the project root (the same directory as docker-compose.yml). This file supplies environment variables to the containers. It typically contains a superset of the variables needed by both backend and frontend, plus any additional configuration for the containers themselves.

Example docker-compose.env (or simply .env at the root):

# Backend MONGODB_URI=mongodb://mongodb:27017/queueless JWT_SECRET=your_jwt_secret_key_here JWT_EXPIRATION=86400000 RAZORPAY_KEY=rzp_test_xxxxxxxxxx RAZORPAY_SECRET=your_razorpay_secret MAIL_USERNAME=your_email@gmail.com MAIL_PASSWORD=your_app_password SSL_KEY_STORE_PASSWORD=changeit APP_FRONTEND_URL=https://localhost:5173 # Frontend VITE_API_BASE_URL=https://backend:8443/api VITE_FIREBASE_API_KEY=your_firebase_api_key VITE_FIREBASE_AUTH_DOMAIN=your_firebase_auth_domain VITE_FIREBASE_PROJECT_ID=your_firebase_project_id VITE_FIREBASE_STORAGE_BUCKET=your_firebase_storage_bucket VITE_FIREBASE_MESSAGING_SENDER_ID=your_firebase_messaging_sender_id VITE_FIREBASE_APP_ID=your_firebase_app_id VITE_FIREBASE_VAPID_KEY=your_firebase_vapid_key VITE_RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxx

cd backend/backend ./mvnw spring-boot:run The backend will start on `https://localhost:8443` (SSL enabled). You can access the API at `https://localhost:8443/api`. #### Frontend ```bash cd frontend/queue-less-frontend npm run dev

The frontend will be available at https://localhost:5173.

The application uses HTTPS (port 8443 for backend, 443 for frontend in Docker) with self‑signed certificates. To avoid browser warnings, you can generate trusted certificates using mkcert.

• macOS: brew install mkcert
• Windows: choco install mkcert or download from github.com/FiloSottile/mkcert
• Linux: sudo apt install libnss3-tools then curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64" && chmod +x mkcert-v*-linux-amd64 && sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

1. Create a local CA (one‑time):

   mkcert -install

2. Generate certificates for localhost:

   cd backend/src/main/resources mkcert localhost 127.0.0.1 ::1

   This creates localhost+2.pem and localhost+2-key.pem. Rename them:

   mv localhost+2.pem localhost.pem mv localhost+2-key.pem localhost-key.pem

3. Convert to PKCS12 format (required by Spring Boot):

   openssl pkcs12 -export -in localhost.pem -inkey localhost-key.pem -out localhost.p12 -name localhost -password pass:changeit

   The password changeit matches the default in application.properties.

4. Place the .p12 file inside src/main/resources/.

The application.properties already contains:

server.ssl.key-store=classpath:localhost.p12 server.ssl.key-store-password=${SSL_KEY_STORE_PASSWORD:changeit} server.ssl.key-store-type=PKCS12

Make sure the password matches the one used when generating the .p12 file.

For the Vite dev server to trust the certificate, add this to vite.config.js:

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], server: { https: { key: 'path/to/localhost-key.pem', cert: 'path/to/localhost.pem', }, port: 5173, proxy: { '/api': { target: 'https://localhost:8443', changeOrigin: true, secure: false, }, }, }, });

Replace the paths with the actual location of your .pem files. The proxy ensures API requests are forwarded to the backend without CORS issues.

In the provided docker-compose.yml, the backend uses the localhost.p12 file mounted from the host. Ensure you have generated the .p12 file and placed it in the expected location (backend/src/main/resources/localhost.p12).

Note: For production, use certificates from a trusted CA like Let’s Encrypt.

The project includes a docker-compose.yml that runs the entire stack (backend, frontend, MongoDB, Redis, Prometheus, Grafana, Loki, Promtail). Make sure you have Docker and Docker Compose installed.

1. Build and start all services

   docker-compose up --build

2. Access the application

   • Frontend: https://localhost:5173
   • Backend API: https://localhost:8443
   • Grafana: http://localhost:3000 (admin/admin)
   • Prometheus: http://localhost:9090
   • Loki: http://localhost:3100

Note: SSL certificates are self‑signed for development; browsers will show a warning – proceed anyway.

Interactive API documentation is available via Swagger UI when the backend is running:

https://localhost:8443/swagger-ui.html 

For a complete list, refer to the Swagger UI.

QueueLess uses WebSocket (STOMP over SockJS) to provide live queue updates. The WebSocket endpoint is /ws.

import { Client } from '@stomp/stompjs'; import SockJS from 'sockjs-client'; const client = new Client({ webSocketFactory: () => new SockJS('https://localhost:8443/ws'), connectHeaders: { Authorization: `Bearer ${token}` }, onConnect: () => console.log('Connected'), }); client.activate();

Subscribe to /topic/queues/{queueId} to receive updates whenever the queue changes (token added, served, completed, cancelled).

client.subscribe('/topic/queues/' + queueId, (message) => { const queue = JSON.parse(message.body); // update UI });

• /user/queue/emergency-approved – emergency token approval/rejection.
• /user/queue/token-cancelled – token cancellation notifications.
• /user/queue/provider-updates – (for providers) updates when they serve a token.

• /app/queue/serve-next – serve next token (provider only).
• /app/queue/add-token – add a regular token (user).
• /app/queue/status – toggle queue active status (provider).

All commands require authentication and appropriate role.

Run unit and integration tests with Maven:

cd backend ./mvnw test

The tests cover services, controllers, and some integration flows. A local MongoDB instance is automatically started/stopped via embedded MongoDB for tests.

Frontend tests are not yet implemented, but the architecture is ready for them using Jest and React Testing Library.

1. Build an executable JAR:

   cd backend ./mvnw clean package -DskipTests

2. Copy the JAR (target/backend-0.0.1-SNAPSHOT.jar) to your server.

3. Run with Java:

   java -jar backend-0.0.1-SNAPSHOT.jar

   Use a process manager like systemd or supervisor to keep it running.

1. Build the production bundle:

   cd frontend npm run build

2. Serve the dist folder with a web server (e.g., Nginx).

For a full stack deployment, use the provided docker-compose.yml on a server with Docker installed. Adjust environment variables in the compose file or in a .env file.

• Ensure MongoDB is running locally or the MONGODB_URI is correct.
• If using embedded MongoDB for tests, it starts automatically.

• Verify Redis is installed and running (redis-server).
• If Redis is not needed, you can disable caching by setting spring.cache.type=none in application.properties.

• For Gmail, enable 2FA and generate an App Password.
• Check that MAIL_USERNAME and MAIL_PASSWORD are correct.
• If using a different SMTP provider, adjust spring.mail.host and port.

• Ensure Firebase project is configured correctly and VAPID_KEY is set.
• In the browser, check that notifications are allowed for the site.
• Verify that FCM tokens are being stored in the database (user's fcmTokens array).

• Make sure the uploads/ directory exists and is writable.
• The backend serves static files under /uploads/**. If you get 404, check that WebConfig is properly configured.

• Check that the backend is running and the WebSocket endpoint /ws is accessible.
• Ensure the JWT token is valid and passed in the Authorization header.
• If using self‑signed certificates, the browser may block the connection. In development, you can temporarily disable SSL verification or use a valid certificate.

• Adjust rate.limit.* properties in application.properties. For example, increase capacity and refill for development.

• The JWT expiration is set to 24 hours by default. If your system clock is skewed, tokens may appear expired. Synchronize time via NTP.

While QueueLess already provides a robust set of features, the following enhancements are planned for upcoming releases:

• Multiple Active Tokens per User: Allow users to join queues in different places simultaneously.
• Per‑Service Multiple Queues: Let users choose from multiple providers offering the same service (e.g., different doctors at the same hospital).
• Emergency Toggle for Providers: Enable/disable emergency support for an existing queue.
• Export Cleanup: Automatic removal of old export files from the cache.
• Admin Audit Log Viewer: Interface for administrators to inspect audit logs.
• Internationalization (i18n): Support for multiple languages.
• Mobile App: React Native or Flutter version for native push notifications and offline support.
• Advanced Analytics: Predictive wait time models using historical data.

We welcome contributions! To ensure a smooth process, please follow these guidelines:

1. Fork the repository and create your branch from main.
2. Write tests for any new functionality. We aim for high test coverage.
3. Ensure all tests pass by running mvn test in the backend and (if applicable) npm test in the frontend.
4. Follow coding conventions:
   • Backend: Use standard Java naming conventions, include Javadoc for public methods, and format code with your IDE's default settings.
   • Frontend: Use ESLint and Prettier (configuration included).
5. Commit messages should be clear and follow Conventional Commits (e.g., feat: add user profile image upload).
6. Open a pull request against the main branch. Describe your changes in detail and link any related issues.

• Backend: Run ./mvnw spring-boot:run for hot reload.
• Frontend: Run npm run dev for Vite dev server with HMR.

Use the GitHub issue tracker to report bugs or suggest features. Include as much detail as possible: steps to reproduce, expected behavior, screenshots, and environment details.

This project is licensed under the Apache License, Version 2.0.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

We as members, contributors, and leaders pledge to make participation in our community a harassment‑free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio‑economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our full Code of Conduct is available in the CODE_OF_CONDUCT.md file. By participating, you are expected to uphold this code.

• Thanks to all contributors and open‑source libraries that made this project possible.
• Special thanks to the Spring Boot and React communities for excellent documentation and tools.