# ishh-g/queuelock architecture

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

- Interactive diagram: https://gitdiagram.com/ishh-g/queuelock
- Repository: https://github.com/ishh-g/queuelock

## Overview

QueueLock is a multi-package virtual queue for clinics and small businesses: customers join by QR code and nickname, follow a live ticket and wait estimate, while staff call customers across counters; a public audit log supports fairness checks. The Flutter app uses the generated Serverpod client to reach thin server endpoints, with queue and ledger services holding domain logic and PostgreSQL-backed state. The README and tree establish these product capabilities and broad package boundaries; sampled source does not include the Dart runtime implementation, so detailed call wiring is intentionally omitted.

Main entry points: [`queuelock_client/lib/queuelock_client.dart`](https://github.com/ishh-g/queuelock/blob/main/queuelock_client/lib/queuelock_client.dart) (Generated client), [`queuelock_server/lib/src/endpoints/queue_endpoint.dart`](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/queue_endpoint.dart) (Queue endpoints), [`queuelock_server/lib/src/services/queue_service.dart`](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/queue_service.dart) (Queue service), [`queuelock_server/migrations`](https://github.com/ishh-g/queuelock/tree/main/queuelock_server/migrations) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flutter application"]
  node_flutter["Flutter app<br/>[main.dart]"]
  node_join["Join queue<br/>[join_screen.dart]"]
  node_ticket["Live ticket<br/>[ticket_screen.dart]"]
  node_staff_ui["Staff dashboard<br/>[staff_screen.dart]"]
  node_dashboard["Queue dashboard"]
  node_audit_ui["Public audit<br/>[audit_screen.dart]"]
  node_client["Generated client"]
end

subgraph group_server["Server API"]
  node_server_entry["Server entry<br/>[server.dart]"]
  node_endpoints["Queue endpoints"]
  node_admin["Admin endpoints"]
  node_audit["Audit endpoint"]
  node_auth["Authentication"]
end

subgraph group_domain["Queue domain"]
  node_queue_service["Queue service<br/>[queue_service.dart]"]
  node_estimator["Wait estimator<br/>[estimator.dart]"]
  node_ledger_service["Ledger service"]
  node_ticket_tokens["Ticket tokens<br/>[ticket_tokens.dart]"]
  node_future_calls["Timeout and sweep"]
end

subgraph group_persistence["State and storage"]
  node_database[("PostgreSQL")]
end

node_customer(("Customer"))
node_staff(("Staff"))

node_customer -->|"joins via QR"| node_join
node_join -->|"submits join"| node_client
node_ticket -->|"loads ticket"| node_client
node_staff -->|"manages queue"| node_staff_ui
node_staff -->|"monitors counters"| node_dashboard
node_staff_ui -->|"sends actions"| node_client
node_customer -->|"checks fairness"| node_audit_ui
node_audit_ui -->|"requests audit"| node_client
node_client -->|"calls API"| node_endpoints
node_client -->|"calls API"| node_admin
node_client -->|"calls API"| node_audit
node_client -->|"authenticates"| node_auth
node_server_entry -->|"registers endpoints"| node_endpoints
node_endpoints -->|"delegates queue logic"| node_queue_service
node_admin -->|"delegates administration"| node_queue_service
node_audit -->|"delegates audit"| node_ledger_service
node_endpoints -->|"uses service history"| node_estimator
node_endpoints -->|"uses ticket tokens"| node_ticket_tokens
node_queue_service -->|"reads and writes"| node_database
node_ledger_service -->|"reads and writes"| node_database
node_future_calls -->|"handles expiry"| node_queue_service
node_future_calls -->|"sweeps expired rows"| node_database

click node_flutter "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/main.dart"
click node_join "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/join_screen.dart"
click node_ticket "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/ticket_screen.dart"
click node_staff_ui "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/staff_screen.dart"
click node_dashboard "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/dashboard_screen.dart"
click node_audit_ui "https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/audit_screen.dart"
click node_client "https://github.com/ishh-g/queuelock/blob/main/queuelock_client/lib/queuelock_client.dart"
click node_server_entry "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/server.dart"
click node_endpoints "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/queue_endpoint.dart"
click node_admin "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/admin_endpoint.dart"
click node_audit "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/audit_endpoint.dart"
click node_auth "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/auth/email_idp_endpoint.dart"
click node_queue_service "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/queue_service.dart"
click node_estimator "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/estimator.dart"
click node_ledger_service "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/ledger_service.dart"
click node_ticket_tokens "https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/ticket_tokens.dart"
click node_future_calls "https://github.com/ishh-g/queuelock/tree/main/queuelock_server/lib/src/future_calls"
click node_database "https://github.com/ishh-g/queuelock/tree/main/queuelock_server/migrations"

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_flutter,node_join,node_ticket,node_staff_ui,node_dashboard,node_audit_ui,node_client toneBlue
class node_server_entry,node_endpoints,node_admin,node_audit,node_auth toneAmber
class node_queue_service,node_estimator,node_ledger_service,node_ticket_tokens,node_future_calls toneMint
class node_database toneRose
class node_customer,node_staff toneIndigo
```

## Components

### Flutter application

- [Flutter app](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/main.dart): `queuelock_flutter/lib/main.dart`
- [Join queue](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/join_screen.dart): `queuelock_flutter/lib/screens/join_screen.dart`
- [Live ticket](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/ticket_screen.dart): `queuelock_flutter/lib/screens/ticket_screen.dart`
- [Staff dashboard](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/staff_screen.dart): `queuelock_flutter/lib/screens/staff_screen.dart`
- [Queue dashboard](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/dashboard_screen.dart): `queuelock_flutter/lib/screens/dashboard_screen.dart`
- [Public audit](https://github.com/ishh-g/queuelock/blob/main/queuelock_flutter/lib/screens/audit_screen.dart): `queuelock_flutter/lib/screens/audit_screen.dart`
- [Generated client](https://github.com/ishh-g/queuelock/blob/main/queuelock_client/lib/queuelock_client.dart): `queuelock_client/lib/queuelock_client.dart`

### Server API

- [Server entry](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/server.dart): `queuelock_server/lib/server.dart`
- [Queue endpoints](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/queue_endpoint.dart): `queuelock_server/lib/src/endpoints/queue_endpoint.dart`
- [Admin endpoints](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/admin_endpoint.dart): `queuelock_server/lib/src/endpoints/admin_endpoint.dart`
- [Audit endpoint](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/endpoints/audit_endpoint.dart): `queuelock_server/lib/src/endpoints/audit_endpoint.dart`
- [Authentication](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/auth/email_idp_endpoint.dart): `queuelock_server/lib/src/auth/email_idp_endpoint.dart`

### Queue domain

- [Queue service](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/queue_service.dart): `queuelock_server/lib/src/services/queue_service.dart`
- [Wait estimator](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/estimator.dart): `queuelock_server/lib/src/services/estimator.dart`
- [Ledger service](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/ledger_service.dart): `queuelock_server/lib/src/services/ledger_service.dart`
- [Ticket tokens](https://github.com/ishh-g/queuelock/blob/main/queuelock_server/lib/src/services/ticket_tokens.dart): `queuelock_server/lib/src/services/ticket_tokens.dart`
- [Timeout and sweep](https://github.com/ishh-g/queuelock/tree/main/queuelock_server/lib/src/future_calls): `queuelock_server/lib/src/future_calls`

### State and storage

- [PostgreSQL](https://github.com/ishh-g/queuelock/tree/main/queuelock_server/migrations): `queuelock_server/migrations`

### Other components

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

## Connections

- Customer → Join queue: joins via QR
- Join queue → Generated client: submits join
- Live ticket → Generated client: loads ticket
- Staff → Staff dashboard: manages queue
- Staff → Queue dashboard: monitors counters
- Staff dashboard → Generated client: sends actions
- Customer → Public audit: checks fairness
- Public audit → Generated client: requests audit
- Generated client → Queue endpoints: calls API
- Generated client → Admin endpoints: calls API
- Generated client → Audit endpoint: calls API
- Generated client → Authentication: authenticates
- Server entry → Queue endpoints: registers endpoints
- Queue endpoints → Queue service: delegates queue logic
- Admin endpoints → Queue service: delegates administration
- Audit endpoint → Ledger service: delegates audit
- Queue endpoints → Wait estimator: uses service history
- Queue endpoints → Ticket tokens: uses ticket tokens
- Queue service → PostgreSQL: reads and writes
- Ledger service → PostgreSQL: reads and writes
- Timeout and sweep → Queue service: handles expiry
- Timeout and sweep → PostgreSQL: sweeps expired rows