Quick Start

Welcome to PubCrawl — a production-ready pub crawl & nightlife tour 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.

PubCrawl 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 Pub Crawl & Nightlife Tours — guides publish dated crawls with a number of spots, and crawlers book a spot and pay. Switching the pack changes every noun on the site (crawl → consultation, guide → practitioner, crawler → 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 — PubCrawl uses the @neondatabase/serverless driver)
About 15 minutes

Install in 4 steps

Terminal

# 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

Terminal

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

# Seed demo guides, crawls, departures, 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

# A multi-week course block on one of the demo crawls
npx tsx scripts/seed-demo-course.ts

# 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

# Account emails, plus booking/waitlist templates for Email, WhatsApp, SMS and Push
npx tsx scripts/seed-message-templates.ts
npx tsx scripts/seed-notification-templates.ts

Demo logins — password Password@1:

Role	Email
Guide (host)	`host1@pubcrawldemo.com` … `host5@pubcrawldemo.com`
Crawler (customer)	`guest1@pubcrawldemo.com` … `guest5@pubcrawldemo.com`

The two booking mechanics

Mode	How availability works	Used by
`seat`	The host publishes dated sittings (`experience_sessions`) with a spot count.	Pub Crawl & Nightlife Tours, classes, tours, events
`slot`	The host sets weekly hours (`availability_rules`); slots are expanded on read and only become a row when booked.	Appointment businesses — clinics, salons, tutors

The active pack declares which one it uses; the booking engine, calendar and checkout follow. PubCrawl runs in seat mode.

What the Pub Crawl & Nightlife Tours pack gives you

Six categories — Classic Bar Hopping, Cocktail Crawls, Craft Beer Crawls, Themed & Costume Crawls, Private & Group Events and Rooftop & Speakeasy Nights — plus eight of its own master tables on top of the shared ones: crawl_theme, crawl_format, pace, focus, inclusion, extras_provided, time_of_night and guide_credential. All are admin-editable under Master Data, and they drive the listing editor, the browse facets and the guide profile.

Courses, blocks and waitlists

Two things a nightlife operator needs that a plain drop-in engine does not have:

Courses (session_series) — one purchase covering a block of dated departures: a season of weekly costume crawls, a multi-night bar-crawl festival, a recurring stag/hen package. A series owns no seat counter of its own; enrolling claims a place in every departure in the block, so a course and a one-off crawl compete for the same spots and can never oversell each other.
Waitlists (session_waitlist) — a full departure is no longer a dead end. Crawlers queue for a date, and when a booking is cancelled the front of the queue is notified automatically. An offer is a head start, not a hold: the crawler still checks out normally.

Notifications

Four channels, all template-driven from Settings → Notifications and all silent until their provider is connected under Settings → Channels:

Channel	Transport	Fired on
Email	Configured email add-on, SMTP fallback	Booking, reminder, cancellation, payment, waitlist
WhatsApp	Connected WhatsApp add-on	Booking, reminder, cancellation, payment, waitlist
SMS	Connected SMS add-on	Booking, reminder, cancellation, payment, waitlist
Push	Firebase Cloud Messaging → the mobile app	Booking, cancellation, waitlist

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 crawler's notify_push preference.

Core environment variables

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string
`JWT_SECRET`	Signs admin/customer session tokens
`SECRET_KEY`	AES-256-GCM key that encrypts stored integration secrets
`PEXELS_API_KEY`	Optional — real demo imagery instead of placeholders
`LICENSE_SERVER_URL`	License server (defaults to `https://creative-cape.com`)

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 operation day-to-day
API Documentation — the REST surface, plus the live reference at /api/docs/v1
Add-on Development Guide — extend PubCrawl
Customization Guide — change the vertical's fields, filters and vocabulary