HQMS — Smart Virtual Queue for Hospitals

🏥 The Problem

What if “waiting at the hospital” didn't actually mean waiting at the hospital?

Hospital waiting rooms can become extremely crowded, especially during OPD hours. Patients often have no idea how many people are ahead of them or how long they will have to wait.

This creates unnecessary anxiety for patients and operational pressure for clinical staff.

HQMS (Hospital Queue Management System) was built to solve this problem by replacing traditional physical waiting with a real-time virtual queue.

💡 The Solution

HQMS allows patients to join and track their hospital queue directly from a mobile browser without installing an app or creating an account.

Patients can see:

Current queue position
Estimated waiting time
Real-time queue updates
Audio alerts
Presence status such as "Stepping Away" and "Returning"

Instead of spending hours sitting in a waiting room, patients can step away and return when their turn is approaching.

🏢 Hospital Management

HQMS provides dedicated workflows for hospital operations.

Hospital administrators can manage:

Departments
OPDs
Consultation rooms
Doctors
Doctor assignments
Patient queues

The platform uses role-based access control so administrators, doctors, and patients have different experiences based on their responsibilities.

🩺 Doctor Workstation

Doctors get a dedicated workstation for managing their active queue.

They can:

Call the next patient
Start and track consultations
Monitor consultation duration
Manage the active queue
Resume the queue after a consultation

The goal is to keep the workflow simple enough for busy clinical environments.

📱 Zero-Install Patient Experience

Patients don't need to download an application or create an account.

A secure, unguessable tokenized URL gives the patient access to their queue tracker from any mobile browser.

This keeps the experience simple while still providing real-time information.

📺 Public Waiting Board

HQMS also includes a real-time public waiting board designed for hospital TVs and wall-mounted displays.

It provides a high-contrast interface for displaying queue information while avoiding unnecessary patient information.

🔒 Concurrency-Safe Queue Engine

One of the most challenging parts of the project was building a reliable queue engine.

Multiple staff members may interact with the same queue at the same time, so the system needs to prevent race conditions and duplicate queue assignments.

HQMS uses a deterministic Finite State Machine (FSM) for queue state transitions together with PostgreSQL pessimistic locking:

SELECT ... FOR UPDATE

This ensures critical queue operations are properly synchronized at the database level.

🏢 Multi-Tenant Architecture

HQMS was designed as a multi-tenant SaaS platform.

Multiple hospitals can operate on the same application while maintaining tenant-level isolation.

Each hospital has its own:

Departments
OPDs
Doctors
Consultation rooms
Queues
Staff access

Queue numbering is also independent between hospitals.

⚡ Real-Time Architecture

The platform uses WebSockets to synchronize queue changes in real time.

When a doctor calls a patient or the queue changes, connected patient trackers and public waiting boards can receive the update without requiring a page refresh.

This creates a synchronized experience between hospital staff, patients, and waiting-room displays.

🛠️ How It Was Built

Backend

Python 3.12
FastAPI
SQLAlchemy Async
Pydantic v2
Alembic

Frontend

Next.js 14
TypeScript
Tailwind CSS
Lucide Icons

Database & Real-Time

PostgreSQL
Neon
WebSockets
Async database engine

Deployment

Vercel
Render
Neon

🧪 Testing

The project currently has 34/34 automated unit and integration tests passing.

Testing covers important application workflows and queue operations.

✉️ Notifications

I also experimented with Fast2SMS and Meta WhatsApp APIs for notifications.

These integrations were kept optional because external messaging services introduce ongoing costs. The core HQMS experience does not depend on paid messaging services.

🚧 Challenges

The most interesting challenges were beyond basic CRUD functionality.

The project required solving problems around:

Concurrent queue operations
Race-condition prevention
Multi-tenant data isolation
Real-time WebSocket synchronization
Queue state management using an FSM
Designing separate workflows for administrators, doctors, patients, and public displays

These challenges made HQMS a practical exercise in concurrency, real-time systems, multi-tenancy, and backend architecture.

📚 What I Learned

Building HQMS gave me practical experience with asynchronous backend development, real-time WebSockets, PostgreSQL concurrency control, state machines, multi-tenant SaaS architecture, and role-based access control.

The biggest lesson was that building a real-world system isn't only about making individual features work. The system also needs to remain consistent when multiple users interact with it simultaneously.