Quick Start

Welcome to Music Lessons — a production-ready private lesson booking marketplace built with Next.js 16 (App Router), React 19, TypeScript, PostgreSQL and Tailwind CSS. This page gets you from a fresh download to a running site in about 15 minutes.

Music Lessons ships as a vertical pack product: the engine is generic, and a pack supplies the vocabulary, fields, filters, master data and demo content for one business. The pack included is Music Lessons — instructors publish their weekly availability and students book a lesson slot and pay. Switching the pack changes every noun on the site (lesson → consultation, instructor → practitioner, student → patient) without touching engine code.

New here? Read Product Overview for the big picture, then come back to install.

What you need

• Node.js 20+ and npm
• A PostgreSQL database (we recommend Neon — Music Lessons uses the @neondatabase/serverless driver)
• About 15 minutes

Install in 4 steps

# 1. Install dependencies
npm install

# 2. Create your environment file
#    Create .env.local with at least DATABASE_URL (JWT_SECRET / SECRET_KEY
#    are auto-generated by the install wizard's database step if unset).

# 3. Initialise the database (schema + seed)
npm run db:init

# 4. Start the dev server
npm run dev

Open http://localhost:3000. The first run launches the install wizard at /install — it walks you through the database check, admin account, and store settings.

Load the demo

# Apply the vertical pack: master data, categories, fields, filters, copy
npx tsx scripts/apply-vertical.ts music-lessons --yes

# Seed demo instructors, listings, availability, bookings and reviews.
# Imagery comes from Pexels — set PEXELS_API_KEY in .env for real photos,
# otherwise deterministic placeholders are used.
npm run vertical:demo

# Subscription plans for the demo hosts (cascades off hosts, so re-run after a re-seed)
npx tsx scripts/seed-plans.ts --hosts

# Storefront pages (privacy, cookies, terms, refunds, about)
npx tsx scripts/seed-site-pages.ts

# Booking lifecycle templates for Email, WhatsApp and SMS (booking confirmed,
# cancelled, payment received, refund issued, waitlist offer)
npx tsx scripts/seed-message-templates.ts

Demo logins — password Password@1:

The two booking mechanics

The active pack declares which one it uses; the booking engine, calendar and checkout follow. Music Lessons runs in slot mode: an instructor sets weekly availability once, and a student books a specific 30/45/60/90-minute lesson time from it.

What the Music Lessons pack gives you

Eight categories — Piano, Guitar & Bass, Voice & Singing, Strings, Drums & Percussion, Woodwind & Brass, Kids & Youth Music and Theory & Composition — plus seven of its own master tables on top of the shared ones: instrument, session_type, intensity, focus, music_practice, equipment and certification. Booking runs on the slot engine — instructors set weekly availability and students book a lesson time, the same mechanism the healthcare pack uses for appointments. All master tables are admin-editable under Master Data, and they drive the listing editor, the browse facets and the instructor profile.

The listing editor further splits an instructor's own answers to those fields into three tabs — Details (instrument, session type, intensity, level, delivery mode…), Format & Practice (focus, technique, equipment, warm-up, prerequisites) and What to Expect (what happens, what to bring, who it's for) — rather than one long form.

Waitlists

Slot mode is 1:1 by design, but a specific time can still be popular. Waitlists (session_waitlist) mean a fully-booked slot is no longer a dead end: students queue for it, and when that booking is cancelled the front of the queue is notified automatically across Email, WhatsApp, SMS and Push. An offer is a head start, not a hold — the student still checks out normally.

Multi-session courses (session_series — one purchase covering a block of dated sittings) are a seat-mode feature and don't apply to Music Lessons' slot-based booking.

Notifications

Four channels, all template-driven from Settings → Notifications (message_templates) and all silent until their provider is connected under Settings → Channels. Every booking-lifecycle template ships worded from the active pack's own vocabulary — run npx tsx scripts/seed-message-templates.ts (core events) and npx tsx scripts/seed-notification-templates.ts (push + waitlist) to (re)populate them after switching packs.

Push additionally needs a Firebase service account under Settings → Push. The mobile app registers each device with POST /api/v1/customer/fcm/token; tokens are pruned automatically when FCM reports them unregistered, and every send respects the student's notify_push preference.

booking-reminder (Email/WhatsApp/SMS) templates are seeded and ready, but nothing currently schedules them — wire a cron task that finds upcoming sessions and calls notifyEmail/notifyWhatsApp/notifySms("booking-reminder…", …) if you want lesson reminders to actually go out.

Core environment variables

See the Installation Guide for the full list and the License Guide for activation.

Where to go next

• Installation Guide — detailed setup
• Deployment Guide — ship to production
• Admin Guide — run your studio day-to-day
• API Documentation — the REST surface, plus the live reference at /api/docs/v1
• Add-on Development Guide — extend Music Lessons
• Customization Guide — change the vertical's fields, filters and vocabulary

© CreativeCape Solutions · creative-cape.com · support@creative-cape.com