QueueLess 🎟️

Smart Virtual Queue & Customer Flow Management Ecosystem
Eliminate physical lines with remote queuing, live ticket tracking, rolling-average wait estimations, staff counter terminals, and lobby displays.

---

📌 Executive Summary

Long physical queues at service counters (hospitals, banks, clinics, embassies, universities, and service centers) lead to overcrowding, customer fatigue, and inefficient counter utilization.

QueueLess is an enterprise-ready, cross-platform queue management system that virtualizes customer queues into real-time digital streams. Customers join queues remotely, monitor estimated wait times live on their devices, and arrive just in time for their appointment—while staff and administrators manage counter workflows with real-time throughput analytics.

---

🌟 Core Personas & Features

1. 📱 Customer Mobile App

• Remote Queue Entry: Browse nearby branches, view live counter wait times, and join virtual queues before stepping out.
• Live Ticket Tracking: Real-time Firestore stream displaying ticket number (A042), currently serving number (A035), ahead count (#6), and dynamic wait time (~18 mins).
• Instant QR Check-in: Scan on-site QR codes using the built-in scanner (mobile_scanner) to claim instant digital tickets.
• Digital Pass & QR Code: Generate high-fidelity pass codes (qr_flutter) for rapid verification at the counter.
• Smart Estimation Algorithm: Rolling-average engine accounting for historical durations, staff count, and peak-hour velocity.
• Proactive Push Alerts: FCM notification triggers when a customer is 5 away, 3 away, or called to a specific counter.
• Queue History & Feedback: View past tickets, time spent, and submit 5-star branch ratings.

2. 👨‍💼 Staff Counter Terminal

• Counter Dispatch Controls: One-tap Call Next, Recall, Start Service, Complete, or Skip / Absent.
• Timestamp Analytics: Auto-records calledAt, serviceStartedAt, and completedAt to feed the wait-time estimation engine.
• Counter Pausing: Suspend dispatching during breaks or counter transfers without disrupting the overarching queue order.

3. 🏢 Organization Admin & Business Intelligence

• Real-Time KPIs: Track total footfall, completion rates, cancellation percentages, and average service durations across all counters.
• Interactive Data Visualization: Peak volume and completion breakdown powered by fl_chart.
• Branch & Service Management: CRUD operations for branch networks, departments, prefix codes (A-, C-, L-), and counter capacity.
• Role-Based Access Control (RBAC): Secure privilege tiering between Customers, Staff Members, and Branch Administrators.

4. 📺 Lobby TV Display Board

• Public Queue Board: Dedicated landscape kiosk mode displaying currently served tickets and assigned counter numbers in large, high-contrast typography for waiting room displays.

---

🏛️ System Architecture

QueueLess is engineered following Feature-Driven Clean Architecture and reactive state management principles:

lib/
├── core/
│   ├── constants/             # Design tokens, color system, Firestore collection names
│   ├── errors/                # Centralized domain Failure & Exception wrappers
│   ├── localization/          # Multi-language support (English, Sinhala, Tamil)
│   ├── routing/               # GoRouter configuration with role-based route guards
│   ├── services/              # Mock & Live Firebase service providers
│   ├── theme/                 # Material 3 Light & Dark mode themes
│   └── utils/                 # QueueEstimationService, DateFormatters
│
├── features/
│   ├── admin/                 # Branch/Service management, Staff roster, Analytics dashboard
│   ├── authentication/        # Dual-mode Auth (Firebase Auth + Mock Dev Provider)
│   ├── customer/              # Home explore, Live queue tracker, Digital pass, History
│   ├── organization/          # Organization data repository & branch models
│   ├── queue/                 # Real-time ticket lifecycle management & state
│   ├── shared/                # Universal domain models (AppUser, Branch, QueueTicket)
│   └── staff/                 # Counter dispatching terminal & queue controls
│
└── main.dart                  # Application entry point & Riverpod Scope initialization

---

📊 Wait-Time Estimation Formula

QueueLess computes dynamic wait times using an adaptive rolling-average formula:

$$\text{Estimated Wait} = \frac{\text{Ahead In Queue} \times \text{Average Service Duration}}{\max(\text{Active Staff Counters}, 1)}$$

Where:

• Ahead in Queue: Number of tickets with status == TicketStatus.waiting created prior to the user's ticket.
• Average Service Duration: Rolling average of the last $N$ completed tickets for that specific service type.
• Active Staff Counters: Number of authenticated counters currently in active state.

---

⚡ Tech Stack & Libraries

Category	Technology
Framework	Flutter (v3.44+) / Dart (v3.12+)
Design System	Material 3 Design with custom high-contrast dark/light tokens
State Management	flutter_riverpod (v3.4+)
Routing	go_router with strict Auth & Role guards
Backend & Database	Firebase Authentication, Cloud Firestore, Firebase Cloud Messaging
Cloud Functions	Node.js Serverless Atomic Transactions (functions/index.js)
Charts & Analytics	fl_chart
QR Code Engine	qr_flutter & mobile_scanner
Typography	google_fonts (Inter / Outfit)

---

🔒 Security & Concurrency Control

• Cloud Firestore Rules (firestore.rules): Granular security rules enforcing role boundaries. Customers can only view and cancel their own tickets; only staff members can update ticket statuses to inProgress or completed.
• Atomic Concurrency Handling (functions/index.js): Server-side Firestore transactions guarantee ticket numbers (#A001, #A002) remain strictly sequential and collision-free even under peak simultaneous requests.

---

🚀 Getting Started

Prerequisites

• Flutter SDK ^3.44.0 or higher
• Dart SDK ^3.12.0 or higher
• Git installed

1. Clone the Repository

git clone https://github.com/Kavi20021026/queueless.git
cd queueless

2. Install Dependencies

flutter pub get

3. Run Automated Tests

flutter test

4. Launch Application

# Run on Web
flutter run -d chrome

# Run on Android / iOS
flutter run

# Run on Windows Desktop
flutter run -d windows

---

🧪 Testing

Comprehensive unit tests validate the algorithmic wait-time estimation engine and repository layer:

flutter test test/core/queue_estimation_test.dart
flutter test test/core/queue_repository_test.dart

---

📄 License

Distributed under the MIT License. See LICENSE for complete details.

---

👨‍💻 Author

Kavindu Dissanayaka
Full-Stack & Mobile Software Engineer

• GitHub: @Kavi20021026
• Project Link: https://github.com/Kavi20021026/queueless