1System Overview

The MK Head & Scalp Spa Booking System is a complete, custom-built platform managing every aspect of spa operations — from online bookings and payments to therapist scheduling, customer records, a wall calendar display, and a walk-in kiosk.

1.1 Architecture

Booking Page	book.html — customer-facing online booking wizard
Admin Panel	admin/index.html — full management dashboard
Calendar Display	calendar.html — wall screen / TV display
Kiosk Screen	kiosk.html — customer check-in touch screen
Manage Booking	manage.html — customer self-service
Backend	Node.js + Express, running on your Windows 11 machine
Database	Microsoft SQL Server (MKHeadBooking database)
Payments	Square API
Email	Resend transactional email
Public Access	Cloudflare Tunnel routing mkhead.com to your local server

1.2 Local URLs

Booking Page	http://localhost:3300/book.html
Admin Panel	http://localhost:3300/admin/
Calendar Screen	http://localhost:3300/calendar.html
Kiosk	http://localhost:3300/kiosk.html
Manage Booking	http://localhost:3300/manage.html

2Daily Startup & Shutdown

2.1 Starting the System

Open two PowerShell windows each morning:

2.2 Stopping

Press Ctrl+C in each PowerShell window to stop gracefully.

3Admin Panel

The admin panel is the central management interface. Navigate to http://localhost:3300/admin/ and sign in with your email and password.

---

3.2 Dashboard

Auto-refreshes every 30 seconds. Contains:

• Stat cards — Today's appointments, week/month revenue, recurring customers, cancellations, no-shows
• Customer alerts — Customer-initiated modifications and cancellations, with timestamps and a "Mark seen" button
• Recent transactions — Last 10 payments with amount and payment method
• Today's appointments — Full list with Check In, No-Show, and Detail actions
• Top services this month — Popularity bar chart with booking count and revenue

---

3.3 Calendar

Two views toggled with buttons at the top:

• Day view — Single day, 8am–9pm, quarter-hour gridlines (:15, :30, :45)
• Week view — Mon–Sun overview, one column per day

Appointment color coding:

Yellow	Scalp services
Green	Hair services
Pink	Couples services
Blue	Other / uncategorized
PAID badge	Card payment — shown at lower right of block
👥 icon	Multi-therapist booking

---

3.4 Bookings

Four tabs: Confirmed, Completed, Cancelled, No-Shows. Use the + New Booking button to create admin-side bookings without requiring payment.

From each booking's detail modal you can: edit date/time/customer details, add admin notes, mark as no-show, complete, or cancel.

---

3.5 Reports

Revenue	Bar chart + table showing bookings, revenue, tips, cancellations. Daily / Weekly / Monthly. Export to CSV.
Customers	Full customer list with visit count, lifetime spend, and last visit. Export to CSV.
Services	Booking count and revenue per service across all time.

---

3.6 Services

Name & Category	Category sets the calendar color and groups services on the booking page
Duration	In minutes — drives availability slot sizing
Base Price	In dollars, before add-ons, fees, or tips
Therapists Required	1 for solo, 2+ for couples or group services
Buffer Before	Minutes blocked before start — for setup/prep (0 to disable)
Buffer After	Minutes blocked after end — for cleanup (0 to disable)
Add-on Modifiers	Extras like Hot Stones or Coconut Oil — added inline with the + Add button

---

3.7 Therapists

• Schedule — Set which days of the week and what hours each therapist works
• Block Time — Mark specific dates or ranges as unavailable (vacations, sick days, breaks)
• Availability checking requires all required therapists to be free simultaneously

---

3.8 Payment Settings

Mandatory rules	Always applied at checkout — customer cannot remove (e.g. Illinois Sales Tax 10.25%)
Optional rules	Shown with a toggle — customer can turn off (e.g. processing fee)
Fixed amount	A flat dollar fee, e.g. $5.00
Percentage	Calculated on subtotal before tip, e.g. 8.75%
Tips	15%, 18%, 20%, 25%, and custom — always shown, tracked separately per booking

---

3.9 Users & Permissions

Role	Access
Owner	Full access — all pages including user management
Manager	All pages except Users — services, payments, reports, customers, waivers
Staff	Dashboard, Calendar, Bookings only — for front desk use
Read-only	Dashboard and Reports only — for accountants or observers

---

3.10 Settings

Booking Slot Interval	10, 15, 20, 30, 45, or 60 minutes between available slots on the booking page
Minimum Lead Time	Hours in advance a booking must be made (0 = same day allowed)
Max Days Ahead	How far ahead customers can book (default 90 days)
Calendar Refresh	Auto-refresh interval for the standalone calendar screen (30s – 300s)
Kiosk Refresh	Auto-refresh interval for the kiosk screen
Auto-Complete	Enable/disable automatic completion of past bookings
Auto-Complete Delay	Minutes after end time before marking confirmed → completed
Check-In Window	Minutes before appointment that kiosk check-in is available
Spa Name	Displayed on emails and the booking page
Timezone	Used for scheduling calculations (default: America/Chicago)

---

3.11 Customers

Complete customer database merged from Setmore, Square, and online bookings. Features:

• Search by name, email, or phone (real-time as you type)
• View visit count, lifetime spend, last visit, and data source badge
• Add, edit, or remove customers manually
• Import CSV — matches on email or phone to avoid duplicates; updates existing records with richer data
• Export CSV — full customer list with all fields for use in other systems

---

3.12 Waivers

View all health and consent waivers submitted via the kiosk. Each entry shows the customer name, email, submission date, booking reference (if linked), and whether a signature was captured. Click any row to view the full waiver including the digital signature image.

4Customer Booking Page

A 5-step wizard accessible at mkhead.com/book.html. Customers can book from any device.

Step 1 — Choose a Service

Services grouped by category. Each card shows the service name, description, duration, therapist count, and starting price. If add-ons are available, a checkbox list appears below the selected service.

Step 2 — Choose Therapist(s)

Solo services require one therapist; couples services require two. Customers select their preferred therapist(s) by name.

Step 3 — Pick a Date & Time

Available slots are shown based on the therapist's schedule, buffer times, and existing bookings. Today is selectable; past time slots are automatically filtered out. The slot interval is configurable in Settings.

Step 4 — Your Details

Customer enters name, email, phone number, and any special notes (allergies, preferences).

Step 5 — Payment

Full order summary with live recalculation as the customer selects tips and toggles optional fees. Two payment methods:

• Pay by Card — Square payment form, charged immediately
• Pay at Spa — Booking confirmed without charging; payment collected at arrival

A confirmation email is sent automatically after booking. The confirmation screen shows the booking reference (e.g. MK-A1B2C3).

5Customer Self-Service

Customers can reschedule or cancel their own bookings at mkhead.com/manage.html — no account required, just their booking reference and email.

Reschedule

Customer picks a new date and time for the same service and therapist(s). The system checks live availability. Must be done at least 24 hours before the appointment.

Cancel

Customer cancels with an optional reason. Must be done at least 24 hours in advance. Both the customer and admin@mkhead.com receive email notifications, and an alert appears on the admin dashboard.

6Standalone Calendar Screen

Designed for a wall-mounted TV or dedicated tablet in the spa. Open http://localhost:3300/calendar.html.

Features

• Dark branded theme with live clock (hours, minutes, seconds)
• Animated countdown ring showing seconds until next refresh
• Navigate between days with ← → arrows, jump to Today
• Timeline view — all therapists, side-by-side overlap columns
• By Therapist view — one dedicated column per therapist
• Color-coded appointments, PAID badge, 👥 multi-therapist indicator
• Red "now" line at current time

Setup

• Open in Chrome, press F11 for full screen
• Disable screen auto-lock on the display device
• Log in to the admin panel once on this device so the session token is cached
• Set refresh interval in Admin → Settings → Calendar Screen Refresh

7Customer Kiosk

A touch-screen check-in station for the waiting area. Open http://localhost:3300/kiosk.html on a tablet or touchscreen.

Check-In Flow

Walk-In Waiver Flow

Waiver Fields

Personal Info	Name, date of birth, email, phone
Emergency Contact	Name and phone number
Medical Conditions	Any conditions the therapist should be aware of
Scalp Conditions	Psoriasis, eczema, open wounds, recent chemical treatments
Medications	Current medications that may affect treatment
Allergies	Product, chemical, or other allergies
Recent Treatments	Color, relaxer, keratin, etc. in the last 30 days
Consent	Four consent statements — all must be checked to proceed
Digital Signature	Drawn with finger or stylus, saved as image

Recommended Setup

• Chrome on an Android tablet or iPad in Guided Access / Kiosk mode
• Screen always-on, auto-lock disabled
• Set refresh interval in Admin → Settings → Kiosk Screen Refresh

8Square Payment Configuration

8.1 Sandbox (Testing)

Test card: 4111 1111 1111 1111 · Any future expiry · Any 3-digit CVV · Any ZIP

View sandbox transactions at squareupsandbox.com/dashboard

8.2 Going Live

9Troubleshooting

"Cannot connect to SQL Server"	Open SQL Server Configuration Manager → Enable TCP/IP → Restart the SQL Server service
"Login failed" on admin panel	Check that ADMIN_KEY in .env matches what you are typing. Log out and back in after any .env change.
Port already in use (EADDRINUSE)	Run: netstat -ano | findstr :3300 then taskkill /PID <number> /F
Emails not sending	Check RESEND_API_KEY in .env. Verify mkhead.com domain is confirmed in the Resend dashboard.
Square card form missing	Ensure SQUARE_APP_ID in book.html matches your environment (sandbox vs production)
Calendar shows no events	Log in to the admin panel on that device first — the calendar uses the stored session token
No available time slots	Check the therapist's weekly schedule is set in Admin → Therapists → Schedule
Import CSV fails (too large)	The server body limit is 10MB. If your file is larger, split it and import in batches.
doLogin is not defined	JavaScript syntax error in admin.html — check browser console for the error line and replace the file

10Maintenance & Data

10.1 Backing Up

In SQL Server Management Studio: right-click MKHeadBooking → Tasks → Back Up. Schedule weekly backups to an external drive or cloud location.

10.2 Sample Data

10.3 Database Migrations

When updating to a new version, run migrations in order:

10.4 Configuration Files

server\.env	All secrets and environment variables — never share or commit this file
cloudflared\config.yml	Cloudflare Tunnel routing configuration
public\book.html	Contains SQUARE_APP_ID and SQUARE_LOCATION_ID constants that must be updated for production