Product Documentation

What Product Can Change

Product and content teams can update page content, funnel order, routing, CTA targets, SEO metadata, header and footer chrome, and supported A/B test references through Sanity.

• Landing pages publish at /{slug}.
• Questionnaire funnels publish at /questionnaire/{funnel-slug}.
• Submit flows add post-funnel screens before the survey payload is sent.
• Corporate content, such as side effect pages, is also routed through the same frontend.

What Still Needs Engineering

The CMS can compose existing content types, but new user experience patterns still need code support.

• A new landing-page block needs a Sanity schema, a GROQ projection, and a renderer in Funnel CMS.
• A new question input type needs schema support plus a matching React input component.
• New routing behavior needs runtime logic and focused tests, not only Sanity fields.
• New tracked events or submission fields need analytics or survey-service changes.

Product Planning Notes

Treat the CMS as the control plane for configured experiences, not as a generic page builder that can safely express any UI. Product specs should name whether a request is content-only, schema-only, renderer work, routing work, or downstream submission work.

How Landing Pages Work

A landing page document owns the URL slug, SEO metadata, default CTA funnel, optional PostHog experiments, page content, and header or footer overrides.

• The page builder supports rows plus approved blocks such as hero, product hero, text, image, CTA, pre-quiz, feature list, accordion, guarantee, pricing, testimonial, promo banner, spacer, and video.
• The frontend renders each block through a type-specific component.
• Product hero content switches the page into the product-detail layout.
• Page-level CTA funnel settings are used as a fallback when individual blocks do not provide their own target.

Safe Content Changes

Most copy, media, block ordering, SEO, and CTA target changes can ship through Sanity without a code release.

• Keep landing-page slugs stable once traffic is pointed at them.
• Use noindex for QA, paid-only, or temporary pages that should not appear in search.
• Confirm that any CTA funnel target exists and is published before moving traffic.
• Check mobile presentation for content-heavy rows and product hero sections.

When To Ask Engineering First

Engineering should be involved when a page needs a new block type, new experiment resolution behavior, new tracking semantics, unusual routing, or a content model that existing blocks cannot express cleanly.

Funnel Building Blocks

A funnel is an ordered list of questions and interstitials. Questions collect answers. Interstitials explain, qualify, or transition the user. Submit flows can add screens after the main funnel before submission.

• Questions can be reused across funnels.
• Routing rules live on question and interstitial documents so reused content keeps consistent branching behavior.
• Questions can be pinned near the end when they should run after routing decisions.
• A funnel can set defaults such as medication, progress display, back navigation, save-progress behavior, disqualification state, and banner configuration.

Routing Model

Routing rules compare captured answers against configured conditions and then route to a funnel, question, or interstitial.

• Conditions use mapped fact keys, not only visual question labels.
• Multiple conditions can be combined with AND or OR.
• Cross-funnel routes need the target funnel to be published and reachable.
• Product specs should define expected paths for default, qualifying, and disqualifying users.

Submit Flow Model

A submit flow is a reusable mini-flow shown before the final API submission. The last submit-flow item triggers submission either automatically or on a button click.

• Use submit flows for final confirmation, education, or extra collection that belongs after questionnaire completion.
• Keep the final submit behavior explicit because it changes when answers are sent downstream.
• Changes to submission payload fields need engineering validation even when the visible screen is CMS-authored.

What Can Be Tested

The CMS supports configured experiments for full landing-page variants, landing-page CTA funnel targets, full funnel variants, and question-level variants.

• The current Sanity document is the control or default.
• PostHog assignment selects a configured variant when one exists.
• Missing or failed evaluation falls back to control content.
• Draft mode skips funnel variant redirects so editors preview the document they are editing.

Product Guardrails

Experiments should be planned around a stable user decision point and a measurable conversion or quality metric.

• Reuse a flag only when multiple fields must share the same assignment.
• Do not reuse a flag across unrelated user decisions.
• Keep variant question types compatible with the control question.
• Define what happens when assignment is unavailable.

What Needs Extra Validation

Experiments that move users between funnels, change CTA targets, or alter submission-impacting questions should get regression coverage for the exact path being changed.

Publishing Model

Sanity publish events are expected to invalidate the frontend cache for affected pages and funnels. Stable staging and production environments use signed webhooks plus bounded time-based fallbacks.

• Landing-page and questionnaire routes both participate in cache invalidation.
• Referenced question, interstitial, and submit-flow changes can invalidate parent funnel paths.
• Draft mode and Presentation mode are for previewing unpublished content.
• Normal published questionnaire traffic avoids source maps and stega metadata to control payload size.

Product Expectations

Most published changes should appear quickly, but content operations should still verify the exact route after publish.

• Staging is the right place for QA before production release.
• PR previews can rely on shorter cache windows unless a temporary webhook is explicitly needed.
• If a change looks stale, first confirm whether it is a webhook issue, route fallback issue, or oversized payload issue.
• Permanent webhooks should point only at stable environment URLs.

Payload Budget

Next.js Data Cache entries must stay below 2 MB. Large page-builder expansions, broad asset projections, and full referenced-funnel expansion can put production traffic at risk.

• Keep CMS projections narrow.
• Avoid adding unused fields to public queries.
• Measure representative funnel payloads before merging schema or query changes.
• Split summary and detail data when product needs grow beyond the current route payload.

Release Model

Merges to main are the source of truth for staging. Production deployments are cut from main through Release Please and the shared repo tag.

• Funnel CMS deploys to Vercel.
• Studio deploys to Sanity.
• Redirect service has app-scoped validation and a separate rollout path.
• Rollbacks run through the manual GitHub Actions rollback workflow.

Product Change Types

Content-only changes usually move through Sanity publish and route QA. Code-backed CMS changes move through PR review, CI, staging, and release.

• Content-only: copy, media, ordering, SEO, and existing block configuration.
• Schema-backed: new Sanity fields or validation behavior.
• Runtime-backed: new renderers, routing behavior, submission fields, analytics, experiments, or cache changes.
• Operational: deploy, rollback, environment, webhook, and preview configuration.

Readiness Checklist

Before release, confirm the user route, Sanity document, experiment assignment, cache behavior, and downstream submission or analytics impact for the changed path.

• QA the public route, not only the Sanity preview pane.
• Check the default path and any routed or experiment variant path.
• Keep release notes business-readable.
• Use rollback tags or the rollback workflow when production recovery is needed.