SilentQueue Pro

Productivity

Original Idea

Waiting Room Queue Display A self-hosted kiosk app for clinics, salons, and service centers that shows real-time queue position and estimated wait without requiring patient names.

Product Requirements Document (PRD): SilentQueue Pro

1. Executive Summary

SilentQueue Pro is a self-hosted, privacy-first queue management solution designed for high-traffic service environments such as medical clinics, salons, and government centers. By utilizing anonymous alphanumeric tokens and real-time WebSocket updates, the platform eliminates the need for displaying sensitive patient names while reducing wait-time anxiety through dynamic, history-based ETA calculations. The system is designed to run on low-cost local hardware (e.g., Raspberry Pi 4) to ensure 100% uptime even during internet outages.

2. Problem Statement

Waiting room environments face two primary friction points:

  1. Privacy Risks: Displaying full names on screens violates confidentiality standards (e.g., HIPAA, GDPR) and makes clients feel exposed.
  2. Wait-Time Anxiety: A lack of transparency regarding "where am I in line?" leads to frustrated clients and higher perceived wait times, even if the actual wait is short.

3. Goals & Success Metrics

  • Privacy Compliance: 0% storage or display of Personally Identifiable Information (PII).
  • Wait-Time Accuracy: Predicted ETAs should be within +/- 15% of actual wait times using Rolling Average Service Time (AST) algorithms.
  • System Latency: <200ms delay between a staff member "calling" a ticket and the kiosk display updating.
  • Operational Uptime: 99.9% availability within the local network, independent of external internet connectivity.

4. User Personas

  • The Clinic Admin: Needs to configure service types (e.g., "Vaccination" vs "Consultation") and monitor daily throughput.
  • The Desk Staff: Needs a fast, one-click interface to call the next patient or handle "no-shows."
  • The Waiting Client: Needs a clear, high-contrast visual display that confirms their token is in the system and moving forward.

5. User Stories

  • As a Staff Member, I want to click a "Next" button so that the system automatically selects the next ticket based on priority and time of arrival.
  • As a Client, I want to see my alphanumeric code (e.g., B-44) on a large screen so that I know exactly how many people are ahead of me.
  • As an Admin, I want the system to calculate wait times based on the last 5 served patients so that the displayed ETA is realistic for current staffing levels.
  • As a Patient, I want to hear an audio chime and see my number flash when it is my turn so that I don't miss my appointment if I am not looking at the screen.

6. Functional Requirements

6.1 Token Generation & Queue Management

  • Alphanumeric Logic: Tickets generated with prefixes (e.g., A- for Doctor, B- for Lab) to avoid semantic leakage.
  • Multi-Queue Support: Ability to handle multiple service categories simultaneously on a single display.
  • Staff Controls: Buttons for "Call Next," "Recall," "No-Show (Skip)," and "On Hold."

6.2 Display & Analytics

  • Real-time Dashboard: A "Now Serving" hero section and an "Up Next" scrolling list.
  • Dynamic ETA: Uses a Rolling Average Service Time (AST) with Exponential Smoothing to update wait times every time a ticket is completed.
  • Daily Reset: Automatic or manual purging of ticket data at the end of the business day.

6.3 Hardware & Alerts

  • ESC/POS Printing: Integration with local thermal printers for physical ticket dispensing.
  • Chime-then-Speech Alerts: Web Audio API plays a "ping," followed by Web Speech API announcing the ticket number.

7. Technical Requirements

7.1 Tech Stack (2026 Hardened)

  • Backend: Node.js v24.13.0 (Krypton LTS) using better-sqlite3 for high-concurrency local storage.
  • Frontend: React v19.2.3 with Tailwind CSS v4.1.18 (Oxide Engine).
  • Real-time: Socket.io v4.8.3 for bi-directional communication.
  • Animation: Framer Motion for shared element transitions (LayoutId) during ticket movement.
  • Deployment: Dockerized container using Raspberry Pi OS Lite + Openbox for a minimalist kiosk GUI.

7.2 Core Optimizations

  • Database: SQLite enabled with Write-Ahead Logging (WAL) mode and PRAGMA synchronous = NORMAL for high-frequency concurrent writes.
  • Low Latency: Use of binary frames (MessagePack) for WebSocket communication to reduce CPU overhead on ARM hardware.

8. Data Model

Entity: Ticket

  • id: UUID
  • token_code: String (e.g., "A-102")
  • service_type_id: ForeignKey
  • status: Enum (waiting, calling, serving, completed, cancelled)
  • created_at: Timestamp
  • called_at: Timestamp
  • completed_at: Timestamp

Entity: ServiceType

  • id: UUID
  • name: String (e.g., "General Checkup")
  • prefix: String (e.g., "G")
  • color_theme: String (Hex code)

9. API Specification (Key Endpoints)

  • POST /api/tickets/issue: Create a new ticket. Returns token_code and estimated_wait.
  • POST /api/tickets/call-next: (Staff only) Moves the highest priority waiting ticket to calling status. Triggers WebSocket broadcast.
  • PATCH /api/tickets/:id/status: Update status to completed or no-show.
  • GET /api/queue/status: Returns current state of all active queues for the dashboard.

10. UI/UX Requirements

  • "Urgency without Anxiety": Use a neutral color palette (Slate/Blue) with a single vibrant accent for the "Now Serving" number.
  • Framer Motion Transitions: Tickets should "slide" from the "Up Next" list into the "Now Serving" slot using a layoutId spring animation (stiffness: 300, damping: 30).
  • Kiosk Mode: The display UI must be responsive and designed for 1080p/4K TV screens with large, legible typography.

11. Non-Functional Requirements

  • Privacy by Design: No name entry fields in the database schema.
  • Offline Capability: System must function on a local subnet using a local DNS (e.g., silentqueue.local) without an internet gateway.
  • Accessibility: ARIA-live regions for all screen updates; high-contrast mode for visually impaired users.

12. Out of Scope

  • Online appointment scheduling or calendar integration.
  • Patient medical record (EMR) storage.
  • Payment or billing processing.
  • Native iOS/Android mobile apps (PWA only).

13. Risks & Mitigations

  • Risk: Browser autoplay policies block audio alerts.
    • Mitigation: Require a "Start System" interaction on staff/kiosk startup to unlock the AudioContext.
  • Risk: Sudden power loss corrupts the SQLite database.
    • Mitigation: Use WAL mode and implement automated daily backups to an internal NAS or SD card partition.
  • Risk: IP address changes break the kiosk connection.
    • Mitigation: Document and provide a script for setting a Static IP or local mDNS via avahi.

14. Implementation Tasks

Phase 1: Project Setup & Hardening

  • [ ] Initialize Node.js v24.13.0 project with ESM support
  • [ ] Install React v19.2.3 and Tailwind CSS v4.1.18
  • [ ] Configure Dockerfile for Raspberry Pi 4 (linux/arm64)
  • [ ] Setup better-sqlite3 with Write-Ahead Logging (WAL) mode

Phase 2: Core Backend & Logic

  • [ ] Create database schema for Tickets and ServiceTypes
  • [ ] Implement Rolling Average Service Time (AST) algorithm for ETA calculation
  • [ ] Setup Socket.io v4.8.3 with binary frame support
  • [ ] Build API endpoints for ticket lifecycle (Issue, Call, Complete)

Phase 3: Staff & Kiosk Frontend

  • [ ] Build Staff Controller UI (One-click "Call Next" functionality)
  • [ ] Build Kiosk Display UI with Hero/List split view
  • [ ] Integrate Framer Motion for "Now Serving" transitions
  • [ ] Implement "Chime-then-Speech" notification manager

Phase 4: Hardware & Offline Deployment

  • [ ] Implement node-thermal-printer integration via TCP/IP (Port 9100)
  • [ ] Configure local DNSmasq for silentqueue.local routing
  • [ ] Create Chromium "Auto-launch" script for kiosk mode
  • [ ] Conduct "Internet Disconnect" stress test to verify offline resilience