Real-time clinic queue management system. Replace paper tokens with live visibility into waiting times for both reception staff and patients.
- Add patients with auto-generated daily token numbers
- View the live waiting queue (FIFO)
- Call Next — completes current consultation and advances the queue
- Configure average consultation time for ETA calculations
- Live statistics: current token, patients waiting, completed today, avg. consultation time
- Enter token number to track position
- See current token being served
- Patients ahead and estimated wait time
- Instant updates via Socket.IO (no page refresh)
- FIFO queue with single active consultation
- Real-time sync across all connected clients
- Duplicate patient detection (same name already waiting)
- Debounced Call Next to prevent rapid double-clicks
- Automatic socket reconnection
- Empty queue handling
- Loading and error states throughout
| Layer | Technologies |
|---|---|
| Frontend | React, Vite, Tailwind CSS, Socket.IO Client, React Router |
| Backend | Flask, Flask-SocketIO, SQLite |
queue-cure/
├── backend/
│ ├── app.py # Flask + SocketIO entry point
│ ├── config.py # Environment configuration
│ ├── extensions.py # Shared SocketIO instance
│ ├── requirements.txt
│ ├── models/
│ │ └── database.py # SQLite schema & connection
│ ├── routes/
│ │ └── api.py # REST API endpoints
│ ├── services/
│ │ └── queue_service.py # Queue business logic
│ └── socket_events/
│ └── handlers.py # WebSocket event handlers
├── frontend/
│ ├── src/
│ │ ├── api/ # HTTP client
│ │ ├── components/ # UI components
│ │ ├── hooks/ # useSocket, useQueue
│ │ ├── pages/ # Dashboard, WaitingRoom
│ │ └── utils/ # Formatting helpers
│ ├── package.json
│ └── vite.config.js
└── README.md
- Python 3.10+
- Node.js 18+
cd backend
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.pyThe API and WebSocket server start at http://localhost:5001.
In a separate terminal:
cd frontend
npm install
npm run devThe app opens at http://localhost:5173.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/health |
Health check |
| GET | /api/queue |
Full queue state + stats |
| POST | /api/patients |
Add patient { patient_name } |
| POST | /api/queue/call-next |
Advance queue |
| GET | /api/settings |
Get consultation time setting |
| PUT | /api/settings |
Update { average_consultation_time } |
| GET | /api/patients/:token/status |
Patient-specific wait info |
| Event | Direction | Payload |
|---|---|---|
connect |
Server → Client | Initial queue state |
request_queue_state |
Client → Server | Request fresh state |
queue_update |
Server → Client | Full queue snapshot |
| Variable | Default | Description |
|---|---|---|
PORT |
5001 |
Server port |
DATABASE_PATH |
./queue_cure.db |
SQLite file path |
DEFAULT_CONSULTATION_TIME |
15 |
Default avg. minutes |
CORS_ORIGINS |
http://localhost:5173 |
Comma-separated origins |
| Variable | Default | Description |
|---|---|---|
VITE_API_URL |
`` (uses Vite proxy) | REST API base URL |
VITE_SOCKET_URL |
http://localhost:5001 |
Socket.IO server |
- Reception opens the dashboard and sets average consultation time (e.g. 15 min).
- Add patients as they arrive — each gets a daily token number.
- Click Call Next when the doctor is ready — the first waiting patient moves to consultation.
- Patients open the Waiting Room, enter their token, and watch live updates.
- When the doctor finishes, click Call Next again — current patient is marked completed and the next patient is called.
MIT — built for hackathons and demos.