How sridhar281/smartqueue works
SmartQueue replaces paper queues with customer-facing digital tokens and appointments, plus staff tools for operating counters and monitoring service performance. Customers browse a service, join its queue or book an appointment, then track position and wait estimates; staff call and complete tokens, producing history used for estimates and analytics. The README documents REST plus WebSocket updates, with REST refetches as the source of truth. Some frontend wiring and unsampled subsystem internals are not shown, so those links rely only on documented behavior.
Main entry points: main.py FastAPI application · queue_service.py Queue lifecycle · useQueueSocket.ts Queue socket hook · api.ts REST client
Components 27
Customer and staff UI
- Customer pages
frontend/app/(app) - Admin pages
frontend/app/admin - REST client
frontend/lib/api.ts - Queue socket hook
frontend/hooks/useQueueSocket.ts
HTTP and realtime API
- FastAPI application
backend/app/main.py - Auth endpoints
backend/app/api/auth.py - Service endpoints
backend/app/api/services.py - Customer queue endpoints
backend/app/api/queue.py - Appointment endpoints
backend/app/api/appointments.py - Admin queue endpoints
backend/app/api/admin_queue.py - Counter endpoints
backend/app/api/counters.py - Analytics endpoints
backend/app/api/analytics.py - WebSocket endpoint
backend/app/api/ws.py
Queue and service rules
- Queue lifecycle
backend/app/services/queue_service.py - Wait estimation
backend/app/services/waiting_time_service.py - Staffing simulation
backend/app/services/simulation_service.py - Room broadcasts
backend/app/websocket/manager.py - Analytics calculations
backend/app/services/analytics_service.py
Identity and access
- Auth rules
backend/app/services/auth_service.py - Request authorization
backend/app/api/deps.py - JWT and passwords
backend/app/core/security.py
Persistence and reporting
- Database sessions
backend/app/core/database.py - Completed-service history
backend/app/models/service_history.py - Domain tables
backend/app/models
Other components
- Customer
- Staff admin
- PostgreSQL
Connections 38
- Customer → Customer pages: uses
README.md - Staff admin → Admin pages: uses
README.md - Customer pages → REST client: requests REST
README.md - Admin pages → REST client: requests REST
README.md - Customer pages → Queue socket hook: subscribes live
README.md - Admin pages → Queue socket hook: subscribes live
README.md - Queue socket hook → REST client: refetches state
README.md - REST client → FastAPI application: calls REST
README.md - Queue socket hook → WebSocket endpoint: opens socket
README.md - FastAPI application → Auth endpoints: registers router
backend/app/main.py - FastAPI application → Service endpoints: registers router
backend/app/main.py - FastAPI application → Customer queue endpoints: registers router
backend/app/main.py - FastAPI application → Admin queue endpoints: registers router
backend/app/main.py - FastAPI application → Appointment endpoints: registers router
backend/app/main.py - FastAPI application → Counter endpoints: registers router
backend/app/main.py - FastAPI application → Analytics endpoints: registers router
backend/app/main.py - FastAPI application → WebSocket endpoint: registers router
backend/app/main.py - Auth endpoints → Auth rules: calls
backend/app/api/auth.py - Auth rules → JWT and passwords: hashes and signs
backend/app/services/auth_service.py - Request authorization → JWT and passwords: decodes token
backend/app/api/deps.py - Auth endpoints → Request authorization: uses dependencies
backend/app/api/auth.py - Customer queue endpoints → Queue lifecycle: calls
backend/app/api/queue.py - Appointment endpoints → Queue lifecycle: calls
backend/app/api/appointments.py - Admin queue endpoints → Queue lifecycle: calls
backend/app/api/admin_queue.py - Service endpoints → Wait estimation: computes live waits
backend/app/api/services.py - Queue lifecycle → Wait estimation: calculates position and wait
backend/app/services/queue_service.py - Admin queue endpoints → Room broadcasts: broadcasts changes
backend/app/api/admin_queue.py - Appointment endpoints → Room broadcasts: broadcasts changes
backend/app/api/appointments.py - Customer queue endpoints → Room broadcasts: broadcasts changes
backend/app/api/queue.py - WebSocket endpoint → Room broadcasts: manages rooms
backend/app/api/ws.py - Analytics endpoints → Analytics calculations: calls
backend/app/api/analytics.py - Analytics endpoints → Staffing simulation: calls simulation
backend/app/api/analytics.py - Service endpoints → Database sessions: uses session
backend/app/api/services.py - Queue lifecycle → Completed-service history: writes completions
backend/app/services/queue_service.py - Wait estimation → Completed-service history: reads durations
backend/app/models/service_history.py - Analytics calculations → Completed-service history: reads history
README.md - Database sessions → PostgreSQL: connects
backend/app/core/database.py - Domain tables → Database sessions: defines tables on
backend/app/models/service_history.py