🎯 The Problem I Was Actually Solving

When I read the brief, the real problem wasn't "build a queue system." It was:

• A receptionist managing 50+ patients from memory, under pressure, with people shouting at her
• A patient with no idea if they'll wait 20 minutes or 2 hours — can't step out, can't plan, can't relax
• A doctor with no visibility into how many patients are left

The solution had to be zero-learning-curve for the receptionist (she's busy), zero-interaction for the patient (they just look at a screen), and real-time so both sides trust the same data.

💡 A clinic owner watching the demo sees the receptionist click "Call Next" on one screen — and before she lifts her finger, the number on the patient's phone has already changed. No refresh. No delay. No one touched the patient's phone. That's the moment she realizes this isn't a form — it's infrastructure.

⚡ Why Socket.io Over HTTP Polling

My first instinct was HTTP polling — hit /api/state every 2 seconds. Simple. But:

• 50 patients × 2s polling = 25 requests/second on a basic clinic Wi-Fi
• 2-second delay means the patient screen is always slightly behind
• "Call Next" click → patient sees update 0–2 seconds later, not instantly

Socket.io WebSocket gives instant push from server to all clients the moment state changes. The receptionist clicks "Call Next" → server emits queue_update → both screens update in under 100ms.

🏗️ Data Flow Decision — Single Source of Truth

I kept all state on the server, not split across clients. This was deliberate.

If I let clients hold their own state:

• What if two receptionists click "Call Next" at the same time?
• What if a client disconnects mid-operation?