# sridhar281/smartqueue architecture

> Architecture diagram of the GitHub repository sridhar281/smartqueue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sridhar281/smartqueue
- Repository: https://github.com/sridhar281/smartqueue

## Overview

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: [`backend/app/main.py`](https://github.com/sridhar281/smartqueue/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/queue_service.py`](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/queue_service.py) (Queue lifecycle), [`frontend/hooks/useQueueSocket.ts`](https://github.com/sridhar281/smartqueue/blob/main/frontend/hooks/useQueueSocket.ts) (Queue socket hook), [`frontend/lib/api.ts`](https://github.com/sridhar281/smartqueue/blob/main/frontend/lib/api.ts) (REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Customer and staff UI"]
  node_customer_ui["Customer pages"]
  node_admin_ui["Admin pages"]
  node_api_client["REST client<br/>[api.ts]"]
  node_socket_hook["Queue socket hook<br/>[useQueueSocket.ts]"]
end

subgraph group_api["HTTP and realtime API"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Auth endpoints<br/>[auth.py]"]
  node_service_api["Service endpoints<br/>[services.py]"]
  node_queue_api["Customer queue endpoints<br/>[queue.py]"]
  node_appointment_api["Appointment endpoints<br/>[appointments.py]"]
  node_admin_queue_api["Admin queue endpoints<br/>[admin_queue.py]"]
  node_counter_api["Counter endpoints<br/>[counters.py]"]
  node_analytics_api["Analytics endpoints<br/>[analytics.py]"]
  node_ws_api["WebSocket endpoint<br/>[ws.py]"]
end

subgraph group_domain["Queue and service rules"]
  node_queue_rules["Queue lifecycle<br/>[queue_service.py]"]
  node_wait_estimates["Wait estimation"]
  node_simulation["Staffing simulation"]
  node_socket_manager["Room broadcasts<br/>[manager.py]"]
  node_analytics["Analytics calculations"]
end

subgraph group_identity["Identity and access"]
  node_auth_service["Auth rules<br/>[auth_service.py]"]
  node_access_control["Request authorization<br/>[deps.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
end

subgraph group_storage["Persistence and reporting"]
  node_database_session["Database sessions<br/>[database.py]"]
  node_service_history[("Completed-service history<br/>[service_history.py]")]
  node_models[("Domain tables")]
end

node_customer(("Customer"))
node_staff(("Staff admin"))
node_postgres[("PostgreSQL")]

node_customer -->|"uses"| node_customer_ui
node_staff -->|"uses"| node_admin_ui
node_customer_ui -->|"requests REST"| node_api_client
node_admin_ui -->|"requests REST"| node_api_client
node_customer_ui -->|"subscribes live"| node_socket_hook
node_admin_ui -->|"subscribes live"| node_socket_hook
node_socket_hook -->|"refetches state"| node_api_client
node_api_client -->|"calls REST"| node_backend_app
node_socket_hook -->|"opens socket"| node_ws_api
node_backend_app -->|"registers router"| node_auth_api
node_backend_app -->|"registers router"| node_service_api
node_backend_app -->|"registers router"| node_queue_api
node_backend_app -->|"registers router"| node_admin_queue_api
node_backend_app -->|"registers router"| node_appointment_api
node_backend_app -->|"registers router"| node_counter_api
node_backend_app -->|"registers router"| node_analytics_api
node_backend_app -->|"registers router"| node_ws_api
node_auth_api -->|"calls"| node_auth_service
node_auth_service -->|"hashes and signs"| node_security
node_access_control -->|"decodes token"| node_security
node_auth_api -->|"uses dependencies"| node_access_control
node_queue_api -->|"calls"| node_queue_rules
node_appointment_api -->|"calls"| node_queue_rules
node_admin_queue_api -->|"calls"| node_queue_rules
node_service_api -->|"computes live waits"| node_wait_estimates
node_queue_rules -->|"calculates position and wait"| node_wait_estimates
node_admin_queue_api -->|"broadcasts changes"| node_socket_manager
node_appointment_api -->|"broadcasts changes"| node_socket_manager
node_queue_api -->|"broadcasts changes"| node_socket_manager
node_ws_api -->|"manages rooms"| node_socket_manager
node_analytics_api -->|"calls"| node_analytics
node_analytics_api -->|"calls simulation"| node_simulation
node_service_api -->|"uses session"| node_database_session
node_queue_rules -->|"writes completions"| node_service_history
node_wait_estimates -->|"reads durations"| node_service_history
node_analytics -.->|"reads history"| node_service_history
node_database_session -->|"connects"| node_postgres
node_models -->|"defines tables on"| node_database_session

click node_customer_ui "https://github.com/sridhar281/smartqueue/tree/main/frontend/app/(app)"
click node_admin_ui "https://github.com/sridhar281/smartqueue/tree/main/frontend/app/admin"
click node_api_client "https://github.com/sridhar281/smartqueue/blob/main/frontend/lib/api.ts"
click node_socket_hook "https://github.com/sridhar281/smartqueue/blob/main/frontend/hooks/useQueueSocket.ts"
click node_backend_app "https://github.com/sridhar281/smartqueue/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/auth.py"
click node_service_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/services.py"
click node_queue_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/queue.py"
click node_appointment_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/appointments.py"
click node_admin_queue_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/admin_queue.py"
click node_counter_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/counters.py"
click node_analytics_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/analytics.py"
click node_ws_api "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/ws.py"
click node_auth_service "https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/auth_service.py"
click node_access_control "https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/deps.py"
click node_security "https://github.com/sridhar281/smartqueue/blob/main/backend/app/core/security.py"
click node_queue_rules "https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/queue_service.py"
click node_wait_estimates "https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/waiting_time_service.py"
click node_simulation "https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/simulation_service.py"
click node_socket_manager "https://github.com/sridhar281/smartqueue/blob/main/backend/app/websocket/manager.py"
click node_analytics "https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/analytics_service.py"
click node_database_session "https://github.com/sridhar281/smartqueue/blob/main/backend/app/core/database.py"
click node_service_history "https://github.com/sridhar281/smartqueue/blob/main/backend/app/models/service_history.py"
click node_models "https://github.com/sridhar281/smartqueue/tree/main/backend/app/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_customer_ui,node_admin_ui,node_api_client,node_socket_hook toneBlue
class node_backend_app,node_auth_api,node_service_api,node_queue_api,node_appointment_api,node_admin_queue_api,node_counter_api,node_analytics_api,node_ws_api,node_postgres toneAmber
class node_queue_rules,node_wait_estimates,node_simulation,node_socket_manager,node_analytics toneMint
class node_auth_service,node_access_control,node_security toneRose
class node_database_session,node_service_history,node_models,node_customer,node_staff toneIndigo
```

## Components

### Customer and staff UI

- [Customer pages](https://github.com/sridhar281/smartqueue/tree/main/frontend/app/(app)): `frontend/app/(app)`
- [Admin pages](https://github.com/sridhar281/smartqueue/tree/main/frontend/app/admin): `frontend/app/admin`
- [REST client](https://github.com/sridhar281/smartqueue/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Queue socket hook](https://github.com/sridhar281/smartqueue/blob/main/frontend/hooks/useQueueSocket.ts): `frontend/hooks/useQueueSocket.ts`

### HTTP and realtime API

- [FastAPI application](https://github.com/sridhar281/smartqueue/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Service endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/services.py): `backend/app/api/services.py`
- [Customer queue endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/queue.py): `backend/app/api/queue.py`
- [Appointment endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/appointments.py): `backend/app/api/appointments.py`
- [Admin queue endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/admin_queue.py): `backend/app/api/admin_queue.py`
- [Counter endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/counters.py): `backend/app/api/counters.py`
- [Analytics endpoints](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [WebSocket endpoint](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/ws.py): `backend/app/api/ws.py`

### Queue and service rules

- [Queue lifecycle](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/queue_service.py): `backend/app/services/queue_service.py`
- [Wait estimation](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/waiting_time_service.py): `backend/app/services/waiting_time_service.py`
- [Staffing simulation](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Room broadcasts](https://github.com/sridhar281/smartqueue/blob/main/backend/app/websocket/manager.py): `backend/app/websocket/manager.py`
- [Analytics calculations](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/analytics_service.py): `backend/app/services/analytics_service.py`

### Identity and access

- [Auth rules](https://github.com/sridhar281/smartqueue/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Request authorization](https://github.com/sridhar281/smartqueue/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [JWT and passwords](https://github.com/sridhar281/smartqueue/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Persistence and reporting

- [Database sessions](https://github.com/sridhar281/smartqueue/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Completed-service history](https://github.com/sridhar281/smartqueue/blob/main/backend/app/models/service_history.py): `backend/app/models/service_history.py`
- [Domain tables](https://github.com/sridhar281/smartqueue/tree/main/backend/app/models): `backend/app/models`

### Other components

- **Customer**
- **Staff admin**
- **PostgreSQL**

## Connections

- Customer → Customer pages: uses (evidence: `README.md`)
- Staff admin → Admin pages: uses (evidence: `README.md`)
- Customer pages → REST client: requests REST (evidence: `README.md`)
- Admin pages → REST client: requests REST (evidence: `README.md`)
- Customer pages → Queue socket hook: subscribes live (evidence: `README.md`)
- Admin pages → Queue socket hook: subscribes live (evidence: `README.md`)
- Queue socket hook → REST client: refetches state (evidence: `README.md`)
- REST client → FastAPI application: calls REST (evidence: `README.md`)
- Queue socket hook → WebSocket endpoint: opens socket (evidence: `README.md`)
- FastAPI application → Auth endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Service endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Customer queue endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Admin queue endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Appointment endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Counter endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Analytics endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → WebSocket endpoint: registers router (evidence: `backend/app/main.py`)
- Auth endpoints → Auth rules: calls (evidence: `backend/app/api/auth.py`)
- Auth rules → JWT and passwords: hashes and signs (evidence: `backend/app/services/auth_service.py`)
- Request authorization → JWT and passwords: decodes token (evidence: `backend/app/api/deps.py`)
- Auth endpoints → Request authorization: uses dependencies (evidence: `backend/app/api/auth.py`)
- Customer queue endpoints → Queue lifecycle: calls (evidence: `backend/app/api/queue.py`)
- Appointment endpoints → Queue lifecycle: calls (evidence: `backend/app/api/appointments.py`)
- Admin queue endpoints → Queue lifecycle: calls (evidence: `backend/app/api/admin_queue.py`)
- Service endpoints → Wait estimation: computes live waits (evidence: `backend/app/api/services.py`)
- Queue lifecycle → Wait estimation: calculates position and wait (evidence: `backend/app/services/queue_service.py`)
- Admin queue endpoints → Room broadcasts: broadcasts changes (evidence: `backend/app/api/admin_queue.py`)
- Appointment endpoints → Room broadcasts: broadcasts changes (evidence: `backend/app/api/appointments.py`)
- Customer queue endpoints → Room broadcasts: broadcasts changes (evidence: `backend/app/api/queue.py`)
- WebSocket endpoint → Room broadcasts: manages rooms (evidence: `backend/app/api/ws.py`)
- Analytics endpoints → Analytics calculations: calls (evidence: `backend/app/api/analytics.py`)
- Analytics endpoints → Staffing simulation: calls simulation (evidence: `backend/app/api/analytics.py`)
- Service endpoints → Database sessions: uses session (evidence: `backend/app/api/services.py`)
- Queue lifecycle → Completed-service history: writes completions (evidence: `backend/app/services/queue_service.py`)
- Wait estimation → Completed-service history: reads durations (evidence: `backend/app/models/service_history.py`)
- Analytics calculations → Completed-service history: reads history (evidence: `README.md`)
- Database sessions → PostgreSQL: connects (evidence: `backend/app/core/database.py`)
- Domain tables → Database sessions: defines tables on (evidence: `backend/app/models/service_history.py`)
