MediQueue Documentation & User Portal
Step-by-step walkthroughs for patients, doctors, and administrators, alongside full software engineering architecture and deployment references.
For Patients, Doctors & Admins
Step-by-step instructions on using every feature.
For Developers & Evaluators
Architecture, SRS, UCP estimation, Docker, security & tests.
🟢 Step-by-Step User Guides
Non-technical walkthroughs for everyday clinic operation.
Patient Guide: How to Join & Track Your Queue
No more waiting in physical lines at the clinic reception.
Create an Account or Sign In
Click "Get Started" on the homepage. Enter your Name, Email, and Password. If you already have an account, click "Sign In".
Demo Patient Account: john.doe@example.com / password
Choose a Clinic Service
Go to "Join Queue" in the top menu. You will see all available departments (e.g. General Consultation, Nursing, Pharmacy) with their average wait times and current queue lengths.
Take Your Digital Queue Ticket
Click "Select & Join Queue", review the estimated wait, and click "Confirm & Issue Queue Ticket". You will immediately be assigned a unique ticket number (e.g. GC-005).
Track Your Real-Time Position from Anywhere
Your screen automatically refreshes every 4 seconds. You will see:
- Your exact Position: (e.g. #1 in line)
- People Ahead of You: (e.g. 0 people ahead)
- Estimated Wait: (e.g. ~0 minutes)
- Currently Serving: Shows who is in consultation right now.
When Called: "It's Your Turn!"
When the doctor calls your number, your screen will turn bright indigo with an animated "It is Your Turn!" banner. You will also receive an automated email alert and in-app notification. Proceed immediately to the consultation room!
Clinical Staff Guide: Doctor & Nurse Console
How to call patients, manage consultations, and handle no-shows.
Sign in with Staff Credentials
Sign in with your staff account (e.g. dr.sarah@mediqueue.test / password). You will be redirected straight to the Staff Queue Console.
Select Your Department
Use the top-right department dropdown to choose which queue you are serving (e.g. General Consultation, Lab, or Nursing).
Calling the Next Patient
Click the big green button: "Call Next Patient". The system selects the next eligible patient according to priority and sequence. This instantly updates the patient's phone and broadcasts their number to the waiting room TV screen!
5-Tier Manchester Emergency Triage Assessment
Staff can assess and update any waiting patient's triage severity with one click:
- 🔴 Red (P1): Resuscitation / Immediate Emergency (Auto-escalates to Urgent)
- 🟠 Orange (P2): Very Urgent (10-minute target)
- 🟡 Yellow (P3): Urgent (60-minute target)
- 🟢 Green (P4): Standard Outpatient (120-minute target)
- 🔵 Blue (P5): Non-Urgent (240-minute target)
Diagnostic Laboratory Referral & Auto-Loopback
During consultation, expand "🧪 Order Lab Investigation & Transfer". The patient transitions seamlessly to the Laboratory queue. When the lab technician inputs test findings, the ticket is automatically returned to the referring doctor with retained Orange / Urgent priority for immediate review!
🚨 Emergency Unconscious Trauma Protocol (Code Red)
When an unconscious, unidentified patient arrives without ID, click "Emergency Trauma" from the Left Sidebar. The system generates a temporary Trauma MRN (e.g. EMG-DOE-4821), allocates an Emergency Triage Bay, sets 🔴 Red Triage, and broadcasts a Code Red emergency page to all active on-call doctors. When identified, staff can link the trauma ticket to their permanent verified MRN.
Discharge, Care Summary & PDF Reporting
Concluding a consultation automatically releases the allocated bed, records final clinical notes, and dispatches a complete care summary email to the patient. Administrators can download streaming CSVs and formatted PDF operational summary reports from the Reports & Analytics portal.
Starting and Concluding Service
- Start Service: When the patient enters the room, click "Start Service" to begin timing the consultation.
- Complete Service: When done, click "Complete Service" to archive the ticket and compute accurate average wait times.
- Skip Patient: If the patient did not enter the room after multiple calls, click "Skip".
- Recall Patient: If a skipped patient returns to the desk, you can click "Recall" to put them back into consultation status.
Administrator Guide: Governance, Users & Settings
Managing clinic departments, resetting passwords, and system audits.
Access Admin Dashboard
Log in with admin@mediqueue.test / password. View clinic KPIs: total patients, active services, waiting count, and average wait time.
Managing Clinic Services
Navigate to "Services". You can create new departments (e.g. Dental, Pediatrics), edit prefixes (e.g. DEN), adjust consultation durations, or activate/deactivate departments without downtime.
Medical Staff Licensing Vetting & Privilege Extension
Under "System Users & Roles", administrators inspect applicant medical licenses (e.g. MMC-748921), assign clinical roles (Doctor, Nurse, Pharmacist, Lab Tech, or Front Desk Staff), approve/revoke access, and dynamically extend custom capabilities via the Dynamic Privilege Extension matrix.
🛡️ HIPAA & ISO 27001 Security Incident Telemetry
Inspect continuous anomaly detection telemetry under "Security & Compliance". The engine tracks brute-force login attempts, unauthorized route access, privilege escalations, and client IP addresses, enabling one-click audit mitigation.
User Creation & Password Resets
Navigate to "Users". Click "Create Account" to add doctors, nurses, or admins. Click "Edit" on any user row to update profile details or perform an Administrative Password Reset (which automatically emails the new credentials to the user).
Configuring Clinic Information & Settings
Navigate to "Settings". Change the clinic name, contact phone, physical address, operating hours, and toggle automated email alerts.
Security Audit Trail
Navigate to "Audit". Review the immutable, timestamped record of every action taken in the system, complete with actor names, target records, JSON metadata, and client IP addresses.
Hospital Waiting Room TV Display Guide
How to set up the public departure board screen on waiting area TVs or tablets.
Open /display on any Smart TV browser or tablet in the clinic waiting room:
- Fullscreen Mode: Click the expand icon in the top right to make the display fill the entire TV screen with zero browser chrome.
- Automatic Refresh: The screen polls the server every 3 seconds — no manual refresh required.
- Audio & Visual Chime: When a new patient is called, the number flashes in bold white and indigo on the left panel.
🔵 Software Engineering & Technical Reference
Architectural specifications, algorithms, estimation models, and deployment configurations.
1. System Architecture (ADR-002)
MediQueue follows a Modular Layered Monolith architecture using Laravel 12 on PHP 8.2 with Blade templates and Tailwind CSS v4. Database queries on active queues employ pessimistic locking (lockForUpdate) inside atomic transactions to eliminate race conditions.
[ Client Tier ] ── Web Browsers / Mobile Clients / Hospital TV Kiosks
│
▼
[ Web Presentation ] ── Laravel Blade Layouts (x-layouts.app) + Tailwind v4 Design Tokens
│
▼
[ Security Guard ] ── RoleMiddleware (patient | staff | admin) + RateLimiter Throttling
│
▼
[ Controllers ] ── Patient, Staff, Admin & Display Controllers
│
▼
[ Domain Service ] ── QueueService (Atomic transactions, sequence generation, state transitions)
│
▼
[ Persistence Tier] ── Eloquent Models (User, Service, QueueEntry, Notification, Setting, AuditLog)
│
▼
[ Storage Tier ] ── Relational DB (SQLite for dev/testing; MySQL/Postgres for production)
2. Queue State Machine Specification
Every ticket follows a formal finite state machine enforced by QueueEntry::canTransitionTo():
| From Status | To Status | Actor | Trigger / Guard Condition |
|---|---|---|---|
| WAITING | CALLED | Staff | "Call Next" CTA; selects highest priority FIFO ticket. |
| WAITING | CANCELLED | Patient / Admin | Patient cancels queue place before being called. |
| CALLED | IN_SERVICE | Staff | Patient enters room; consultation starts. |
| CALLED | SKIPPED | Staff | No-show response; moves to skipped pool. |
| SKIPPED | CALLED | Staff | Patient returns to desk; recalled to active call. |
| IN_SERVICE | COMPLETED | Staff | Consultation concluded (Terminal state). |
3. Requirements Traceability Matrix (RTM)
| Req Code | Specification | Priority | Verification Method |
|---|---|---|---|
| REQ-AUTH-001 | User Registration & Bcrypt Hashing | MUST | AuthTest::test_patient_can_register |
| REQ-AUTH-006 | Role-Based Access Control (RBAC) | MUST | AuthorizationTest (8 test cases) |
| REQ-QUEUE-001 | Sequential Atomic Ticket Issuing | MUST | QueueLifecycleTest::test_sequential_ticket_numbers |
| REQ-QUEUE-004 | Duplicate Active Ticket Prevention | MUST | QueueLifecycleTest::test_duplicate_prevented |
| REQ-DISP-001 | Hospital Screen TV Display | SHOULD | AdminEnhancementsTest::test_hospital_display |
| REQ-NOTIF-001 | Transactional Email Dispatch | SHOULD | AdminEnhancementsTest::test_email_dispatch |
4. Software Effort Estimation (Use Case Points)
Calculated using Gustav Karner's algorithmic Use Case Points formula:
Total effort: 46 person-hours (fits within the individual 48-hour examination scope).
5. Production Deployment & DevOps
MediQueue includes a multi-stage production Dockerfile and automated Render.com Blueprint (render.yaml) that provisions both the Dockerized Laravel application and a Managed PostgreSQL database instance:
# 1. Local execution with Docker Compose
docker compose up -d --build
# 2. Deploy to Render via Blueprint
Render Dashboard → New Blueprint → Select repo (Auto-provisions PostgreSQL + App)
# 3. Execute automated test suite
php vendor/bin/phpunit
6. Security Architecture, HIPAA & ISO 27001 Compliance
- Granular Least-Privilege Clinical Roles: Strict isolation between Doctors, Nurses, Pharmacists, Lab Techs, Receptionists, and Admins.
- Medical Staff Licensing Gate: Mandatory practicing license submission (`/staff/onboarding`) and Administrator verification before clinical data access.
- Mandatory First-Time Password Change: Forced password reset on administrator creation or reset (`/force-password-change`).
- Real-Time Anomaly & Sign-In Telemetry: Automated detection of brute-force login attempts and unrecognized IP address changes with instant transactional email alerts.
- Live UGMC Zoho SMTP Gateway: Secure encrypted transactional notifications delivered via SSL port 465 with hospital branding.
- Immutable Forensic Audit Trail: Append-only ledger recording every state mutation with SHA-256 integrity metadata.