Zap Virtual Queue System

Welcome to Zap – the next-gen virtual queue platform that eliminates long waiting lines! This project lets admins create virtual queues so users can roam free and only arrive when their turn comes. With scalable APIs and modular apps, Zap revolutionizes how people wait.

---

🚀 Overview

• Create virtual queues as an admin; users join from anywhere and get notified when it’s their turn.
• No pointless waiting: Get notified, show up when it’s your turn!
• Modular design: 2 APIs and 2 websites for maximum scalability.
• Hosted on Express (backend) and Next.js (frontend).
• Primary DB: Firebase Firestore. Auth handled by Firebase Auth.

---

🏗️ Architecture & Structure

Apps & APIs

• APIs (2 total):
  • zap-backend-api — Admin API (Express)
  • zap-customer-api — Customer actions API (Express)
• Websites (2 total):
  • zapbs — Customer-facing site (Next.js)
  • zap-admin — Admin dashboard (Next.js)

Note: Admin web dashboard relies on both customer API and backend API for certain flows, such as user checkout.

---

🌐 Public Endpoints

• Customer API Endpoint: https://git-endpoint.zapnow.tech/
  (Use for all customer-facing queue actions)
• Admin API Endpoint: https://api.zapnow.tech/
  (Use for admin dashboard and management)
• Customer App: https://customer.zapnow.tech/dashboard
• Admin App: https://admin.zapnow.tech/signup

🔑 Authentication

All requests to these APIs must be authenticated (i.e., you must provide a valid Firebase Auth ID token in the request headers), except the open endpoints (such as create account/signup).
After account creation, use Firebase Auth to obtain your ID token and include it in every API request for both customer and admin actions.

---

🗄️ Database

Uses Firebase Firestore (NoSQL) as primary storage and Firebase Auth for authentication and user tracking.

Main Collections

1. admins

• id (string, UID)
• name (string)
• email (string)
• phone (string)
• createdAt (timestamp)
• createdQueues (array of queue IDs)

2. users

• uid (string)
• displayName (string)
• email (string)
• password (string, hashed)
• phoneNumber (string)
• timestamp (timestamp)
• userType ("user")
• customClaims (object)

3. queues

• id (queue ID)
• location (address, landmark, name)
• settings (categories, password, premiumSlots, slots, etc.)

3.1.2 queues/{queueId}/users

• userId
• name
• phone
• isPremium
• memberCount
• position
• timestamp
• usermail

3.1.3 queues/{queueId}/history

• Same as users, plus quit_timestamp

• 

See images above for real database UI and document structures.

---

⚡ Tech Stack

• Backend: Express.js, Firebase Admin SDK
• Frontend: Next.js (React)
• Database: Firebase Firestore
• Authentication: Firebase Auth

---

🏃 Running Locally

Prerequisites

• Node.js (v18+)
• Yarn or npm
• Environment variables for each service (see .env.example or .env in each app)

Setup

1. Clone the repo:

   git clone https://github.com/joel909/Zap-Development.git
   cd Zap-Development

2. Install dependencies:
   Do this in each app/website directory

   cd zap-backend-api && yarn install
   cd ../zap-customer-api && yarn install
   cd ../zap-in-frontend/zapbs && yarn install
   cd ../zap-web-admin && yarn install

3. Set up environment variables:

   • Copy .env.example to .env in each directory.
   • Set Firebase credentials, ports, and other secrets for local development.

4. Start the services:
   In separate terminals, run:

   cd zap-backend-api && yarn start
   cd ../zap-customer-api && yarn start
   cd ../zap-in-frontend/zapbs && yarn dev
   cd ../zap-web-admin && yarn dev

   Make sure each API & website points to the correct endpoints!

---

📦 Dependencies

Each service and website has its own dependencies, managed via package.json. Key dependencies include:

• express
• firebase-admin
• next (for frontend)
• react
• firebase (for frontend/firebase usage)

---

🔗 Inter-Service Dependencies

• Admin website needs both the backend API and customer API running for full admin features.
• Customer website talks to customer API for queue operations.

---

🛠️ Scalability & Modularity

• Each API is a separate Express app, making backend logic modular.
• Next.js apps are fully decoupled, allowing independent deployment and scaling.

---

🗃️ Database Schema Visualization

See the screenshots (images 1–4 above) for an actual look at the Firestore database structure:

• users collection: stores user documents (uid, auth info, etc.)
• queues collection: stores queue definitions
• queues/{queueId}/users: users in a queue
• queues/{queueId}/history: users who left/completed the queue

Admins have a schema very similar to users.

---

🎥 Demo

Check out the attached repo media for a project walkthrough and database tour!

20250723-1240-30.2655375.mp4

---

📣 Credits & Contact

Project by my team @Zap.
(For support, use the official repo issues—not email.)

---

Enjoy the end of waiting in lines!