Website Service Integration Contract

Website Service Integration Contract

This note defines the default generator-side integration model for QuantaLumin websites.

The goal is not to hide every application behind the brochure domain. The goal is to let authored websites integrate cleanly with the shared service stack.

Default Model

  • generator owns brochure pages, structured content blocks, and widget shells.
  • central applications keep their own domains and service boundaries:
    • booking.*
    • payments.*
    • registration.*
    • shop or product apps on their own dedicated host when needed
  • brochure pages usually integrate those apps through widgets and site-facing route shims such as /_platform/* or /api/pay/checkout/*.
  • full same-origin app shells such as TutorLumin /app are exceptions for first-party product surfaces, not the general pattern.

First-Wave Website Integrations

These are the first integrations generator should treat as canonical across sites.

1. Booking

Use the existing booking widget when the website needs live availability, reservation intake, and optional hosted checkout continuation.

  • generator surface:
    • booking shortcode / fenced block
  • backend owners:
    • booking for reservation intake and schedule state
    • payments for hosted checkout
    • registration only when the booking flow also needs post-payment account continuation

When booking is authored with registration continuation, the hosted checkout success target should continue into registration rather than bounce back to a generic brochure page. Generator now treats registration_success_url as the default checkout-success path unless the authored success_url already carries checkout_session_id.

2. Public Calendar

Use the existing calendar widget for read-only event and availability views.

  • generator surface:
    • calendar shortcode / fenced block
  • backend owner:
    • booking public feed

3. Course Purchase

Use the existing coursepurchase widget when a website should start a paid course or enrolment flow from brochure content.

  • generator surface:
    • coursepurchase shortcode / fenced block
  • backend owners:
    • registration for intake and continuation
    • payments for hosted checkout when customer credit does not fully cover the purchase

This is the preferred brochure-side entry for TutorLumin-style course enrolment.

4. Membership Or Bundle Purchase

Use the existing purchasemembership widget when a website should start a membership or bundle handoff from brochure content.

  • generator surface:
    • purchasemembership shortcode / fenced block
  • backend owners:
    • payments for signup handoff orchestration and hosted checkout
    • registration when the handoff continues into account finalization

This is the preferred brochure-side entry for QuantaLumin membership and TutorLumin plus QuantaLumin bundle-style offers.

5. Shop

Shop is currently a content contract, not a brochure widget family.

  • generator surface:
    • shop section content and product bundles
  • backend link targets:
    • dedicated shop app
    • payments handoff
    • enquiry/contact flow

Do not force shop pages into the same shape as booking or course purchase widgets. Product-led sites often need richer editorial product pages with a CTA that hands off to a separate commerce surface.

6. Product And Class Catalogs

Use catalog_grid when the page needs a shared editable grid for products, classes, memberships, or other offer cards without committing to the full shop bundle model.

  • generator surface:
    • catalog_grid shortcode / fenced block
  • typical use cases:
    • TutorLumin class offers and short courses
    • Rawson class pages or client-managed class details
    • TechnoAntiques products and services
  • backend handoff:
    • a catalog_grid card can link out to booking, payments, or a shop detail page when needed

Treat catalog_grid as the editorial collection surface. Keep the full /shop bundle layouts for item detail pages and archive storefronts.

Registration And Payments

registration and payments are not normally rendered as standalone brochure widgets.

Instead:

  • registration is the continuation target reached from course purchase, booking, or AI-tuition flows
  • payments is the hosted checkout or payment handoff surface reached from widgets and commerce CTAs

That means the usual brochure responsibility is:

  • collect the minimum decision or intent on-page
  • redirect or continue into the owned service at the correct seam

Generator Authoring Guidance

Use these defaults when shaping new website integrations:

  • prefer fenced structured blocks for interactive brochure widgets
  • prefer /_platform/* or explicit payment handoff paths for site-origin API integration
  • keep app ownership on the service domain unless there is a deliberate first-party app shell
  • keep Nextcloud and other workspace tools on dedicated subdomains, not behind brochure paths

Shared Widget Contract

Interactive brochure widgets that hand off into booking, payments, or registration should share these runtime rules:

  • carry a stable flow_id into downstream URLs and request metadata
  • send x-qluster-flow-id and traceparent headers on widget-origin API calls
  • re-initialize on direct load, spa:route, ql:page-swapped, and late DOM insertion
  • keep service ownership in the destination app, not in brochure JavaScript

The shared runtime helper is:

  • widgetRuntime.js

Current adopters:

  • purchaseMembershipWidget.js
  • coursePurchaseWidget.js

Current Canonical Generator Surfaces

  • booking widget: layouts/partials/etc/booking.html
  • calendar widget: layouts/partials/etc/calendar.html
  • course purchase widget: layouts/partials/etc/coursepurchase.html
  • shop content contract: shop-section-contract.md