Skip to main content

Flow Studio Non-Functional Requirements

Flow Studio is a maintained visual documentation, testing, and training layer for Mobilis chat products. Treat it as part of the system, not as a one-off prototype.

Product requirements​

  • Flow Studio must stay scenario-driven. Update scenario data before adding one-off UI behavior.
  • Flow Studio must be updated when product functionality, user-facing messages, moderation behavior, notification behavior, API contracts, connector behavior, destination behavior, role visibility, or publishing behavior changes.
  • Small wording, styling, and minor scenario-data adjustments update the current scenario. Major changes create or update a major iteration record.
  • Major iteration examples include changed message sequences, changed approval flow, changed pipeline states, changed API payload shape, changed permission model, new training mode, new public demo mode, or new feedback workflow.
  • Flow Studio must support desktop and mobile browser viewing.
  • Flow Studio must support role play for technical admin, developer, non-technical admin, community moderator, and submitter perspectives.
  • Product-forward Flow Studio surfaces should use the shared Mobilis Astro experience system when the surface is part of docs, demos, onboarding, sales, marketing, tenant previews, or self-service testing.
  • Astro-backed Flow Studio surfaces must still consume Flow Studio scenario data as the source of truth for roles, test cases, live checks, information links, and public-safety boundaries.
  • Astro-backed Flow Studio routes must use src/experience-system/scaffoldRegistry.mjs and src/experience-system/designTokens.mjs for shell metadata, template selection, and public-safe theme selection. They must not duplicate scenario steps, private technical links, denied-path rules, or viewer restrictions in page files.
  • Submitter and moderator workflows must show what the platform says and does, not implementation internals.
  • Technical admin and developer workflows may show APIs, state changes, audit trails, and implementation documentation when those details are relevant.

Visual and interaction requirements​

  • The active scenario, role, and surface controls must stay docked directly under the main header while scrolling.
  • Viewer switching must behave like an account/profile menu. After a viewer is selected, the menu must close automatically.
  • Lower-permission viewers must not be able to select or deep-link into higher-permission role views.
  • Non-technical viewers must receive user-friendly how-to documentation, not API or implementation documentation.
  • Technical-system scenarios that mention private dashboards, credential references, or internal control points must be restricted to the technical admin viewer profile unless a later authenticated access model says otherwise.
  • Conversational submission flows must use a chat-style intake surface. GLD desktop submission must support event links, flyer/image upload, pasted event text, and visible processing stages.
  • GLD chat submission MVP prototypes must support mock-preview mode first, with guarded Supabase review writes shown as disabled-by-default loopback storage until the explicit write gate is approved.
  • Admin/operator views must be able to edit prototype copy, step labels, button labels, dialog text, selected sample input, extracted-field preview, row-preview labels, audit-preview labels, and backlog connector labels in the browser and see the mock preview update immediately.
  • Admin/operator views must include a visual run map for mock submission flows so input capture, extraction, row preview, and deferred connector state are visible before and after a mock run.
  • Admin/operator views must expose a copyable scenario handoff packet for visual edits so approved mock changes can be converted into durable scenario-data pull requests without enabling live writes.
  • Submitter and moderator views must stay scoped to their own visible content, while admin/operator views may show raw input, extraction results, Supabase write previews, audit previews, role visibility, and backlog connector state.
  • Postponed connectors such as WhatsApp, The Events Calendar, EventON, WordPress/public publish, and social posting must remain visible as backlog stages when they are intentionally disconnected from the active MVP.
  • Flow Studio must visually show submitter responses, moderator/operator views, destination movement, notifications, and pipeline state in a way non-technical users can understand.
  • SEO/AEO and other self-service product demos must support premade public-safe datasets first, read-only live evidence second, and disabled-by-default write or publish actions until protected production controls exist.
  • Live read-only checks must label available, fallback, stale, unavailable, or unknown states plainly and show a safe fallback explanation when an expected public evidence artifact is not ready.

Chat-first admin and management requirements​

  • The default administrative and management surface should be chat-first. Most admin actions should be expressed as chat intents backed by server-authorized action contracts, not as dedicated handcrafted admin screens.
  • Dedicated admin screens are exceptions for dense visual review, batch operations, audit-heavy workflows, compliance review, complex comparison, or cases where chat plus embedded modules cannot represent the workflow clearly.
  • Chat must be able to render generated UI modules inside the conversation to manage functionality. Examples include review cards, edit forms, queue summaries, diff panels, status timelines, approval gates, filter chips, table slices, action receipts, and rollback panels.
  • Every new admin or management function must define a chat intent, action schema, role/scope requirements, dry-run preview behavior, commit behavior, denial path, audit receipt, and human fallback before it is treated as complete.
  • Every new admin or management function must also generate a public-safe Flow Studio/chat UI module preview for approval. The preview should show how the function is best represented visually inside chat before production or broader internal rollout.
  • UI modules should be generated from the same metadata, schema, and action contracts used by the underlying server action. Do not hand-code a visual representation that drifts from the canonical action contract.
  • Flow Studio scenarios must show both the conversational path and the generated UI module for new admin/management functionality, including lower-permission denial behavior when relevant.
  • Chat-first admin does not weaken authorization. Server-side permission checks, launch gates, idempotency, audit receipts, and explicit write confirmations remain mandatory for mutating actions.

Activity, Reversal, And Moderation Requirements​

  • User-facing chat products must define an activity log contract for meaningful user actions, assistant receipts, approval decisions, moderator actions, and state changes before persistent community storage is treated as complete.
  • Reversible activity must state who can reverse it, what reverse patch is applied, what user-visible effect changes, and which audit receipt records the reversal.
  • Same-user reversal and admin reversal are separate policies. Moderator actions such as warning, suspension, and ban require explicit moderator scope, audit receipt, retention policy, and appeal/reversal handling before durable enforcement launches.
  • Moderator-to-user messages may appear inside chat previews, but provider sends, push notifications, durable bans, durable suspensions, and cross-device enforcement must remain disabled until authenticated role/scope checks and launch evidence pass.

Documentation requirements​

  • Every meaningful screen, action, message, API-adjacent moment, and workflow state must expose an information link.
  • Technical viewers may receive API, schema, workflow, audit, and implementation links.
  • Non-technical viewers must receive public-safe how-to or user-guide links.
  • Public user documentation must reference only approved public documentation and support links.
  • Public docs and API docs must be updated when a release changes user instructions, connector behavior, moderation behavior, notification copy, or API contracts.
  • Public-facing Flow Studio scenarios must not include real phone numbers, private customer messages, production IDs, credentials, confidential partner details, or non-public source URLs.
  • Release history must record major iterations only. Do not create a release-history entry for routine copy or style changes.
  • The release smoke checklist must be followed before a major public publish.

Private contact and CRM requirements​

  • Real email, phone, WhatsApp, social DM, and personal contact values must never appear in public demos, public docs, public projections, SEO content, sitemaps, public JSON, public build artifacts, or public Flow Studio scenario data.
  • Public-safe congress/contact research output may show availability flags and evidence URLs, such as has_public_email_on_page, public_email_page_urls, and has_contact_form; actual contact values must be stored only in private/internal evidence or private_contact tables.
  • Demo, sample, public Flow Studio, and sales data must use fake contact values only.
  • Admin CRM screens for congress/event contacts must require authenticated admin access and must not be available to public, submitter, moderator-only, or non-technical viewer profiles unless a later authenticated access model explicitly grants that role.
  • Every access to a private contact value must be auditable, including actor, role/scope, purpose, subject/contact record, timestamp, and read/export/send action.
  • Suppression, opt-out, block, abuse, or do-not-contact state must block future outreach before provider send actions are evaluated.
  • Email, SMS, WhatsApp, and social DM sends require consent/compliance gates, contact-point verification, provider configuration, template/sender readiness where applicable, suppression checks, audit logging, and launch evidence.
  • Live outreach actions in CRM/admin scenarios must remain visibly disabled until the compliance gates are complete.
  • Public Mi Gente pages may show only approved contact availability or brokered-contact eligibility, never raw contact values, private notes, private evidence, moderation notes, or unapproved claim state.
  • Compliance reference links must be maintained for implementation planning: FTC CAN-SPAM guide, Twilio Messaging Policy, European Commission GDPR overview, California CCPA overview, Supabase secure data docs, and TikTok Login Kit.

Testing requirements​

Run these checks before merging Flow Studio changes that affect behavior, role access, documentation links, public safety, or release behavior:

cd docs-portal
npm run test:flow-studio
npm run test:flow-studio-access
npm run test:experience-system
npm run test:experience-system-browser
npm run test:tenant-emulators
npm run test:third-party-services
npm run build
npm run build:astro
npm run stage:astro-deploy
npm run test:experience-system-deploy-artifact
npm run test:flow-studio-browser

For public Cloudflare release builds, also run:

cd docs-portal
DEPLOY_TARGET=cloudflare-pages npm run build
npm run test:third-party-services-public-build

Set the selected public Flow Studio URL through the repository release-build configuration rather than hardcoding it in public docs.

Browser smoke must cover WhatsApp Submission, GLD Event Submission desktop chat/admin editor, GLD Ingest desktop operator, GLD mobile moderator/non-technical admin, lower-permission deep-link downgrade behavior, sticky controls, and viewer-menu behavior.

Deployment requirements​

  • Normal main pushes must build and test the docs portal but must not publish to Cloudflare Pages.
  • Public Cloudflare Pages publishing must be release-gated through a flow-studio-v* tag or manual docs-portal workflow dispatch with publish_cloudflare=true and a major iteration name.
  • Public release builds must run the public privacy guard before deploy.
  • Private dashboard browser smoke must not run against public Flow Studio release builds.
  • The public production URL and preview URL must return HTTP 200 after deployment.
  • A hydrated browser check must confirm the updated Flow Studio content is visible on the public site before declaring a public release complete.

Future requirements​

  • Add authenticated viewing for admin and moderator flows before treating public viewer gates as real access control.
  • Add training modes for submitters, moderators, admins, and developers.
  • Add sales and partner demo modes with sanitized data.
  • Add contextual feedback and comment collection for future product improvement.
  • Add custom-domain publishing when the selected Flow Studio domain is ready.