QSmart

# QSmart — Smart Queue & Appointment Management System (PHP)

Multi-Tenant SaaS Queue Management, Appointment Scheduling & Booking Platform with QR Check-in, Real-Time Notifications, Stripe Payments & Subscriptions

---

## 🔖 Short Description (for listing header)

QSmart is a complete, production-ready multi-tenant queue management and appointment booking platform built in pure PHP & MySQL. Run it as your own SaaS business — let unlimited organizations (clinics, government offices, salons, banks, retail stores) sign up, manage their queues and appointments, accept online payments, and notify customers in real time. Includes a web app, a mobile-optimized web version, REST API, QR-code check-in, Firebase push notifications, Stripe & Stripe Connect payments, subscription billing, multi-language support, and a full analytics dashboard.

---

## 🌟 Overview

Traditional queues mean paper tickets, long waits, and zero visibility. QSmart digitizes the entire queue lifecycle — from the moment a customer joins a queue to the moment their service is completed — giving both customers and staff real-time control.

Built on a clean, class-based PHP architecture with PDO prepared statements, QSmart is designed to be sold as a SaaS out of the box: a single installation serves unlimited organizations, each fully isolated with its own services, staff, queues, branding, and subscription tier. You collect recurring subscription revenue (via Stripe) and optionally a platform fee on every customer payment (via Stripe Connect).

Whether your buyers are running a hospital, a municipality, a barbershop chain, or a service center, QSmart gives them a modern, mobile-first queue and booking experience — no app installation required for end customers (they join via web link or QR scan).

---

## ✨ Key Features

### 🏢 Multi-Tenant SaaS Architecture

- Single deployment serves unlimited organizations

- Each organization is fully isolated: own services, staff, queues, settings, profile

- Many-to-many user↔organization relationship — one user can belong to multiple organizations with different roles (perfect for franchises & multi-branch businesses)

- Public organization pages with SEO-friendly slug URLs (`/organization/42-city-clinic`)

### 🔐 Role-Based Access Control

- Super Admin — manages the entire platform

- Organization Admin — configures & operates their organization

- Moderator — assists with queue operations

- End User / Customer — joins queues and receives notifications

- Secure session management, CSRF protection, activity logging & audit trails

### 🚦 Intelligent Queue Management

- Priority-based queuing (Urgent / High / Normal / Low)

- Drag-and-drop manual reordering

- Live queue status with estimated wait times

- One-click "call next", skip, complete, and no-show handling

- Real-time queue length & wait-time calculation

### 📅 Appointment Scheduling (FullCalendar)

- Professional calendar UI — Month / Week / Day / Agenda views

- Drag-and-drop rescheduling

- Automatic double-booking / conflict detection

- Time-slot booking with available-slot suggestions

- Scheduled appointments can flow into the live queue on the day of visit

### 📱 QR Code Check-in

- Generate & print QR codes that link directly to an organization's queue page

- Customers scan with their phone camera → join instantly (no app needed)

- Built-in browser QR scanner page for staff check-in verification

### 🔔 Real-Time Notifications (Multi-Channel)

- Firebase Cloud Messaging (FCM) push notifications for background/closed app

- In-app real-time alerts via lightweight polling

- Email notifications (SMTP / PHPMailer) for confirmations, verification & password resets

- Toast alerts, sound, and vibration for "your turn" events

### 💳 Payments & Subscriptions (Stripe)

- Stripe integration for online payments

- Stripe Connect marketplace model — collect a configurable platform fee on every transaction

- Subscription tiers (Basic / Premium / Enterprise) with per-tier capabilities & limits

- Full subscription lifecycle management

### 📊 Analytics & Reporting

- Real-time dashboard with live queue metrics (current length, avg wait, served today)

- Historical trend analysis & performance metrics (Chart.js)

- Peak-hour insights to optimize staffing

### 🌍 Multi-Language Support

- Dynamic language switching with browser language detection

- Organized JSON translation files — easy to add new languages

- Parameter replacement in translation strings

### 📱 Mobile-Optimized

- Fully responsive Bootstrap UI (desktop / tablet / mobile)

- Dedicated mobile web version

- Android app project included

### 🔌 REST API

- Documented endpoints for appointments, queue, calendar events, available slots, stats, service types & clients

- JSON responses, authentication-protected, CORS-configured

---

## 🛠️ Technology Stack

| Layer | Technology |

|---|---|

| Backend | PHP 7.4+ (class-based, modular) |

| Database | MySQL 5.7+ (PDO, prepared statements) |

| Frontend | Server-rendered PHP + JavaScript, Bootstrap |

| Calendar | FullCalendar |

| Charts | Chart.js |

| Push | Firebase Cloud Messaging |

| Payments | Stripe + Stripe Connect |

| Email | SMTP via PHPMailer |

| Security | reCAPTCHA v3 support, CSRF tokens, security headers |

---

## 📦 What's Included

- Full PHP source code (no encryption — 100% editable)

- Complete MySQL database schema + migration scripts

- Web application (admin + organization + customer portals)

- Mobile-optimized web version

- Android app project folder

- REST API

- Sample data for quick testing

- Documentation (README, installation & migration guides)

- `.htaccess` with SEO-friendly routing & security headers

- Sitemap generator (SEO)

---

## ✅ Requirements

- PHP 7.4 or higher

- MySQL 5.7 or higher

- Apache or Nginx (with URL rewriting / `mod_rewrite`)

- Composer (for dependencies)

- SSL certificate (recommended for production)

- Stripe account (for payments — optional)

- Firebase project (for push notifications — optional)

- SMTP credentials (for email — optional)

> ⚡ Performance: Optimized for high concurrency — a single mid-range VPS (8 vCPU / 12 GB RAM) comfortably handles several thousand simultaneous online users thanks to persistent DB connections and efficient real-time polling.

---

## 👥 Who Is It For?

- Entrepreneurs launching a queue-management SaaS business

- Hospitals & clinics (patient flow)

- Government & municipal offices (citizen services)

- Banks & financial branches

- Salons, spas & barbershops (appointments)

- Retail & service centers

- Restaurants (waitlists)

- Any business that wants to eliminate physical waiting lines

---

## 💡 Why Buy QSmart?

- Monetize from day one — built-in subscription billing + per-transaction platform fees

- True multi-tenant SaaS — not a single-business script

- No customer app required — web + QR removes adoption friction

- Clean, documented, editable code — easy to customize & extend

- Scales — proven to handle thousands of concurrent online users

- Complete package — web, mobile, API, and Android included

---

## 🚀 Quick Setup

1. Upload files & point your domain to the project root

2. Create a MySQL database and import the schema

3. Configure `config.php` (database, Stripe, Firebase, SMTP)

4. Enable URL rewriting

5. Register your first Super Admin — you're live!

(Full step-by-step guide included.)

---

## 🆕 Version

Version 1.0.0 — Smart Queue System with Calendar Integration