---

About

VitaQ is a web-based community clinic appointment and queue management system designed for public health clinics in South Africa. It helps patients book appointments, join queues remotely, and track their status in real time — while giving clinic staff and administrators the tools to manage patient flow efficiently.

Built as part of the COMS3009A Software Design course at the University of the Witwatersrand, following the Agile Scrum methodology across four sprints.

Live Application

URL: https://vitaq-gkcudzf2asfeevgq.southafricanorth-01.azurewebsites.net/

Role	Email	Password
Patient	test_patient@gmail.com	patient123
Staff	test_staff@gmail.com	staff123
Admin	test_admin@gmail.com	admin123

Features

Patient

• Register and log in (email/password or Google OAuth)
• Search and discover clinics across South Africa (893 imported facilities)
• View available appointment slots and book appointments
• Cancel or reschedule existing bookings
• Join a virtual queue and track live position with estimated wait times
• Receive near-turn notifications when close to being seen
• Get email reminders 30 minutes before an appointment

Staff

• Register as a clinic staff member (pending admin approval)
• Manage the daily queue: advance patients through waiting → in consultation → complete
• Add walk-in patients directly to the queue
• Create recurring weekly slot templates and generate dated appointment slots

Admin

• Review and approve or reject staff registration requests (with email notifications)
• Manage clinic details (edit info, toggle active/inactive status)
• View analytics dashboards: wait times by clinic/day/hour, no-show rates
• Export reports as CSV or PDF

Tech Stack

Layer	Technology
Frontend	HTML, JavaScript (vanilla), Tailwind CSS v4.2
Backend	Node.js, Express v5
Database & Auth	Supabase (PostgreSQL + Row Level Security + Auth)
Email	Resend API
Deployment	Microsoft Azure App Service (South Africa North)
Testing	Jest (unit tests), Codecov (coverage reporting)
CI/CD	GitHub Actions

Project Structure

VitaQ/
├── backend/
│   ├── server.js                  # Entry point — starts Express on configured port
│   ├── src/
│   │   ├── app.js                 # Express app setup, middleware, route mounting
│   │   ├── lib/
│   │   │   ├── supabaseClient.js  # Shared Supabase client (service role)
│   │   │   └── emailClient.js     # Resend email provider wrapper
│   │   ├── middleware/
│   │   │   └── auth.js            # JWT auth, requireStaff, requireAdmin guards
│   │   ├── modules/
│   │   │   ├── admin/             # Clinic management, staff request review
│   │   │   ├── analytics/         # Wait-time and no-show analytics
│   │   │   ├── appointments/      # Booking, cancellation, rescheduling
│   │   │   ├── clinics/           # Clinic search and discovery
│   │   │   ├── notifications/     # Email reminders and staff decision emails
│   │   │   ├── queue/             # Queue join, status, prediction, walk-ins
│   │   │   ├── reports/           # CSV and PDF report exports
│   │   │   ├── slots/             # Appointment slot queries and availability
│   │   │   └── staff/             # Staff registration, slot template CRUD
│   │   └── utils/
│   └── tests/                     # Jest unit tests for all modules
├── frontend/
│   ├── assets/                    # Images, CSS (Tailwind output)
│   ├── js/
│   │   ├── features/              # Page-specific scripts (one per route)
│   │   └── shared/                # Auth helpers shared across pages
│   ├── lib/
│   │   └── supabaseClient.js      # Browser-side Supabase client
│   └── pages/                     # HTML pages (landing, login, register, dashboard, etc.)
├── supabase/
│   ├── migrations/                # SQL schema: tables, views, RLS policies, indexes
│   ├── scripts/                   # Data import scripts (SA clinic dataset)
│   └── seed/                      # Seed data for clinics and appointment slots
├── uml/                           # UML diagrams (use case, class, sequence, component, deployment)
├── jest.config.js                 # Test configuration
├── package.json                   # Dependencies and scripts
└── codecov.yml                    # Code coverage settings

Prerequisites

• Node.js v18 or later
• npm v9 or later
• A Supabase project with Auth enabled
• (Optional) A Resend account for email functionality

Local Setup

1. Clone the repository

   git clone https://github.com/Gradient-Ascenders/VitaQ.git
   cd VitaQ

2. Install dependencies

   npm install

3. Configure environment variables

   Create a .env file in the project root. You will need your own Supabase project with Auth enabled. The minimum required values are SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, and PORT=3000. Email notification variables are optional and only needed if you want to test appointment reminders or staff decision emails locally.

   SUPABASE_URL=your_supabase_project_url
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   PORT=3000
   
   # Optional email configuration for reminder/notification testing
   EMAIL_ENABLED=false
   RESEND_API_KEY=your_resend_api_key_if_email_is_enabled
   EMAIL_FROM=your_verified_sender_email

   Security note: Do not commit the .env file or service-role keys to GitHub. Keep real secrets local or in the deployment provider's environment variable settings.

4. Set up the database

   Apply the SQL files in supabase/migrations/ to your Supabase project in order, then run the seed files in supabase/seed/ to populate clinic and slot data. The full schema (tables, views, RLS policies, and indexes) is defined in the migration files.

   Note: The live application is already fully configured and accessible at the URL above — local setup is only needed for development purposes.

5. Build Tailwind CSS

   npm run tw:build

6. Start the server

   npm start

   The application will be available at http://localhost:3000.

Running Tests

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

Tests are located in backend/tests/ and cover all service modules, middleware, and controllers. Coverage reports are generated in the coverage/ directory.

Team

Contributor	Student Number
Kevin Ebrahim	2801913
Uzair Mahomed	2802191
Caleb Perumalsamy	2826779
Tyron Van Tonder	2885498

License

This project was developed for academic purposes as part of COMS3009A at the University of the Witwatersrand.