Smart Queue - Hospital Queue & Appointment Management System

A hospital queue management system for local development, built with NestJS, Next.js, and SQLite. Features intelligent triage scoring, real-time queue tracking, appointment management, and role-based dashboards for patients, doctors, and staff.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Frontend    │────▶│   Backend    │────▶│   SQLite     │
│  (Next.js)   │     │  (NestJS)    │     │  (dev.db)    │
│  Port 3000   │     │  Port 3001   │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

Runs entirely on localhost — no external services or internet required.

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 14 (React)	Server-side rendered UI
Styling	Tailwind CSS	Utility-first CSS framework
Charts	Recharts	Analytics visualization
Backend	NestJS 10	Enterprise Node.js framework
ORM	Prisma	Type-safe database access
Database	SQLite	Embedded relational database
Auth	JWT + Passport	Secure authentication
API Docs	Swagger/OpenAPI	API documentation

Project Structure

smart-queue/
├── backend/                    # NestJS Backend
│   ├── prisma/
│   │   └── schema.prisma      # Database schema
│   ├── src/
│   │   ├── main.ts            # Application entry point
│   │   ├── app.module.ts      # Root module
│   │   ├── common/            # Shared resources
│   │   │   ├── decorators/    # Custom decorators
│   │   │   ├── guards/        # Auth & role guards
│   │   │   └── interfaces/    # TypeScript interfaces
│   │   ├── config/            # Configuration
│   │   ├── database/          # Prisma service + seed
│   │   └── modules/           # Feature modules
│   │       ├── auth/          # Authentication & registration
│   │       ├── users/         # User management
│   │       ├── patients/      # Patient records
│   │       ├── doctors/       # Doctor profiles
│   │       ├── appointments/  # Appointment booking
│   │       ├── queue/         # Queue management + auto-checkin
│   │       ├── triage/        # Medical triage engine
│   │       ├── departments/   # Department management
│   │       ├── reports/       # Reporting engine
│   │       ├── dashboard/     # Role dashboards
│   │       ├── emergency/     # Emergency handling
│   │       └── staff/         # Staff management
│
├── frontend/                   # Next.js Frontend
│   ├── src/
│   │   ├── app/
│   │   │   ├── (protected)/   # Authenticated routes
│   │   │   │   ├── doctor/    # Doctor portal (queue, dashboard, appointments)
│   │   │   │   ├── staff/     # Staff portal (queue, dashboard, walk-in, reports)
│   │   │   │   ├── patient/   # Patient portal (dashboard, appointments, walk-in)
│   │   │   │   ├── admin/     # Admin panel
│   │   │   │   └── dashboard/ # Shared dashboard
│   │   │   ├── auth/          # Login/Register
│   │   │   └── components/    # Layout, UI, triage components
│   │   ├── lib/               # API client
│   │   └── types/             # TypeScript types
│
└── README.md

Features

Queue Engine

• Priority-based sorting — EMERGENCY → APPOINTMENT → WALK_IN within each status level
• Triage scoring — 0-100 scale with cross-rule checks (elderly+fever, smoker+respiratory)
• Triage levels — P1_CRITICAL (90), P2_URGENT (60), P3_STANDARD (20)
• Staff review workflow — flagged patients reviewed before being callable
• Auto check-in — cron job runs every minute; scheduled appointments become queue entries
• Doctor busy guard — a doctor can only have one active patient at a time
• Real-time sync — 10-15s polling + visibilitychange + focus + custom review-updated events

Patient Portal

• Phone-based registration and login
• Appointment booking with time-slot conflict prevention
• Walk-in registration with guided symptom triage
• Real-time queue position tracking (relative to same-doctor queue)
• Appointment history

Staff Dashboard

• Walk-in patient registration with triage
• Unified queue view across all doctors with doctor filter dropdowns
• Queue prioritization (override triage level)
• Emergency check-in
• Daily appointment overview

Doctor Portal

• Personal queue sorted by status and priority
• IN_PROGRESS appointments merged at top of queue
• Call next / complete visit workflow
• Appointment schedule

Triage Engine

• Rule-based severity/risk scoring with 40+ symptom rules
• Cross-rule interactions (R067: elderly+fever boosts score; R066: smoker+respiratory boosts score)
• Cluster-based escalation for related symptoms
• Patient role caps at P2 to prevent self-diagnosed critical
• Department auto-assignment from symptom mapping

Emergency Handling

• Walk-in emergency registration with automatic highest priority
• Emergency patients bypass staff review (needsStaffReview: false)
• Red-highlighted queue entries

Quick Start

Prerequisites

• Node.js 20+
• npm

Setup

1. Install dependencies

# Backend
cd backend
npm install

# Frontend
cd ../frontend
npm install

2. Setup environment

# Backend — copy and edit
cp backend/.env.example backend/.env

# Frontend
echo "NEXT_PUBLIC_API_URL=http://localhost:3001" > frontend/.env.local

3. Run migrations & seed

cd backend
npx prisma migrate dev --name init
npx prisma generate
npx ts-node src/database/seed.ts

5. Start servers

# Terminal 1 — Backend (port 3001)
cd backend
npm run start:dev

# Terminal 2 — Frontend (port 3000)
cd frontend
npm run dev

6. Access

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001/api/v1
• API Docs: http://localhost:3001/api/docs

Demo Credentials

All accounts use password: Password123!

Role	Login
Doctor	Login via email or phone (see seed data)
Staff	Login via email or phone (see seed data)
Patient	Login via phone number (see seed data)
Admin	Login via email or phone (see seed data)

Patients log in using their phone number. Sample patient: Bilal Ahmed (+921234567890).

Role-Based Access

Feature	Patient	Staff	Doctor	Admin
Register/Login	✅	✅	✅	✅
Book Appointment	✅	✅	-	-
View Queue Position	✅	✅	✅	✅
Manage Queue	-	✅	✅	✅
Triage Assessment	Self	Full	Full	✅
Emergency Check-in	-	✅	-	✅
View Reports	-	✅	✅	✅
Manage Departments	-	-	-	✅
System Config	-	-	-	✅

Key Design Decisions

• Queue sorting is client-side — conditional status+patientType ordering via rank function rather than Prisma orderBy
• Real-time sync uses polling (10-15s) + visibilitychange + custom events instead of WebSockets
• Appointment auto-check-in assigns WITH_DOCTOR only if the doctor is free; otherwise WAITING
• Overlapping appointments are prevented at the database level (same patient + same date + same time slot)
• Triage cross-checks run before priority assignment so boosted scores affect threshold evaluation

API Endpoints

Authentication

• POST /api/v1/auth/register — Register (phone-based)
• POST /api/v1/auth/login — Login
• POST /api/v1/auth/refresh — Refresh token
• POST /api/v1/auth/logout — Logout

Appointments

• GET /api/v1/appointments/my — My appointments (Patient)
• GET /api/v1/appointments/doctor/:id — Doctor's appointments
• GET /api/v1/appointments — All appointments (Staff/Admin)
• POST /api/v1/appointments — Create appointment
• PATCH /api/v1/appointments/:id/cancel — Cancel
• PATCH /api/v1/appointments/:id/reschedule — Reschedule

Queue

• POST /api/v1/queue/check-in — Check in walk-in/emergency
• GET /api/v1/queue/doctor/:id — Doctor's queue
• GET /api/v1/queue/unified — Unified queue (all doctors)
• POST /api/v1/queue/doctor/:id/call-next — Call next patient
• POST /api/v1/queue/:id/complete — Mark visit completed
• GET /api/v1/queue/stats — Queue statistics

Triage

• POST /api/v1/triage/assess/:patientId — Run triage assessment
• POST /api/v1/triage/:queueEntryId/override — Override priority (Staff)
• GET /api/v1/triage/critical/list — Critical case list
• GET /api/v1/triage/stats/summary — Triage statistics

Reports

• GET /api/v1/reports/daily — Daily report
• GET /api/v1/reports/weekly — Weekly report
• GET /api/v1/reports/monthly — Monthly report
• GET /api/v1/reports/doctor/:id/workload — Doctor workload
• GET /api/v1/reports/patients/statistics — Patient statistics

Full API docs at /api/docs when backend is running.

Database Schema

Key entities:

• User — Base user with role (PATIENT/DOCTOR/STAFF/ADMIN), phone login
• Patient — Extended profile (gender, medical conditions)
• Doctor — Medical professional with department, availability schedule
• Department — Hospital departments with symptom-to-department mapping
• Appointment — Scheduled visits with time slots
• QueueEntry — Real-time queue with priority score, needsStaffReview flag
• TriageAssessment — Medical triage with symptom IDs, triggered rules, severity/risk/confidence scores
• DoctorAvailability — Weekly availability slots
• AuditLog — System audit trail
• SystemConfig — Key-value configuration store