# njoyc/queueless architecture

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

- Interactive diagram: https://gitdiagram.com/njoyc/queueless
- Repository: https://github.com/njoyc/queueless

## Overview

QueueLess serves customers booking appointments or joining FIFO service queues, while staff manage appointments and queue progression. The React client uses REST for application operations and a WebSocket for live queue changes; FastAPI routes implement domain operations, with JWT/role dependencies and SQLAlchemy persistence underneath. The graph includes the documented appointment and organization capabilities even where their implementation was not excerpted; those links are documented rather than inferred from unsampled code.

Main entry points: [`backend/app/db/database.py`](https://github.com/njoyc/queueless/blob/main/backend/app/db/database.py) (DB Sessions), [`frontend/src/App.jsx`](https://github.com/njoyc/queueless/blob/main/frontend/src/App.jsx) (App Router), [`frontend/src/services/api.js`](https://github.com/njoyc/queueless/blob/main/frontend/src/services/api.js) (REST Client), [`backend/app/main.py`](https://github.com/njoyc/queueless/blob/main/backend/app/main.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer and Staff Client"]
  node_app["App Router<br/>[App.jsx]"]
  node_authui["Auth Context<br/>[AuthContext.jsx]"]
  node_servicesui["Service Browser<br/>[Services.jsx]"]
  node_appointmentsui["Appointments UI<br/>[Appointments.jsx]"]
  node_customerui["Customer Dashboard"]
  node_queueui["Queue Status UI<br/>[QueuePage.jsx]"]
  node_staffui["Staff Dashboard<br/>[StaffDashboard.jsx]"]
  node_http["REST Client<br/>[api.js]"]
end

subgraph group_domain["Service Operations"]
  node_organizations["Organizations<br/>[organizations.py]"]
  node_services["Service Catalog<br/>[services.py]"]
  node_appointments["Appointment Booking<br/>[appointments.py]"]
  node_queue["Queue Operations<br/>[queue.py]"]
end

subgraph group_access["Identity and Access"]
  node_auth["Authentication API<br/>[auth.py]"]
  node_security["JWT and Roles<br/>[security.py]"]
  node_dependencies["Request Authorization<br/>[dependencies.py]"]
end

subgraph group_runtime["API and Persistence"]
  node_api["FastAPI App<br/>[main.py]"]
  node_dbsession["DB Sessions<br/>[database.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_wsmanager["WebSocket Manager"]
end

node_customer(("Customer"))
node_staff(("Staff"))
node_browser(("Browser"))

node_browser -->|"uses"| node_app
node_app -->|"uses"| node_authui
node_app -->|"routes to"| node_servicesui
node_app -->|"routes to"| node_appointmentsui
node_app -->|"routes to"| node_customerui
node_app -->|"routes to"| node_queueui
node_app -->|"routes to"| node_staffui
node_customer -->|"browses"| node_servicesui
node_staff -->|"operates"| node_staffui
node_servicesui -->|"requests"| node_http
node_appointmentsui -->|"requests"| node_http
node_customerui -->|"requests"| node_http
node_queueui -->|"requests"| node_http
node_staffui -->|"requests"| node_http
node_authui -->|"loads user"| node_http
node_http -->|"REST calls"| node_api
node_services -->|"reads organization"| node_organizations
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_organizations
node_api -->|"registers routes"| node_services
node_api -->|"registers routes"| node_appointments
node_api -->|"registers routes"| node_queue
node_auth -->|"hashes and signs"| node_security
node_auth -->|"queries and writes"| node_dbsession
node_appointments -->|"queries and writes"| node_dbsession
node_queue -->|"queries and writes"| node_dbsession
node_services -->|"queries and writes"| node_dbsession
node_organizations -->|"queries and writes"| node_dbsession
node_appointments -->|"checks access"| node_dependencies
node_queue -->|"checks access"| node_dependencies
node_services -->|"checks access"| node_dependencies
node_dependencies -->|"validates JWT"| node_security
node_dependencies -->|"loads user"| node_dbsession
node_dbsession -->|"sessions use"| node_models
node_dbsession -->|"persists data"| node_postgres
node_queue -->|"broadcasts updates"| node_wsmanager
node_queueui -.->|"receives live updates"| node_wsmanager

click node_app "https://github.com/njoyc/queueless/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/njoyc/queueless/blob/main/frontend/src/context/AuthContext.jsx"
click node_servicesui "https://github.com/njoyc/queueless/blob/main/frontend/src/pages/Services.jsx"
click node_appointmentsui "https://github.com/njoyc/queueless/blob/main/frontend/src/pages/Appointments.jsx"
click node_customerui "https://github.com/njoyc/queueless/blob/main/frontend/src/pages/CustomerDashboard.jsx"
click node_queueui "https://github.com/njoyc/queueless/blob/main/frontend/src/pages/QueuePage.jsx"
click node_staffui "https://github.com/njoyc/queueless/blob/main/frontend/src/pages/StaffDashboard.jsx"
click node_http "https://github.com/njoyc/queueless/blob/main/frontend/src/services/api.js"
click node_organizations "https://github.com/njoyc/queueless/blob/main/backend/app/api/organizations.py"
click node_services "https://github.com/njoyc/queueless/blob/main/backend/app/api/services.py"
click node_appointments "https://github.com/njoyc/queueless/blob/main/backend/app/api/appointments.py"
click node_queue "https://github.com/njoyc/queueless/blob/main/backend/app/api/queue.py"
click node_auth "https://github.com/njoyc/queueless/blob/main/backend/app/api/auth.py"
click node_security "https://github.com/njoyc/queueless/blob/main/backend/app/core/security.py"
click node_dependencies "https://github.com/njoyc/queueless/blob/main/backend/app/core/dependencies.py"
click node_api "https://github.com/njoyc/queueless/blob/main/backend/app/main.py"
click node_dbsession "https://github.com/njoyc/queueless/blob/main/backend/app/db/database.py"
click node_models "https://github.com/njoyc/queueless/blob/main/backend/app/db/models.py"
click node_wsmanager "https://github.com/njoyc/queueless/blob/main/backend/app/core/websocket_manager.py"

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_app,node_authui,node_servicesui,node_appointmentsui,node_customerui,node_queueui,node_staffui,node_http,node_browser toneBlue
class node_organizations,node_services,node_appointments,node_queue toneAmber
class node_auth,node_security,node_dependencies toneMint
class node_api,node_dbsession,node_models,node_postgres,node_wsmanager toneRose
class node_customer,node_staff toneIndigo
```

## Components

### Customer and Staff Client

- [App Router](https://github.com/njoyc/queueless/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth Context](https://github.com/njoyc/queueless/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Service Browser](https://github.com/njoyc/queueless/blob/main/frontend/src/pages/Services.jsx): `frontend/src/pages/Services.jsx`
- [Appointments UI](https://github.com/njoyc/queueless/blob/main/frontend/src/pages/Appointments.jsx): `frontend/src/pages/Appointments.jsx`
- [Customer Dashboard](https://github.com/njoyc/queueless/blob/main/frontend/src/pages/CustomerDashboard.jsx): `frontend/src/pages/CustomerDashboard.jsx`
- [Queue Status UI](https://github.com/njoyc/queueless/blob/main/frontend/src/pages/QueuePage.jsx): `frontend/src/pages/QueuePage.jsx`
- [Staff Dashboard](https://github.com/njoyc/queueless/blob/main/frontend/src/pages/StaffDashboard.jsx): `frontend/src/pages/StaffDashboard.jsx`
- [REST Client](https://github.com/njoyc/queueless/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Service Operations

- [Organizations](https://github.com/njoyc/queueless/blob/main/backend/app/api/organizations.py): `backend/app/api/organizations.py`
- [Service Catalog](https://github.com/njoyc/queueless/blob/main/backend/app/api/services.py): `backend/app/api/services.py`
- [Appointment Booking](https://github.com/njoyc/queueless/blob/main/backend/app/api/appointments.py): `backend/app/api/appointments.py`
- [Queue Operations](https://github.com/njoyc/queueless/blob/main/backend/app/api/queue.py): `backend/app/api/queue.py`

### Identity and Access

- [Authentication API](https://github.com/njoyc/queueless/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [JWT and Roles](https://github.com/njoyc/queueless/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Request Authorization](https://github.com/njoyc/queueless/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`

### API and Persistence

- [FastAPI App](https://github.com/njoyc/queueless/blob/main/backend/app/main.py): `backend/app/main.py`
- [DB Sessions](https://github.com/njoyc/queueless/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Domain Models](https://github.com/njoyc/queueless/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- **PostgreSQL**
- [WebSocket Manager](https://github.com/njoyc/queueless/blob/main/backend/app/core/websocket_manager.py): `backend/app/core/websocket_manager.py`

### Other components

- **Customer**
- **Staff**
- **Browser**

## Connections

- Browser → App Router: uses (evidence: `README.md`)
- App Router → Auth Context: uses (evidence: `frontend/src/App.jsx`)
- App Router → Service Browser: routes to (evidence: `frontend/src/App.jsx`)
- App Router → Appointments UI: routes to (evidence: `frontend/src/App.jsx`)
- App Router → Customer Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App Router → Queue Status UI: routes to (evidence: `frontend/src/App.jsx`)
- App Router → Staff Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Customer → Service Browser: browses (evidence: `README.md`)
- Staff → Staff Dashboard: operates (evidence: `README.md`)
- Service Browser → REST Client: requests (evidence: `frontend/src/pages/Services.jsx`)
- Appointments UI → REST Client: requests (evidence: `frontend/src/pages/Appointments.jsx`)
- Customer Dashboard → REST Client: requests (evidence: `frontend/src/pages/CustomerDashboard.jsx`)
- Queue Status UI → REST Client: requests (evidence: `frontend/src/pages/QueuePage.jsx`)
- Staff Dashboard → REST Client: requests (evidence: `frontend/src/pages/StaffDashboard.jsx`)
- Auth Context → REST Client: loads user (evidence: `frontend/src/context/AuthContext.jsx`)
- REST Client → FastAPI App: REST calls (evidence: `README.md`)
- Service Catalog → Organizations: reads organization (evidence: `backend/app/api/services.py`)
- FastAPI App → Authentication API: registers routes (evidence: `backend/app/main.py`)
- FastAPI App → Organizations: registers routes (evidence: `backend/app/main.py`)
- FastAPI App → Service Catalog: registers routes (evidence: `backend/app/main.py`)
- FastAPI App → Appointment Booking: registers routes (evidence: `backend/app/main.py`)
- FastAPI App → Queue Operations: registers routes (evidence: `backend/app/main.py`)
- Authentication API → JWT and Roles: hashes and signs (evidence: `backend/app/api/auth.py`)
- Authentication API → DB Sessions: queries and writes (evidence: `backend/app/api/auth.py`)
- Appointment Booking → DB Sessions: queries and writes (evidence: `backend/app/api/appointments.py`)
- Queue Operations → DB Sessions: queries and writes (evidence: `backend/app/api/queue.py`)
- Service Catalog → DB Sessions: queries and writes (evidence: `backend/app/api/services.py`)
- Organizations → DB Sessions: queries and writes (evidence: `backend/app/api/organizations.py`)
- Appointment Booking → Request Authorization: checks access (evidence: `backend/app/api/appointments.py`)
- Queue Operations → Request Authorization: checks access (evidence: `backend/app/api/queue.py`)
- Service Catalog → Request Authorization: checks access (evidence: `backend/app/api/services.py`)
- Request Authorization → JWT and Roles: validates JWT (evidence: `backend/app/core/dependencies.py`)
- Request Authorization → DB Sessions: loads user (evidence: `backend/app/core/dependencies.py`)
- DB Sessions → Domain Models: sessions use (evidence: `backend/app/db/database.py`)
- DB Sessions → PostgreSQL: persists data (evidence: `README.md`)
- Queue Operations → WebSocket Manager: broadcasts updates (evidence: `backend/app/api/queue.py`)
- Queue Status UI → WebSocket Manager: receives live updates (evidence: `README.md`)
