A Queue Management System (QMS) is designed to organize customer flow, reduce waiting chaos, and improve service efficiency. Instead of standing in messy lines, customers receive a digital token, wait comfortably, and get called automatically when it's their turn.

The system connects four key components into one smooth experience:

• Admin Dashboard (control center)
• Kiosk (customer entry point)
• Service Panel (staff workspace)
• Serial Display (public queue screen)

Everything works together in real-time.

Understanding the Building Blocks

• Company: The top-level organization. Think of it as the umbrella that holds everything together—your entire business entity.
• Branch: A physical location under your company (e.g., Downtown Office, Airport Branch). Most data—services, counters, tokens—is scoped by branch, so each location operates independently while staying connected to the central system.
• Service: A queue type that customers take tokens for (e.g., Billing, Registration, Support, Consultation). Services live under a branch and define what kind of help customers need.
• Counter: A service point (desk) where staff calls and serves customers. Each counter can handle one or multiple services depending on your setup.
• Token: A digital ticket issued to a customer for a specific service. Tokens move through statuses: waiting → called/serving → served/no-show/cancelled/transferred. This lifecycle tracking ensures accurate reporting and smooth operations.
• Devices: Kiosk, Display, and Printer entries configured in the system. Each device has specific behavior and access controls, allowing you to manage hardware across multiple branches from one dashboard.

Most Queue Management Systems follow the same core model: customers are issued a ticket (token), wait in a service queue, get called to a counter, then the visit is completed (or handled as an exception such as no-show or transfer).

Let's walk through the complete journey step by step:

1. Customer Arrives → Uses Kiosk

The journey starts at the Kiosk.

Customer selects:

• Service Category (e.g., Emergency & Trauma, Diagnostic & Imaging, Surgical Services)
• Service (e.g., Accident & Emergency, Ambulance Services, ICU, Burn Unit)
• User Details (Name, Phone, Email) (optional)
• Print Token (optional)

Then the system:

• Generates a unique token number
• Prints ticket or shows digital confirmation
• Adds the customer to the live queue

Goal: Zero confusion, zero staff involvement at entry.

2. Admin Configures Everything from Dashboard

Behind the scenes, the Admin Dashboard controls the system.

Admin can manage:

• Services (add/remove/edit)
• Counters & staff assignments
• Working hours and schedules
• Analytics & reports

Think of it as: "The brain of the entire system."

Any change made here instantly reflects in Kiosk, Service Panel, and Display.

3. Staff Operates from Service Panel

Service agents log in to the Service Panel.

They can:

• Call next token
• Skip or hold tokens
• Transfer customers between counters
• Mark service complete
• See live queue status

The system automatically:

• Updates the queue order
• Pushes the called token to Serial Display
• Keeps everything synced in real-time

Goal: Faster service, fewer mistakes, smoother operations.

4. Customers Watch Serial Display

Customers simply relax and watch the Serial Display screen.

It shows:

• Current token being served
• Counter number
• Upcoming tokens
• Announcements or notices

When their token appears → They go directly to the counter.

No shouting. No confusion. No crowd pressure.

Queue Rules & Exception Handling

• Queue rules: Usually "first-come, first-served" per service and transfer to another service. While transfered the system will reassign counter to the token based on counter availability.
• Exceptions: No-show, cancelled, hold, reserved, transferred—these are tracked so reports remain accurate and operations stay transparent.
• Audit trail: Good systems keep activity logs (who changed what, when). OnestQ provides comprehensive logs via the "Logs" actions in menus, ensuring full accountability.

Industry-Standard KPIs You Should Monitor Daily

Track these metrics to optimize your operations:

• Total tokens — Volume / throughput (how many customers served)
• Average wait time — Customer experience indicator
• Average service time — Operational efficiency measure
• Completion rate — Served vs cancelled/no-show ratio
• Counter utilization — Capacity planning and resource optimization

OnestQ uses roles to control what menus, pages, and actions a user can access. The same system can look different depending on whether you're a Branch Manager, Staff, or Counter Manager.

• Branch Manager: manages branch operations (tokens/services/counters) and reviews branch analytics.
• Staff: operational user who can view and manage records relevant to day to day flow; may not be assigned to a counter.
• Counter Manager: focuses on the Counter panel (calling/serving workflow) and counter-specific token lists.

Minimum Server Requirements

• PHP >= 8.2 (8.3+ preferred)
• MySQL >= 8.0 or MariaDB >= 10.10
• Apache >= 2.4 or Nginx >= 1.15 (Recommended: 1.20+ (LTS))
• Memory Limit >= 1 GB (Recommended: 2 GB+)
• Max Execution Time >= 300 seconds
• Disk Space >= 10 GB (Recommended: 20 GB+)

Required PHP Extensions

• OpenSSL PHP Extension
• PDO PHP Extension
• Mbstring PHP Extension
• Tokenizer PHP Extension
• cURL Extension
• JSON Extension
• XML PHP Extension
• BCMath PHP Extension
• Ctype PHP Extension
• Fileinfo PHP Extension
• DOM PHP Extension
• GD PHP Extension (or Imagick)
• ZIP PHP Extension
• Exif PHP Extension
• mysqli PHP Extension
• pdo_mysql (for MySQL/MariaDB)

Required PHP Settings

allow_url_fopen = On
file_uploads = On
max_file_uploads = 20
upload_max_filesize = 32M
post_max_size = 32M
max_input_vars = 3000
max_execution_time = 300
memory_limit = 200M

Database Requirements

• MySQL 8+ or MariaDB 10.10+
• InnoDB storage engine support
• UTF8MB4 character set support
• Database user with full privileges

Web Server Configuration

• URL Rewrite Module enabled
• HTTPS support (recommended)
• Gzip compression enabled (recommended)
• Security headers configured (recommended)

Required Writable Permissions (777)

• /lang — Language files

Required Writable Permissions (775) [If you face permission errors try 777]

• /storage — Application logs, cache, and temporary files
• /storage/app — Application file storage
• /storage/framework — Framework cache and session files
• /storage/logs — Application log files
• /bootstrap/cache — Bootstrap cache files
• /vendor — Vendor files

Required File Permissions (664) [If you face permission errors try 666]

• .env — Environment configuration file
• modules_statuses.json — Modules configuration file

Creating DB in cPanel

Step 1: Create Database

1. Login to your cPanel dashboard
2. Navigate to Manage My Databases section
3. Under Create New Database, enter database name (e.g., yourdb_your_db_name)
4. Click Create Database

Goto the Manage My Databases from cPanel

Create New Database

×

Step 2: Create Database User

1. Scroll down to MySQL Users section
2. Enter username (e.g., yourdb_your_db_user_name)
3. Enter a strong password (avoid # character)
4. Click Create User

Add New User

Step 3: Add User to Database

1. In Add User to Database section
2. Select the user you created
3. Select the database you created
4. Click Add
5. Check ALL PRIVILEGES and click Make Changes

Add User To Database

Universal / Other Servers

CREATE DATABASE `yourdb` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'youruser'@'%' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON `yourdb`.* TO 'youruser'@'%';
FLUSH PRIVILEGES;

Queues: Start a Worker

Use one of the following options to run the queue worker continuously.

Option A — Terminal (Linux/macOS)

php artisan queue:work

Recommended to run under a process manager (Supervisor/systemd) so it restarts automatically.

Supervisor (Linux)

# /etc/supervisor/conf.d/onestq-queue.conf
[program:onestq-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your/project/artisan queue:work
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/supervisor/onestq-queue.log

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start onestq-queue:*

Option B — Windows (Task Scheduler)

1. Open Task Scheduler → Create Task
2. Action: Start a Program
3. Program/script: php
4. Add arguments: artisan queue:work
5. Start in: C:\\path\\to\\your\\project
6. Trigger: At startup or on logon; set to run whether user is logged on or not

Option C — Shared Hosting (cPanel)

Create a Cron Job with the following command (runs the worker in the background):

cd /home/USERNAME/public_html && php artisan queue:work > /dev/null 2>&1 &

Note: Replace /home/USERNAME/public_html with your project path.

Scheduler: Run Cron

Scheduler should be triggered once per day to run due reset tokens according to service settings.

Linux Cron

* * * * * php /path/to/your/project/artisan app:token-reset > /dev/null 2>&1

cPanel Cron

1. cPanel → Cron Jobs → Add New Cron Job
2. Common Settings: Once Per Day
3. Command:

php /home/USERNAME/public_html/artisan app:token-reset > /dev/null 2>&1

Troubleshooting

1. Create/verify Branch: Go to Branch and ensure your branch details are correct.
2. Create Services: Go to Services and create services under the branch (starting letter/number control how token numbers are generated).
3. Create Counters: Go to Counter and create counters (desk locations).
4. Assign services to counters: Configure counter settings and select allowed service(s) per counter.
5. Create users/staff: Go to Users/Staff to add staff, roles, and permissions.

The dashboard UI has two navigation layers:

• Main menu (icon bar): The vertical icon bar at the far left (the rectangle area in your screenshot).
• Submenus: The expanded list (arrow area in your screenshot). This list changes depending on which main menu icon you selected.

The most important submenus you'll use daily are the Others Menu group: Token, Services, Counter, Display, Kiosk, Branch, and Statistical Report.

Most admin screens in OnestQ are "list tables": you search/filter records, then perform operations from the row action menu or bulk actions.

• Filters: use the search fields and dropdowns at the top of the table to narrow results. Always filter by Branch first if you're not seeing expected records.
• Row actions (⋮ in the Action column): per-row context menu for Details, Edit, Delete, Settings, Logs, etc.
• Bulk actions (More Action): applies a command to multiple selected rows (when available). Use carefully—this can update many records at once.

Row actions (⋮ menu)

The "Action" column button (⋮) opens a context menu for that specific record. This is a core feature across almost every list in the system.

• Details/View: opens a read-only view to verify record information.
• Edit: opens a form to change configuration fields (name, prefix, mapping, etc.).
• Settings: opens deeper configuration for the record (rules, mappings, UI settings).
• Logs: audit trail showing changes and activity for the record.
• Delete: removes the record (often restricted). Use only if you are sure the record is safe to delete.

• Kiosk (customer): Customers select a service and generate a token. Depending on kiosk settings, the system can ask for name/phone/email, print a ticket (thermal/laser), and optionally show/print QR or barcode.
• Counter (staff): Staff calls the next token, serves the customer, and can transfer/recall/skip based on service/counter settings.
• Display (public): Shows currently serving tokens and queue information; can play sound/voice announcements and show ticker notifications.

The dashboard shows key totals (services/counters/kiosks/staff), daily/weekly analytics, and quick links into reports.

Use Quick Create to jump directly into creating common entities (Token, Service, Display, Counter, Kiosk, Branch, Printer, User, etc.).

The Users & Staff management system provides comprehensive control over your organization's user accounts, roles, permissions, departments, and designations. This centralized module allows you to manage who has access to the system and what they can do.

Navigate to Staff in the Others Menu to access the following submenus:

• User: Create and manage staff accounts
• Designation: Define job titles and positions
• Department: Organize users by department
• Role: Configure roles with specific permissions
• Permission: Assign granular permissions to roles and users

User Management

The User Management screen displays all staff members in your system. From here, you can create new staff accounts, edit existing users, assign roles, and manage their status. Each user can be assigned to specific branches, departments, and designations.

Key features:

• Filter users by status, department, role, or branch
• View user details including email, phone, designation, and department
• Create new staff with customizable fields
• Assign users to specific counters for service operations
• Manage user permissions individually or through roles

Department & Designation Management

Departments help you organize users based on their functional areas. Create departments like HR, Finance, Operations, Customer Service, etc. Each user can be assigned to one department, making it easier to filter staff lists and reports.

Designations define job titles and positions within your organization, helping establish hierarchy and organizational structure.

Role & Permission Management

OnestQ includes a powerful role-based access control (RBAC) system. Roles define what actions users can perform in the system. Each role can have multiple permissions assigned, controlling access to specific features and operations.

Role management workflow:

1. Create a new role (e.g., "Branch Manager", "Counter Staff", "Supervisor")
2. Assign permissions to the role from the available permission list
3. Assign the role to users who need those permissions
4. Optionally assign additional permissions directly to specific users

The Token module is the heart of the queue management system. Every customer interaction begins with a token - a unique identifier that tracks the customer's journey from arrival to service completion.

Navigate to Token in the Others Menu to access the token management interface. From here, you can view all tokens across your system, filter by status, service, branch, date, and perform various actions.

Token List & Filters

The Token list displays comprehensive information about each token including:

• Token Number: Unique identifier (e.g., A-001, B-022)
• Service: Which service the token was issued for
• Counter: Assigned counter number
• Date & Time: When the token was created
• Customer Info: Name, email, phone (if collected)
• Status: Current state (Waiting, Called, Serving, Served, No-Show, Cancelled)
• Action Menu: Quick access to details, print, and other operations

Use the filter options at the top to search by token number, customer details, date range, service, counter, branch, or status. This makes it easy to find specific tokens or generate custom lists.

Token Details & Actions

Click the action menu (⋮) on any token row to access detailed information and perform operations:

• Details: View complete token information including timeline, status history, and customer data
• Print: Reprint the token ticket (useful if customer lost their original)
• Delete: Remove the token (use with caution - restricted by permissions)
• Logs: View audit trail of all actions performed on this token

Services define the types of customer assistance available at your facility. Each service represents a queue type that customers can select when generating a token. Services are the foundation of your queue management workflow.

Navigate to Services in the Others Menu to manage services, service categories, and service-specific settings.

Service List & Configuration

The Service list shows all available services with key information:

• Service Name: Display name shown to customers
• Service Category: Grouping for related services
• Prefix: Letter/number prefix for token numbering (e.g., A, B, C1)
• Starting Number: Initial token sequence number
• Status: Active or Inactive
• Branch: Which branch this service belongs to

Creating a New Service

When creating a service, you'll configure:

1. Basic Info: Service name, description, branch assignment
2. Category: Select or create a service category for organization
3. Token Prefix: Define the letter/number that appears on tokens (e.g., "A" generates A-001, A-002...)
4. Starting Number: Set initial sequence (usually 1)
5. Status: Set active/inactive (only active services appear in Kiosk)
6. Additional Settings: Optional configurations like estimated service time, priority, etc.

Service Categories

Service categories help organize services into logical groups, making it easier for customers to find the right service on the Kiosk. For example, a hospital might have categories like "Emergency & Trauma", "Diagnostic & Imaging", "Surgical Services", etc., with multiple specific services under each category.

Counters represent the physical service points (desks, windows, stations) where staff members serve customers. Each counter can handle one or multiple services and must be assigned to staff members who operate it.

Navigate to Counter in the Others Menu to manage counters, assign services, and configure counter settings.

Counter List & Overview

The Counter list provides a comprehensive view of all service points:

• Serial: Counter number/identifier
• Name: Counter display name
• Location: Physical location description
• Assigned Staff: Users authorized to operate this counter
• Service Status: Which services this counter can handle
• Status: Active or Inactive

Counter Actions & Details

From the action menu (⋮), you can access various counter management functions:

• Details: View complete counter information and current status
• Settings: Configure service assignments and operational parameters
• Assign Staff: Manage which users can operate this counter
• Edit: Update counter name, location, and basic info
• Delete: Remove counter (if not in use)

Service Assignment

One of the most important counter configurations is service assignment. This determines which services a counter can handle. You can configure a counter to:

• Handle a single specific service (specialized counter)
• Handle multiple services (multi-purpose counter)
• Handle all services from the branch (flexible counter)

The system will only route tokens to counters configured for that service. This ensures customers are directed to the appropriate service point.

Staff Assignment

Assign specific staff members to each counter. Only assigned staff can log into the counter panel and serve customers from that counter. This provides accountability and helps track individual staff performance.

You can assign multiple staff members to a single counter (for shift rotations) and a single staff member to multiple counters (for flexible staffing).

Branches represent different physical locations or operational units of your organization. Multi-branch support allows you to manage queues, services, counters, and staff separately for each location while maintaining centralized oversight.

Navigate to Branch in the Others Menu to manage branches, configure branch settings, and view branch-specific dashboards.

Branch List & Overview

The Branch list displays all operational locations:

• Branch Name: Display name for the location
• Address & Contact: Physical location and contact information
• Status: Active or Inactive
• Services: Number of services available at this branch
• Counters: Number of service points configured
• Staff: Users assigned to this branch

Branch Actions & Management

Each branch has dedicated management features accessible through the action menu:

• Dashboard: View branch-specific analytics and current operations
• Settings: Configure branch-specific parameters and preferences
• Edit: Update branch information, address, and contact details
• Delete: Remove branch (if no active services or staff assigned)

Creating a New Branch

When adding a new branch location:

1. Provide basic information (name, code, address)
2. Set contact details (phone, email)
3. Configure operational hours
4. Assign initial services and counters
5. Set branch-specific preferences

Branch Dashboard

Each branch has a dedicated dashboard showing real-time statistics and operational metrics specific to that location. This helps branch managers monitor their location's performance independently.

The Reports & Analytics module provides comprehensive insights into your queue management operations. Use statistical reports and dashboard charts to monitor performance, identify bottlenecks, and make data-driven decisions.

Navigate to Reports in the menu to access various report types including KPI Dashboard, Staff Performance, Service Efficiency, and Counter Utilization.

KPI Dashboard Report

The KPI (Key Performance Indicator) Dashboard provides a comprehensive overview of your queue management system's performance:

• Token Volume: Total tokens generated, served, and pending over selected time periods
• Wait Times: Average and maximum wait times across services and branches
• Service Times: Average service duration by service type and counter
• No-Show Rates: Percentage of customers who didn't arrive after taking a token
• Trend Analysis: Visual charts showing performance trends over time

Staff Performance Report

Track individual and team performance with detailed staff analytics. This report shows:

• Tokens served per staff member
• Average service time by user
• Staff utilization rates
• Performance comparisons across the team
• Productivity trends over time

Use this report to identify high performers, spot training opportunities, and ensure balanced workload distribution.

• General: Site name, address, branding, company footer text, and meta tags.
• Terms/Privacy/Support: Editable content shown on the public pages linked from login screens.
• Devices: Register Kiosk/Display/Printer devices and configure per-device behavior (layout, voice, filters, printer formats).

The Counter app (Counter staff panel) is where Counter Managers (and staff assigned to a counter) run day-to-day serving operations: calling the next token, starting service, completing a visit, handling no-shows, and transferring a token to another service when required.

• Home: the main counter dashboard (Next Call / Serving controls).
• Schedule: view tokens scheduled for this counter (filter by status, service, date, phone).
• All Tokens: list of tokens in the counter context (includes waiting, completed, no-show etc.).
• Create Token: quick token creation from the counter panel (if enabled by permissions).
• Counter Status: set the counter Open/Close (affects whether tokens can be called/served).

1. Next Call: clicks the next waiting token in queue and moves it to Calling. The token number appears on the left panel and the system can announce it on the Display (depending on settings).
2. Start Serving: when the customer reaches the counter, start service. This changes the status to Serving and begins service-time tracking.
3. Recall Token: repeats the call/announcement for the current token (useful if the customer didn't hear).
4. No Show: marks the token as no-show if the customer does not arrive. (This is important for accurate reporting.)
5. Transfer To: moves the current token to another service (for example, when a customer must be routed to a different department). Select a target service and confirm.
6. Complete: finishes the visit and marks the token completed/served.

Kiosks are customer-facing self-service devices used to create and print tokens. Each kiosk has its own configuration including enabled modules, required customer fields, printing preferences, and session behavior.

Navigate to Kiosk in the Devices Menu to manage kiosk devices, configure settings, and preview the customer interface.

Kiosk List & Configuration

The Kiosk management screen displays all self-service kiosk devices:

• Kiosk Name: Identifier for the kiosk device
• Branch: Location where the kiosk is installed
• Services: Which services are available on this kiosk
• Status: Active, Inactive, or Online (currently connected)
• Device ID & PIN: Authentication credentials
• Printer: Connected thermal/laser printer configuration

Creating a New Kiosk

When creating a new kiosk device, configure:

1. Basic Info: Kiosk name, branch, location description
2. Device Authentication: Set unique device ID and PIN
3. Service Selection: Choose which services customers can access
4. Customer Fields: Configure what information to collect (name, phone, email)
5. Printer Settings: Connect thermal or laser printer, set ticket format
6. UI Preferences: Language, theme, button size, timeout settings

1. Device Authentication: If the kiosk is configured as a device, access it using the device ID/PIN or use the demo device buttons (e.g., "Kiosk 1/2") for testing.
2. Home Screen: After authentication, the kiosk displays two main options: Create Token (generate a new queue token) and Print Token (reprint an existing token).
3. Navigation Buttons: The kiosk interface includes:
   • Home: Returns to the home screen (Create Token / Print Token selection).
   • Back: Goes back to the previous step in the workflow.
   • Settings: From this menu you can logout from the kiosk using Device ID & PIN (PIN is configurable in the kiosk settings). When you logout, the kiosk will return to the home screen.

1. Select "Create Token" from the home screen.
2. Choose Service Category: Browse available service categories (e.g., Emergency & Trauma, Diagnostic & Imaging, Surgical Services). Categories are displayed as tabs or large buttons for easy touch interaction.
3. Select Service: After selecting a category, choose the specific service you need (e.g., Accident & Emergency, Ambulance Services, ICU, Burn Unit). The service list shows available services for the selected category.
4. Submit & Generate Token: Confirm your selection. The kiosk generates a unique token number (e.g., AE-009) with a barcode. The token details include:
   • Token number (format: ServiceCode-Number)
   • Barcode (for scanning at counters)
   • Service name
   • Estimated wait time (if configured)
5. Print Token: If the kiosk has a printer configured, click "Print Token" to print a physical copy. The print dialog appears, and you can use the browser's print controls or the kiosk's thermal printer (if connected).
6. Back to Home: After generating or printing, use "Back to home" to return to the main menu.

1. Select "Print Token" from the home screen.
2. Enter Token Number: Input the token number you want to reprint (e.g., AE-009). The input field accepts the token format displayed during generation.
3. View Token: Click "View Token" to retrieve and display the token details. If the token exists, the kiosk shows:
   • Token number and barcode
   • Original service
   • Token status (waiting, called, serving, served, no-show)
   • Date and time information
4. Print Token: Click "Print Token" to generate a new printout of the existing token. This is useful when a customer loses their original token slip.

Note: The reprint form is accessed from the home screen's "Print Token" option. Enter the token number in the input field (e.g., AE-009) and click "View Token" to retrieve the token details, then use "Print Token" to generate a new printout.

Displays are public-facing screens that show real-time queue information to customers. Each display can be configured to show tokens by counter or by service, and includes device authentication, layout customization, voice announcements, and ticker notifications.

Navigate to Display in the Devices Menu to manage display devices, configure settings, and preview live output.

Display List & Configuration

The Display management screen shows all configured display devices:

• Display Name: Identifier for the display device
• Branch: Location assignment
• Type: Counter-based or Service-based display
• Status: Active, Inactive, or Online (currently connected)
• Device ID: Unique authentication identifier
• PIN: Security PIN for device access

Creating a New Display

When creating a new display device, configure:

1. Basic Info: Display name, branch assignment
2. Display Type: Choose counter-based or service-based layout
3. Device Authentication: Set device ID and PIN for secure access
4. Visual Settings: Layout theme, colors, font sizes
5. Audio Settings: Voice announcements, sound effects
6. Filtering: Which counters/services to show on this display

1. Open Display from the app switcher (home page). If the Display is configured as a device, you'll see the device login screen.
2. Authenticate using a device ID (or the demo buttons like "Display 1/2").
3. Go live: the display shows the current calling token and the waiting list, updating in real-time.

• Calling token: the bottom/right highlight area shows the currently called token number and its counter/service context (example shown as BU-001 / 178).
• Waiting lists: depending on configuration, the display can show waiting tokens grouped by Counter or by Service.
• Summary totals: total tokens, waiting tokens, and no-show count help staff and customers understand queue load.

Multi-Step Service Lifecycle

In many hospitals, polyclinics, banks, and government service centers, a single visitor visit requires multiple departmental services in a strict or conditional sequence. In traditional systems, customers have to pull a new ticket at each desk, causing line disputes, loss of queue priority, and fragmented audit trails.

OnestQ solves this with Service Journeys: a visitor is issued a single token at check-in that seamlessly advances through sequential department queues as each counter finishes service.

Configuring Service Journeys in Admin

Administrators can configure and preview journeys from the admin portal under Others > Services > Service Journeys:

1. Create Journey: Define the journey name (e.g. "Standard OPD Outpatient Flow") and status.
2. Map Ordered Steps: Select services in exact order (e.g. Step 1: Reception/Vitals, Step 2: General Physician, Step 3: Diagnostics Lab, Step 4: Pharmacy).
3. Assign Default Journey: In Services > Edit Service, link the default journey. The interactive Journey Flow Preview will render a visual node graph of the token route.

Dedicated Counter Screen Layout

While the standard Fixed Row Display shows an aggregated multi-counter waiting grid for main waiting halls, the SingleDisplay Module is tailored for individual doorways or teller desks. It gives waiting patients instant visual clarity right outside the specific room where service is delivered.

• Oversized Hero Token: Giant typography highlighting the token currently being served or called.
• Live Duration Timer: Real-time elapsed consultation timer showing how long the current visitor has been with the doctor or officer.
• Counter Status Messaging: Prominent visual alerts when the desk is temporarily unavailable (OPEN, BREAK, HOLD, CLOSED).
• Adjustable Split Ratio: Dynamic layout slider adjusting the split between the hero caller panel and waiting token column (10% to 90%).
• Branded Serving Panel: Support for custom background image branding and institutional theme palettes.
• Announcement Ticker: Scrolling bottom ribbon for room-specific instructions, clinic hours, or promotional notices.

Setting Up a Single Counter Display

1. Go to Settings > Devices > Display Settings.
2. Select Display Type: Single Counter Display (or Single Service Display).
3. Bind the display to the desired Counter or Service.
4. Configure the split percentage, hero background image, and announcement ticker text.
5. Open the display URL in fullscreen on the dedicated doorway monitor.

Hardware LED Integration Architecture

In high-traffic environments, physical LED matrix display boards mounted over counter windows provide superior visibility and durability compared to LCD TVs. The LEDDisplay Module integrates industrial LED matrix panels using RS232/RS485 serial COM/USB protocols (including standard WIXT command sets).

Because the central OnestQ web application may run on a cloud server while the physical LED panels are connected locally to staff PCs at physical branches, the module introduces a dedicated Python LED Display Desktop Agent.

Python LED Display Agent (Remote Server Bridge)

The desktop agent bridges cloud-to-hardware communication seamlessly:

1. Token-Based Authentication: Generate an Agent API token from the OnestQ Admin Panel under Settings > LED Display.
2. Run Agent Script: Launch the Python agent on the counter PC connected to the LED display board via USB/Serial cable:

   python led_agent.py --server https://your-domain.com --token YOUR_AGENT_TOKEN --port COM3 --baud 9600

3. Real-Time WebSocket Push: The agent connects to OnestQ's Pusher WebSocket channel. When staff call or complete tokens, commands arrive in sub-second latency.
4. Direct Serial Writing: The agent translates the incoming payload into WIXT serial protocol commands and writes directly to the local COM port.
5. Hold Keepalive Job: A background daemon periodically re-transmits active token numbers so the matrix panel does not clear prematurely during long consultations.

Split-Screen Digital Signage

Waiting rooms represent high-attention dwell time. The Multimedia Display Module splits large TV screens into an engaging multi-zone broadcast:

• Live Queue Grid: Real-time tokens currently being called and waiting in line, synchronized over WebSockets.
• HD Video Player: Supports looped video playlists (local MP4 uploads or streaming video links) for corporate branding, health education, or sponsor advertisements.
• Image Slideshow: Automatic transition carousel for promotional flyers, service highlights, and doctor profiles.
• Horizontal News Ticker: Customizable scrolling text ribbon along the footer for breaking announcements, operating hours, and greetings.

Voice Announcement Capabilities

Visual screens alone are often missed by distracted or elderly visitors. The MultiVoice Module introduces natural voice synthesis:

• Pleasant Pre-Call Chimes: Configurable attention chime sounds before voice playback.
• Multilingual Speech Synthesis: Voice generation supporting English, Arabic, Spanish, French, Bengali, and other localized system languages.
• Dynamic Sentence Templates: Fully customizable speech phrasing (e.g., "Token number {token}, please proceed to counter {counter}").
• Dual Audio Engine: Leverages high-fidelity cloud TTS voices or zero-cost client-side Web Speech API synthesis depending on environment requirements.

WhatsApp Entry QR (Contactless Mobile Intake)

Visitors can completely bypass physical touchscreen kiosk lines by scanning branded QR code posters located at clinic entrances or lobby doors:

1. The customer scans the QR code poster using their smartphone camera.
2. A pre-filled wa.me WhatsApp chat message opens automatically on their phone.
3. Sending the message immediately generates their digital token with estimated waiting time and queue position.

Dual Messaging Architecture (Cloud API vs WhatsApp Web Sidecar)

OnestQ gives organizations flexibility in how WhatsApp messages are delivered:

Remote & In-Branch Mobile Ticketing

The Virtual Kiosk (KioskApp) provides a lightweight, touch-optimized web application:

• Zero Installation: Runs instantly in any standard mobile browser (Chrome, Safari) without requiring an app store download.
• Department & Service Selector: Clear icons, language switcher, and live estimated wait time display per service category.
• Digital Ticket Pass: Displays the issued token number, QR code, and real-time live position updates on the user's phone.
• Tablet Reception Mode: Can be deployed on wall-mounted iPads or Android tablets as an economical kiosk alternative.

Integrated Scheduling & Check-In

Managing both walk-in visitors and scheduled appointments on separate systems creates double-booking chaos and desk friction. The Appointment Module synchronizes both worlds:

• Customer Booking Portal: Customers book specific date/time slots online, selecting branch, service department, and preferred staff member.
• Appointment Confirmation: Automated confirmation emails and WhatsApp messages containing a secure appointment QR code.
• Arrival Check-In: When the patient arrives at the branch, scanning their appointment QR code at the kiosk instantly issues an active token.
• Smart Slot Prioritization: Configurable rules ensure appointment holders are called punctually within their scheduled window without completely halting walk-in queues.

Queue Protection & Security Controls

When public QR codes or virtual kiosks are exposed online, bad actors can attempt to hoard tokens or flood the database. QueueGuard enforces multi-layered defense rules:

• IP & Fingerprint Rate Limiting: Enforces maximum token generation limits per IP address and browser session within a rolling time window.
• Cooldown Periods: Prevents consecutive token requests until a configured cooldown duration (e.g. 15 minutes) has elapsed.
• SMS / Mobile OTP Verification: Requires visitors to verify their mobile phone number via a one-time passcode before a valid token is dispensed.
• Audit Logging: Logs blocked attempts, flagged IP ranges, and security violations for administrator review.

Automated Update Lifecycle

Keeping production software up to date is simplified with the SelfUpdate Module accessible from Settings > About System:

1. Version Detection: Compares the currently installed release against the remote update server and notifies administrators with release notes and changelogs.
2. Expected ZIP Name Verification: Ensures uploaded archives match strict version naming (e.g. RELEASE-2.0.zip) to prevent accidental mismatches.
3. Maintenance Mode Activation: Automatically invokes php artisan down during installation to prevent user race conditions.
4. Pre-Update Safety Backup: Existing files slated for replacement are automatically copied to a timestamped backup directory (/storage/app/laraupdater/backup_YYYYMMDD).
5. Hook Execution & Migrations: Executes beforeUpdate() and afterUpdate() hooks inside upgrade.php, running database migrations and clearing cache.
6. Fail-Safe Rollback: If any error or exception occurs, the system triggers recovery(), restores original files from the backup directory, and brings the system back online.

Inclusivity & Assistive Controls

Public sector clinics, hospitals, and municipal buildings must comply with international digital accessibility standards (WCAG 2.1 / ADA). The AccessibilityPanel Module provides:

• High-Contrast Color Modes: Instant toggles for dark mode, inverted contrast, and monochrome high-contrast palettes for visually impaired visitors.
• Typography Zoom: Multi-step font size enlargement (+10% to +40%) across kiosk and display screens.
• Dyslexia-Friendly Fonts: Alternative specialized typography optimizing readability for neurodivergent visitors.
• Screen Reader Ready: ARIA labels and landmark markup across kiosks, digital tokens, and web interfaces.

The OnestQ application uses Laravel Blade templates. Key paths and components:

• Layouts: resources/views/layouts/ — head, meta, footer_script, keyboard
• Backend layout: resources/views/backend/company/layouts/ — sidebar, header, footer_script
• Auth views: resources/views/auth/ — login-display, login-kiosk, login-counter
• Form components: resources/views/components/form/ — file_upload, input, select-component, date-picker, editor, checkbox, radio, status
• Table components: resources/views/components/table/ — table-container, action-dropdown, bulk-actions, pagination
• Backend pages: resources/views/backend/company/ — dashboard, branch, queue (services, counters, tokens, device), user_management, settings, trash
• Error pages: resources/views/errors/ — 403, 404, 405, 429, 500
• Modules: Modules/Counter/, Modules/Kiosk/, Modules/Display/ — Blade views for each module

The OnestQ application uses SCSS compiled to CSS. Key paths and structure:

• Entry point: public/assets/backend/scss/main-style.scss — main SCSS import
• Global: scss/global/ — _global.scss, _animation.scss, _button.scss, _rtl.scss, _select2.scss, _bootstrap-tooltip-custom.scss
• Layout: scss/layout/ — _header.scss, _sidebar.scss, _footer.scss
• Components: scss/components/ — _form.scss, _table.scss, _token.scss, _custom-modal.scss, _breadcrumb.scss
• Pages: scss/pages/ — _counter.scss, _display.scss, _kiosk.scss, _login.scss, _error.scss
• Sections: scss/sections/ — _dashboard.scss, _profile.scss, _dashboard-card.scss
• Output: public/assets/backend/css/ — compiled CSS files
• Framework: Bootstrap 5 for layout, grid, and base components

The OnestQ application uses jQuery, Bootstrap JS, and custom scripts. Key paths and structure:

• Core: public/assets/backend/js/ — jquery-4.0.0.min.js, bootstrap-5.3.8.min.js, main-core.js, main-ui.js, main-forms.js
• Custom scripts: custom-core.js, custom-modals.js, custom-tokens.js, custom-devices.js, custom-settings.js, bulk-action.js, dashboard.js, queue-dashboard.js
• Plugins: plugins/ — plugin.js, lucide-icon.js, LoadingOverlay.js, nprogress, quill.min.js, pusher.min.js, file-preview file_preview_handler.js
• Chart: plugins/chart/ — apexcharts.js, chart-custom.js
• Modules: assets/modules/ — counter/counter.js, display/display.js, kiosk/kiosk.js, deviceauth/auth-script.js
• Build: Vite (Laravel vite.config.js) for resources/js/app.js and resources/css/app.css
• Real-time: Pusher for live token and queue updates

The OnestQ application backend is built with Laravel. Key paths and structure:

• Controllers: app/Http/Controllers/ — backend/ (BranchController, DashboardController, queue_management/TokenController, ServiceController, CounterController, DeviceController), Auth/, UserController
• Models: app/Models/ — Token, Service, ServiceCategory, Counter, Branch, User, Role, Device, Printer, KioskSetting, DisplaySetting
• Repositories: app/Repositories/ — Data access layer for tokens, services, branches, etc.
• Routes: routes/web.php, routes/api.php — admin prefix (admin/branches, admin/queue/*, admin/user/*), device auth (login-kiosk, login-display, login-counter)
• Middleware: app/Http/Middleware/ — auth, permissionCheck, device auth
• Services: app/Services/ — TokenService, ReportService, CommonExportService
• Config: config/ — app, database, queue, broadcasting, reverb
• Modules: Modules/Counter/, Modules/Kiosk/, Modules/Display/, Modules/DeviceAuth/ — module-specific controllers and views

The OnestQ application uses a relational database (MySQL/MariaDB/SQLite). Migrations are in database/migrations/. Key tables:

• Core: companies, branches, services, service_categories, counters, tokens
• Users: users, roles, departments, designations, counter_users
• Devices: devices, display_settings, display_setting_counters, display_setting_services, kiosk_settings, printer_settings
• Queue operations: tokens (reference_number, status, service_id, counter_id), token_logs, counter_logs, counter_feedback
• Service config: service_schedule_setups, service_time_slots
• Settings: general_settings, company_settings, branch_settings, counter_settings
• Other:file_managers, activity_log, notifications, sms_templates, device_login_logs

Key image paths in the project:

• Backend assets: public/assets/backend/images/ — favicon, no-data placeholder, UI images
• Auth: public/assets/auth/ — login backgrounds
• Modules: assets/modules/ — kiosk (kiosk-bg.png), display (calling-icon.gif), counter images
• User uploads: Stored via FileManager; paths from storageAssetPath()