Queue Manager

Queue Manager is a desktop queue-management platform designed for organizations that attend customers in person and need a clear, synchronized, and role-based service flow.

The application is built with Java + JavaFX and is structured around four operating modes:

• Administrator mode (A): configure company data, branches, stations, services, customers, and analytics.
• Kiosk mode (K): customer-facing ticket generation flow.
• Staff mode (S): station operator flow to call and complete tickets.
• Projection Screen mode (P): public display with live calling status and call announcements.

Main Purpose

The core objective of Queue Manager is to coordinate the full ticket lifecycle:

1. A customer (identified or guest) selects a service in Kiosk mode.
2. The system generates a queue ticket, stores it, and creates a PDF receipt.
3. Staff calls and attends tickets from station-specific queues.
4. Projection Screen shows the active call and recent history to improve customer orientation.
5. The system records attended/cancelled tickets and updates operational statistics.

The app is focused on reducing waiting confusion, improving branch operation visibility, and keeping queue data consistent across multiple running instances.

How the App Works (Functional Flow)

1) Startup and App Mode Selection

The app starts in App.java and receives one optional argument:

• A -> Administrator interface
• K -> Kiosk interface
• S -> Staff interface
• P -> Projection Screen interface

If no mode is provided, the default is Administrator mode.

At startup, the app:

• Resolves data paths from confi.json (sharedDataPath when valid, otherwise local data/).
• Loads company, services, branches, and customers JSON files into memory.
• Syncs branch/station local context.
• Starts an auto-reload watcher to detect external JSON changes and refresh UI data in real time.

2) Data Layer and Synchronization

The central in-memory manager is DataLoader.

It provides:

• Observable collections for branches, services, customers, waiting queues, offered services, and stations.
• JSON rehydration to restore references between tokens, customers, services, branches, and stations.
• Stale-check reload logic to avoid unnecessary reloads.
• Listener-based propagation so views refresh when data changes.
• Protection against suspicious/corrupt JSON states and local backup mirroring.

Persistence is handled by dedicated Gson managers (BranchGsonManager, ServiceGsonManager, CustomerGsonManager, CompanyGsonManager, StatisticsGsonManager) with a shared storage strategy.

3) Kiosk Ticket Creation

In Kiosk mode, the flow is:

1. Customer enters as guest or identifies with ID.
2. Optional priority session can be enabled using admin PIN.
3. Customer selects one available service from the current branch.
4. The system generates the next ticket number (1..999 with collision avoidance in active queue).
5. A TokenModel is created with status WAITING and inserted into branch waiting queue.
6. A PDF ticket is generated and opened automatically when possible.

Ticket creation includes service reference normalization, customer association, priority flag handling, and branch/station trace metadata.

4) Staff Attention Flow

In Staff mode, each station works with its configured service capabilities.

Key operations:

• Call next compatible ticket.
• Priority call (if needed).
• Repeat current call.
• Call selected ticket from queue manager table.
• Switch station active/inactive status.
• Complete the current ticket as finished or cancelled.

When a ticket is completed:

• It is removed from waiting queue.
• Service duration is computed from attention start/end timestamps.
• Service average time is updated using rolling attended samples.
• Customer completed-service count is incremented when applicable.
• Company attended-token history is updated for analytics and display.

5) Projection Screen and Announcements

Projection mode displays:

• Company and branch identity.
• Current ticket being called/attended.
• Last attended tickets.
• Informational branch message ticker.

It also processes call announcements with controlled replay behavior:

• Detects call-count increments in active tokens.
• Queues audio announcements.
• Applies cooldown and rollback logic if playback fails.

6) Administrator Modules

Administrator mode is the operations console and includes:

• General company setup (name, branding, admin pin, contact data).
• Service/formality management.
• Branch and station management.
• Customer registry and editing.
• Statistics dashboards with filters and cached persistence.

The administrator UI uses paginated statistic cards and data-bound previews that refresh when persistence changes are detected.

Project Structure (High Level)

• src/main/java/cr/ac/una/queuemanager/controller: UI controllers for each mode and module.
• src/main/java/cr/ac/una/queuemanager/model: domain models (branch, station, service, token, customer, statistics).
• src/main/java/cr/ac/una/queuemanager/service: JSON persistence and storage managers.
• src/main/java/cr/ac/una/queuemanager/util: flow management, data loader, animations, messaging, PDF generation, path resolution, and shared context helpers.
• src/main/resources/.../view: JavaFX FXML views for administrator, kiosk, staff, and projection screen.
• data/json: active or fallback local JSON storage.

Technology Stack

• Java 25
• JavaFX 25
• Maven
• Gson (JSON serialization/deserialization)
• iText (PDF ticket generation)
• MaterialFX + AtlantaFX (UI components and styling)
• Webcam Capture (camera support)
• Google Cloud Text-to-Speech (voice calls)

Build and Run

Prerequisites

• JDK 25
• Maven 3.9+

Build

mvn clean package

Run (JavaFX Maven plugin)

mvn javafx:run

Run with specific mode

Example idea (depending on your local launch strategy): pass one of A, K, S, or P as startup argument.

Team Contributions

This project was developed as a full-stack collaborative effort by all three members, with each person taking stronger ownership in a specific area:

• Dominique Mariano Quiros Castro Primary Frontend lead and main owner of the visual style/language of the application, with occasional support from teammates in specific UI tasks.

• Luis Andrés Elizondo Hernández Primary Backend lead, focused on most of the Java business logic, queue behavior, and application processing rules.

• Esteban Josué Mena Cascante Primary data persistence and data-flow lead, focused on JSON storage consistency, synchronization strategy, and data movement through the app.

Even with those focus areas, all three contributors participated as full-stack developers across the project lifecycle.