Functional Requirement Document (FRD)

This Functional Requirement Document specifies what PubCrawl does from a behavioral perspective: its modules, pages, features, customer/host/admin/influencer flows, validation, and the business rules that govern them. It complements the Business Requirement Document by translating goals into concrete, testable functionality across the storefront, the customer, host and influencer portals, and the admin CMS — all served from one Next.js 16 application.

Module Overview

PubCrawl groups functionality into nine functional areas. Crawl listing and booking are part of the free core; premium integration providers unlock via CreativeCape add-on licensing.

Catalogue

Public storefront under / (the (site) route group).

Capabilities:

• Published-crawl catalogue with faceted filtering (theme, pace, format, price, location) and sorting; results are cached for hot public pages.
• Crawl detail renders the description, what's included (amenity groups), scheduled departures with per-departure availability, ratings (rating_avg/rating_count), approved reviews, and nearby places.
• Crawl categorisation via listing_master_items (theme / format / focus tags); host profiles aggregate crawl count and rating.
• Paid extras (e.g. a photo package) surface on the crawl page and are selectable at checkout.

Booking & Checkout

APIs under /api/v1/bookings and /api/v1/listings.

• Availability — GET /api/v1/listings/[slug]/availability returns each experience_sessions row with seats_total/seats_booked so the client can render bookable departures and remaining spots.
• Quote — POST /api/v1/listings/[slug]/quote re-prices a proposed booking server-side (departure, spot count, booking_mode per_person|private, extras) and returns the deposit and full amounts without creating a booking.
• Coupons & gift cards — coupons support PERCENT or AMOUNT discounts, a minimum total, a max-discount cap, redemption limits, a validity window, and scoping; gift cards are validated for ACTIVE status, currency, and balance.
• Payment methods — GET /api/v1/bookings/payment-methods lists the active gateways for the method picker.
• Booking creation — POST /api/v1/bookings/checkout re-prices server-side, re-validates the coupon, and claims spots atomically (seats_total - seats_booked >= seats), creating a bookings row keyed to the session_id with the chosen seats and booking_mode. The customer pays deposit or full; online gateways return a redirect/approval, offline methods return a pending booking.
• Verification — POST /api/v1/bookings/pay and the verify/return routes confirm payment with the driver and finalise the booking (recording a booking_payments row).

Payments

• Built-in online gateway: PayPal (Orders v2, redirect flow) using client-id/secret with test/live/sandbox modes.
• Offline method: Bank Transfer — creates a pending booking fulfilled by admin "Mark as Paid".
• Deposit or full. The customer may choose to pay a deposit or the full amount; the split is computed server-side from the crawl/departure pricing — never trusted from the client.
• Pluggable driver registry: premium gateways (e.g. Stripe, Razorpay, and more) ship as self-contained add-on drivers, configured in admin settings.
• Active gateway configuration is read from the integration_connections table (channel PAYMENTS), with secrets decrypted server-side only.

Departures & Spots

Booking statuses: pending, confirmed, cancelled, refunded.

• Departures. Each crawl (listings) runs on scheduled experience_sessions (departures) with a fixed seats_total; seats_booked tracks claimed spots. A departure is bookable while spots remain and its date/time is in the future.
• Atomic spot claiming. On checkout the requested spot count is claimed in a single guarded update (seats_total - seats_booked >= n) so two customers cannot oversell the same departure.
• Booking modes. per_person books individual spots at the per-spot price; private books the whole departure for a party.
• Cancellations & refunds. Tiered cancellation policies (flexible / moderate / firm / strict / non-refundable) determine the refund amount from the policy and lead time. Both customer-initiated and host-initiated cancellations are supported; spots are released on cancellation and the request enters the admin refund approval queue (booking_refunds). Email/WhatsApp/SMS notifications are sent.
• Extras & notes — booking_extras records paid add-ons on a booking; booking_notes and booking_emails capture internal notes and the message trail.

Customer Portal

Portal under /customer (customer session, dynamically rendered to reflect live theming).

Host (Guide)

Portal under /host (host session).

Admin / CMS

Panel under /admin/(panel) (admin session, permission-gated).

• catalogue — listings (crawls), departures, master-data (themes / formats / focus), extras, amenities.
• bookings (with per-booking detail and Mark as Paid), refunds (approval queue), customers, guides, dashboard (revenue/analytics).
• marketing — coupons, gift-cards, partners, testimonials, leads. subscription — host subscription plans.
• Content/CMS — pages, blogs (+ categories), hero-slider, gallery, faqs, reviews, about, menus, theme builder, builder-pages.
• influencers — affiliate accounts, commissions, payouts.
• settings sections include: channels/integrations, notifications (email/sms/whatsapp/in-app/push/webhook) + notification-log, languages, currencies, countries, locations, invoice, theme, roles, permissions, users, api-tokens, webhooks, license, master-data, advanced, activity.

Add-ons & Licensing

• PubCrawl ships 53 channel integration providers across categories — Payments, Email, Storage, Analytics, Calendar, CAPTCHA, Realtime Chat, AI Chatbot, Live Chat, SMS, Social Auth, WhatsApp.
• Free defaults include SMTP (email), PayPal + Bank Transfer (payments), Cloudflare R2 (storage), and GA4 (analytics); other providers are premium.
• Gating. A premium provider serves only when unlocked. Activation is per-add-on via an Envato-style purchase code entered in admin → Add-ons, exchanged once for an RS256 JWT bound to { addon, domain } and then verified offline on every check; the domain license can also grant entitlements ("*", a channel id, or "channel:provider"). Localhost/dev hosts are unlocked.
• Toggling. Server-side gates (premiumBlock / featureBlock) and the client useFeatureActive() hook check installation and entitlement before exposing a feature.

Auth & Permissions

• Auth routes (/(auth)): login, register, forgot-password, reset-password, verify-email.
• OTP/verification delivery channel is admin-configurable; a QA test-contact/test-code bypass exists for staging.
• Admin RBAC — permissions-catalog.ts defines resources × CRUD actions; requirePermission(action, resource) enforces per route and returns 403 when denied, emitting an audit event on mutations. System/super roles bypass the matrix.

Validation & Business Rules

• Server-side re-pricing: booking totals, deposits, coupons, and gift-card balances are recomputed on the server at booking time — never trusted from the client.
• File uploads pass through the server to R2/S3; images are processed (resize/convert) with sharp before storage.
• BR-A Spots are claimed atomically; a booking is created only if seats_total - seats_booked >= seats.
• BR-B A booking is confirmed only when payment (deposit or full) succeeds; offline bookings require admin Mark as Paid.
• BR-C Cancellations release spots and compute a tiered refund routed through the admin approval queue.
• BR-D Premium add-ons require a valid entitlement or purchase code (dev/localhost unlocked).
• BR-E Integration secrets are stored AES-256-GCM encrypted and never returned to clients.
• BR-F Admin mutations are permission-checked and audited.

For functional questions or feature requests, contact support at creative-cape.com.

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