🏛️ ARCHITECTURAL SPECIFICATION & DEVELOPER MANUAL

WaitLink Architecture & Technical Blueprint

The definitive guide to WaitLink’s cloud synchronization, real-time Firestore database schema, Twilio SMS messaging engine, role-based workflows, developer deployment commands, and competitive industry benchmark.

< 2s
QR Check-In Velocity
100%
Zero App Installs Needed
< 500ms
Firestore Real-time Sync
1-Tap
SERVE NOW SMS + Link
01

Purpose of WaitLink & The Problem Solved

⚠️ The Walk-Away Revenue Loss Crisis

Walk-in service businesses (barbershops, urgent care clinics, pet groomers, auto service bays, DMV offices) lose up to 30% of peak rush revenue simply because prospective customers look at a crowded waiting room and walk away without ever checking in.

Traditional solutions fail because they require costly iPad kiosks ($800+), cumbersome native app downloads with accounts and passwords, or expensive enterprise contracts with $300/mo minimums.

💡 The Zero-Barrier WaitLink Solution

WaitLink replaces physical buzzers and kiosks with a simple, high-resolution printable Window QR Poster. Customers scan the flyer with their native mobile phone camera, enter their name and optional mobile number in 2 seconds, and immediately track their live spot in line with a real-time ticking clock.

When their turn is ready, front desk staff tap "SERVE NOW", and WaitLink automatically dispatches an instant transactional SMS with their direct live ticket link, enabling customers to step outside, grab coffee, and return exactly when called.

02

Platform Features & Operational Capabilities

⏱️

1-Tap "SERVE NOW" Control

Front desk staff manage incoming visitors on any device (tablet, smartphone, PC). One tap instantly updates the cloud queue, advances waiting counters, and triggers customer notifications.

📲

Turn-Ready SMS with Ticket Link

Integrated with enterprise Twilio SMS gateway. Dispatches personalized texts containing the customer's direct tracking URL (https://waitlink.app?s=slug&view=public&ticket=id).

🖨️

8.5"x11" Printable Window Poster

Generates high-resolution vector printable flyers with custom shop logo, business name, and dynamic QR code ready to print directly onto cardstock and hang on storefront glass.

🔄

3D Stage Rotator & Grid Views

Front desk staff can switch dynamically between a high-efficiency Compact Grid view and a carousel-style 3D Stage Rotator designed for fast stylus navigation on iPads.

📊

Business Intelligence & Audit Trail

Automatically calculates Walk-Away Loss % (cancellations), Peak Rush Windows, Staff Throughput (Visits/Hr), Average Wait Time, and provides 11-column CSV export logs.

🏢

Multi-Tenant Shop Management

Shop owners can create, configure, and switch between multiple locations under a single account. Each store has an independent URL slug, queue, services menu, and QR poster.

03

Process Flows by Role (End-to-End)

👤 1. Customer End-User Journey

Step 1: Scan Arrive & Point Camera

Customer approaches storefront and points mobile phone camera at the WaitLink Window Poster QR code. Opens directly in mobile Safari/Chrome.

Step 2: Check-In 2-Second Self Check-In

Types name/initials, chooses desired service chip (e.g. Haircut 20m), and enters optional mobile number with CTIA/TCPA SMS consent disclosure.

Step 3: Track Live Dynamic Ticket

Receives a personal live ticket showing real-time ticking wait timer, position in line (e.g., #3 in line), and a "🕒 Running Late" action button.

Step 4: Turn Ready SMS Notification Delivered

When desk calls, receives instant SMS: "Hi Alex! Your turn at Main St Barbers is ready now. View ticket: waitlink.app?s=...&ticket=..."

💈 2. Front Desk Staff Workflow

Step 1: Mount Open Desk Console

Staff open ?s=slug&view=desk on reception iPad or phone. Real-time Firestore snapshot listener populates active line.

Step 2: Monitor Queue Tickers & Triage

Monitors ticking elapsed time for each customer, late flags, and selected service tags. Can tap phone links to launch universal phone dialer.

Step 3: Call Tap "SERVE NOW"

When service bay or barber chair opens up, staff tap "SERVE NOW". App calculates wait metrics, ends timer, and dispatches turn SMS automatically.

Step 4: Re-Queue Line Flexibility

If a customer stepped away, staff tap "⬇️ Move to End" to requeue them without losing their historical check-in record, or cancel with 1-click.

🔑 3. Shop Owner Administration Flow

Step 1: Setup Shop Onboarding

Signs in via Google Auth or email. Claims unique storefront slug (e.g., main-st-barbers), uploads custom logo, sets base wait time.

Step 2: Customize Services & SMS Templates

Configures service catalog with estimated durations. Customizes the "SERVE NOW" SMS template using tags: {name}, {shop}, {link}.

Step 3: Intelligence Analytics & Audit Logs

Tracks walk-away cancellation loss percentages, peak customer rush hours, and staff visits per hour. Exports comprehensive 11-column CSV audit files.

Step 4: Billing Stripe Subscription Control

Upgrades seamlessly between Free Starter, Pro ($15/mo), and Enterprise ($49/mo) plans through 100% secure Stripe Checkout integrations.

👑 4. SuperAdmin Platform Governance Flow

Step 1: Auth Cryptographic Auth

Locked to verified Platform Administrator via Firebase Auth and Firestore security rule validation on every request.

Step 2: Directory Multi-Tenant Directory

Inspects all registered businesses across the database, monitoring active queue lengths, shop configurations, and active plans.

Step 3: Pricing Dynamic Pricing Manager

Live configurator updates feature checklists and prices across pricing tables and checkout modals. Records immutable audit logs in Firestore.

Step 4: Support Support Inquiry Center

Reads incoming support inquiries from contact.html, writes replies, and triggers direct email dispatch to the user.

04

Cloud & Data Architecture Blueprint

WaitLink uses an ultra-responsive, serverless micro-architecture designed for sub-second UI updates, real-time multi-device synchronization, and zero local hardware dependencies.

📦 Google Cloud Firestore Collection Model

Firestore Collection Document Path Primary Fields / Schema Access Permissions
shops /shops/{slug} shopName, slug, queue[], history[], services[], twilio{}, planTitle, ownerEmail Public Read single doc • Owner/Admin Write • Customer atomic queue append
messages /messages/{msgId} to, from, body, ticketId, ticketUrl, shopSlug, triggerType, createdAt, status Write-only from app • Read/Executed by Twilio Extension / Cloud Functions
contact_messages /contact_messages/{id} name, email, subject, message, sentAt, status Public Create via contact page • SuperAdmin Read/Delete/Reply
support_replies /support_replies/{id} inquiryId, recipientEmail, replyText, sentAt, sender SuperAdmin Read/Write Only
settings /settings/pricing_config tiers: { t1[], t2[], t3[] }, updatedAt Public Read • SuperAdmin Write Only
pricing_audits /pricing_audits/{auditId} author, timestamp, changes[], previousState, newState SuperAdmin Read/Write Only
users /users/{uid}/checkout_sessions price, mode, success_url, cancel_url, sessionId Authenticated User (UID Match) • Stripe Extension Read/Write
05

Security Architecture & Rules Enforcement

🛡️ Firestore Security Rules Isolation

WaitLink eliminates open wildcard access. Access is strictly constrained by authentication state and role:

  • No Open Scraping: Direct allow list queries across the entire /shops collection are blocked for unauthenticated users.
  • Customer Check-In Safeguard: Unauthenticated customer check-ins are restricted to updating only the queue and stats fields via affectedKeys().hasOnly(...). Customers cannot overwrite owner email, settings, or plans.
  • SMS & Inquiry Protection: Outbound SMS and contact inquiry tables are blocked from public reads.

🔑 Git & Secrets Management Architecture

Credentials and operational API keys are permanently decoupled from Git:

  • config.secrets.js holds local credentials and is excluded via .gitignore and firebase.json.
  • config.secrets.example.js is tracked in Git as a placeholder template.
  • Source files (app.js, index.html) use the dynamic window.WAITLINK_SECRETS loader with zero hardcoded secret strings.
06

Developer CLI & Deployment Commands

Copy and execute these commands directly in your terminal for maintenance, deployments, and testing:

1. Full Production Deployment (Hosting + Version Pruning) Primary Deploy Workflow
npm run deploy
2. Deploy Cloud Firestore Security Rules Only Database Security Release
npx firebase-tools deploy --only firestore:rules --project waitlink-app-8821
3. Deploy Firebase Hosting Files Only CDN Static Assets
npx firebase-tools deploy --only hosting --project waitlink-app-8821
4. Run Automatic Hosting Version Pruning Script Keep 5 Most Recent Versions
node scripts/prune-firebase-versions.js
07

Public URLs & Search Engine Indexing Directory

All public-facing routes deployed on waitlink.app, registered in sitemap.xml and submitted to Google Search Console:

Web Page Production URL SEO Priority Description
Homepage https://waitlink.app/ 1.0 (Daily) Main SaaS landing page with QR check-in demo and live queue ticker
Pricing https://waitlink.app/pricing.html 0.9 (Weekly) Transparent tier comparison: Free Starter, Pro ($15), Enterprise ($49)
Comparison Matrix https://waitlink.app/comparison.html 0.9 (Weekly) Head-to-head comparison vs Waitwhile, Waitlist Me, QLess, Qminder
About Us https://waitlink.app/about.html 0.8 (Monthly) Our mission, local business revenue optimization, and team story
FAQ https://waitlink.app/faq.html 0.8 (Weekly) Detailed answers on SMS delivery, hardware requirements, Stripe billing
Help Center https://waitlink.app/help.html 0.8 (Weekly) Step-by-step guides for window flyers, front desk iPads, and owner settings
Contact Page https://waitlink.app/contact.html 0.7 (Monthly) Direct inquiry form connected to Cloud Firestore support inbox
Architecture Blueprint https://waitlink.app/waitlinkarchitecture.html Unlisted / Direct Internal technical blueprint, process flows & developer manual (excluded from sitemap.xml)
Privacy Policy https://waitlink.app/privacy.html 0.4 (Monthly) TCPA & CTIA compliant cellular mobile SMS text messaging disclosures
Terms of Service https://waitlink.app/terms.html 0.4 (Monthly) Software as a service subscription and user licensing agreement
Cookie Policy https://waitlink.app/cookies.html 0.3 (Monthly) Client-side HTML5 LocalStorage caching and analytics disclosure
XML Sitemap https://waitlink.app/sitemap.xml Search Index Google Search Console indexable XML feed
Robots Directives https://waitlink.app/robots.txt Crawler Index Search crawler permissions and sitemap pointer
08

Competitive Comparison Matrix (WaitLink vs Industry)

Comprehensive benchmarking comparing WaitLink against traditional queue management systems:

Feature / Capability 🚀 WaitLink
Built for Speed & Value
 Waitwhile Waitlist Me QLess Qminder
1. Setup & Customer Friction
App Download Required ❌ None (Web Instant) ❌ None ❌ None ⚠️ App Often Preferred ❌ None
Account Setup Time ⚡ Under 2 Minutes 30+ Mins 15+ Mins Days / Onboarding Call 30+ Mins
Hardware Requirements 📱 Any Phone/Browser Tablet Kiosk Tablet Kiosk Custom Hardware iPad Kiosk
2. Core Queue & Customer Experience
Live Queue Tracker (Customer Phone) ✅ Real-Time Sync ✅ Yes ⚠️ SMS Link Only ✅ Yes ⚠️ Basic SMS
Lobby Digital TV Display Mode ✅ Included Free 💲 Paid Addon 💲 Paid Addon 💲 Enterprise Addon 💲 Paid Addon
Twilio SMS Integration ✅ Built-in Toggle & Compliance ✅ Yes ✅ Yes ✅ Yes ✅ Yes
3. Analytics & Operational Intelligence
Walk-Away Loss % Analytics ✅ Instant KPI Dashboard Higher Tier Only ❌ No Enterprise Tier Custom Reports
Customer Lifecycle CSV Audit Export ✅ 11-Column Detailed Audit Basic CSV Basic CSV Enterprise SQL Limited Export
4. Pricing & Value
Starting Price 💎 High Value / Free Start $29 - $199 / mo $29 - $49 / mo $100+ / mo $299+ / mo

Explore the Live WaitLink Platform

Experience 1-tap queue control, real-time wait times, and automated SMS turn notifications.

🚀 Open WaitLink Application ⭐ View on GitHub