# ramjani09/waitora architecture

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

- Interactive diagram: https://gitdiagram.com/ramjani09/waitora
- Repository: https://github.com/ramjani09/waitora

## Overview

WAITORA lets visitors choose a service, join its virtual queue, and track ticket position and estimated wait; staff monitor queues and advance or clear tickets. The React app calls a FastAPI service, which delegates queue operations to a JSON-persisted store. The sampled sources confirm the app shell, API client, staff dashboard, ticket tracking, API handlers, and store behavior; join-form wiring and other unsampled page details are represented only at the documented subsystem level.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ramjani09/waitora/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/services/api.js`](https://github.com/ramjani09/waitora/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/pages/StaffDashboard.jsx`](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/StaffDashboard.jsx) (Staff dashboard), [`frontend/src/pages/QueueStatus.jsx`](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/QueueStatus.jsx) (Ticket status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_visitor["Visitor experience"]
  node_app["App shell<br/>[App.jsx]"]
  node_home["Home and services<br/>[Home.jsx]"]
  node_join["Join queue<br/>[JoinQueue.jsx]"]
  node_status["Ticket status<br/>[QueueStatus.jsx]"]
  node_ticket["Ticket display<br/>[QueueTicket.jsx]"]
  node_client_api["API client<br/>[api.js]"]
end

subgraph group_staff["Staff operations"]
  node_dashboard["Staff dashboard<br/>[StaffDashboard.jsx]"]
  node_queue_table["Queue controls"]
  node_stats["Queue statistics<br/>[StatCard.jsx]"]
end

subgraph group_backend["Queue API"]
  node_api["FastAPI handlers<br/>[main.py]"]
  node_schemas["API models<br/>[models.py]"]
end

subgraph group_state["Queue state"]
  node_store["Queue logic<br/>[store.py]"]
  node_json_state[("Persisted queue state<br/>[queue_state.json]")]
end

node_customer(("Visitor"))
node_staff_actor(("Staff member"))

node_customer -->|"uses"| node_app
node_staff_actor -->|"uses"| node_app
node_app -->|"renders"| node_home
node_app -->|"renders"| node_join
node_app -->|"renders"| node_status
node_app -->|"renders"| node_dashboard
node_home -->|"loads services"| node_client_api
node_join -->|"requests ticket"| node_client_api
node_status -->|"polls and leaves"| node_client_api
node_status -->|"displays ticket"| node_ticket
node_dashboard -->|"loads and updates"| node_client_api
node_dashboard -->|"renders controls"| node_queue_table
node_dashboard -->|"renders metrics"| node_stats
node_client_api -->|"HTTP requests"| node_api
node_api -->|"validates and shapes"| node_schemas
node_api -->|"dispatches operations"| node_store
node_store -->|"loads and saves"| node_json_state

click node_app "https://github.com/ramjani09/waitora/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/Home.jsx"
click node_join "https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/JoinQueue.jsx"
click node_status "https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/QueueStatus.jsx"
click node_ticket "https://github.com/ramjani09/waitora/blob/main/frontend/src/components/QueueTicket.jsx"
click node_client_api "https://github.com/ramjani09/waitora/blob/main/frontend/src/services/api.js"
click node_dashboard "https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/StaffDashboard.jsx"
click node_queue_table "https://github.com/ramjani09/waitora/blob/main/frontend/src/components/AdminQueueTable.jsx"
click node_stats "https://github.com/ramjani09/waitora/blob/main/frontend/src/components/StatCard.jsx"
click node_api "https://github.com/ramjani09/waitora/blob/main/backend/app/main.py"
click node_schemas "https://github.com/ramjani09/waitora/blob/main/backend/app/models.py"
click node_store "https://github.com/ramjani09/waitora/blob/main/backend/app/store.py"
click node_json_state "https://github.com/ramjani09/waitora/blob/main/backend/data/queue_state.json"

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_home,node_join,node_status,node_ticket,node_client_api toneBlue
class node_dashboard,node_queue_table,node_stats toneAmber
class node_api,node_schemas toneMint
class node_store,node_json_state toneRose
class node_customer,node_staff_actor toneIndigo
```

## Components

### Visitor experience

- [App shell](https://github.com/ramjani09/waitora/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Home and services](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Join queue](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/JoinQueue.jsx): `frontend/src/pages/JoinQueue.jsx`
- [Ticket status](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/QueueStatus.jsx): `frontend/src/pages/QueueStatus.jsx`
- [Ticket display](https://github.com/ramjani09/waitora/blob/main/frontend/src/components/QueueTicket.jsx): `frontend/src/components/QueueTicket.jsx`
- [API client](https://github.com/ramjani09/waitora/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Staff operations

- [Staff dashboard](https://github.com/ramjani09/waitora/blob/main/frontend/src/pages/StaffDashboard.jsx): `frontend/src/pages/StaffDashboard.jsx`
- [Queue controls](https://github.com/ramjani09/waitora/blob/main/frontend/src/components/AdminQueueTable.jsx): `frontend/src/components/AdminQueueTable.jsx`
- [Queue statistics](https://github.com/ramjani09/waitora/blob/main/frontend/src/components/StatCard.jsx): `frontend/src/components/StatCard.jsx`

### Queue API

- [FastAPI handlers](https://github.com/ramjani09/waitora/blob/main/backend/app/main.py): `backend/app/main.py`
- [API models](https://github.com/ramjani09/waitora/blob/main/backend/app/models.py): `backend/app/models.py`

### Queue state

- [Queue logic](https://github.com/ramjani09/waitora/blob/main/backend/app/store.py): `backend/app/store.py`
- [Persisted queue state](https://github.com/ramjani09/waitora/blob/main/backend/data/queue_state.json): `backend/data/queue_state.json`

### Other components

- **Visitor**
- **Staff member**

## Connections

- Visitor → App shell: uses
- Staff member → App shell: uses
- App shell → Home and services: renders
- App shell → Join queue: renders
- App shell → Ticket status: renders
- App shell → Staff dashboard: renders
- Home and services → API client: loads services
- Join queue → API client: requests ticket
- Ticket status → API client: polls and leaves
- Ticket status → Ticket display: displays ticket
- Staff dashboard → API client: loads and updates
- Staff dashboard → Queue controls: renders controls
- Staff dashboard → Queue statistics: renders metrics
- API client → FastAPI handlers: HTTP requests
- FastAPI handlers → API models: validates and shapes
- FastAPI handlers → Queue logic: dispatches operations
- Queue logic → Persisted queue state: loads and saves