Functional Requirement Document (FRD)

This Functional Requirement Document specifies what Tutor 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

Tutor groups functionality into nine functional areas. Lesson 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-lesson catalogue with faceted filtering (subject, study level, lesson format, price, location) and sorting; results are cached for hot public pages.
• Lesson detail renders the description, what's included (amenity groups), scheduled lesson times with per-time availability, ratings (rating_avg/rating_count), approved reviews, and nearby places.
• Lesson categorisation via listing_master_items (subject / study-level / category tags); tutor profiles aggregate lesson count and rating.
• Paid extras (e.g. exam-board past-paper packs, extra revision materials) surface on the lesson 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 (a lesson time expanded from the tutor's weekly availability) with its remaining capacity so the client can render bookable lesson times.
• Quote — POST /api/v1/listings/[slug]/quote re-prices a proposed booking server-side (lesson time, session 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 the lesson time 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 lesson/lesson-time 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.

Lesson Times & Availability

Booking statuses: pending, confirmed, cancelled, refunded.

• Lesson times. Each lesson (listings) runs on the tutor's published weekly hours, expanded on read into scheduled experience_sessions rows (lesson times) with a fixed capacity (seats_total); seats_booked tracks claimed capacity. A lesson time is bookable while capacity remains and its date/time is in the future.
• Atomic capacity claiming. On checkout the requested capacity is claimed in a single guarded update (seats_total - seats_booked >= n) so two students cannot double-book the same lesson time.
• Booking modes. per_person books an individual session at the per-session price; private books the whole lesson time for a party (e.g. a small-group lesson).
• 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; the lesson time is 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 (Tutor)

Portal under /host (host session).

Admin / CMS

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

• catalogue — listings (lessons), lesson times, master-data (categories / subjects / study levels), extras, amenities.
• bookings (with per-booking detail and Mark as Paid), refunds (approval queue), customers, hosts, 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

• Tutor 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 Lesson-time capacity is 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 the lesson time 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