B2BEA.org V1 Survey System Spec

Source of record: RedKey Supabase Studio artifact.

• Project: B2BEA.org Rebuild
• Project ID: a820dd0c-6cef-4133-bfbd-d802fd806e44
• Artifact: survey-system-spec
• Artifact ID: 823d14d7-5992-42f3-a2f4-f4738a045f7c
• Version: 1
• Status: draft
• Updated: 2026-05-07T15:32:18.423567+00:00

Define the standard reusable survey/form capability separately from the maturity-assessment special flow, so B2BEA can run structured surveys without forcing all assessments into one generic model.

``json { "included": [ "Admin-created standard surveys and forms", "Question definitions and ordering", "Audience assignment rules", "Public/member/vendor/company respondent flows where authorized", "Response capture and partial/progress state where needed", "Review, export, reporting, and display permissions", "Email-first notification events for invitations/reminders/results where approved", "Audit trail for publish/archive/export and permission-sensitive operations" ], "excluded_or_separate": [ "Current maturity assessment special flow; it remains V1 but uses its own maturity-assessment pattern", "Complex in-app notification center beyond email-first event log", "Unbounded custom quiz/certification grading; academy certification has its own spec", "Anonymous collection of sensitive data without explicit consent/policy", "Raw platform-wide exports for vendors or companies" ] } ``

draft

| id | role | | --- | --- | | b2bea_admin | Creates, publishes, assigns, reviews, exports, and archives surveys/forms. | | anonymous_respondent | Can submit public surveys/forms only when explicitly published for anonymous access. | | member | Can respond to member-assigned or public surveys and view own submitted responses/results where allowed. | | vendor_admin | Can respond to vendor-assigned surveys and view own vendor aggregate/report outputs where allowed. | | company_admin | Can assign company-eligible surveys to employees and view own-company aggregate/report outputs where allowed. | | company_employee | Can respond to company-assigned surveys when invited/entitled. |

| id | actor | surface | acceptance | description | | --- | --- | --- | --- | --- | | SurveyCreateDefinition | b2bea_admin | /admin | Definition validates before publish., Question ids are stable., Owner and intended audience are required. | Create a reusable survey/form definition with title, description, purpose, owner, question set, audience, lifecycle, consent copy, and reporting policy. | | SurveyPublishArchive | b2bea_admin | /admin | Draft/preview is not public., Archived surveys stop accepting new responses., Lifecycle changes create audit events. | Move survey/form through draft, preview, published, paused, archived lifecycle. | | SurveyAssignAudience | b2bea_admin/company_admin | /admin or /company | Audience membership is server-side evaluated., Assignment has opens_at/closes_at where relevant., Company admins can only assign surveys allowed by company entitlement/policy. | Assign a published survey/form to an audience: public link, members, vendors, companies, company employees, event attendees, or a curated list. | | SurveyTake | respondent | public/member/vendor/company as authorized | Required questions are enforced., Respondent access is checked server-side., Submis

```json { "tables_or_entities": [ { "name": "survey_definitions", "purpose": "Canonical survey/form definition and lifecycle metadata.", "key_fields": [ "id", "slug", "title", "description", "owner_role", "status", "audience_policy", "consent_text", "reporting_policy", "created_by", "created_at", "updated_at", "published_at", "archived_at" ] }, { "name": "survey_questions", "purpose": "Ordered question definitions linked to survey_definitions.", "key_fields": [ "id", "survey_id", "stable_key", "question_type", "label", "help_text", "required", "order_index", "options_json", "validation_json", "show_if_json", "sensitive_flag" ] }, { "name": "survey_assignments", "purpose": "Audience assignment and availability window for a survey.", "key_fields": [ "id", "survey_id", "audience_type", "audience_ref", "opens_at", "closes_at", "status",

``json { "v1_rules": [ "Every question has a stable key, label, optional help text, required flag, order, and answer validation.", "Choice questions store stable option keys, not only display labels.", "Conditional branching is limited in V1: show_if based on prior single_choice/boolean answers only, unless separately approved.", "Free-text responses can be marked sensitive and excluded from non-admin exports by default." ], "v1_question_types": [ "short_text", "long_text", "single_choice", "multi_choice", "rating_scale", "boolean", "email", "url", "number", "date" ], "deferred_question_types": [ "file_upload", "matrix_grid", "rank_order", "payment", "signature", "complex calculated score blocks" ] } ``

``json { "export": [ "requested", "authorized", "generated", "downloaded", "expired", "denied", "failed" ], "response": [ "not_started", "in_progress", "submitted", "voided", "deleted_or_redacted" ], "assignment": [ "draft", "scheduled", "open", "closed", "archived" ], "survey_definition": [ "draft", "preview", "published", "paused", "archived" ] } ``

``json { "entitlement_keys": [ "survey.respond.public", "survey.respond.member", "survey.respond.vendor", "survey.respond.company", "survey.report.admin", "survey.report.own_account", "survey.export.admin", "survey.export.own_account" ], "server_side_rules": [ "Survey definition writes require b2bea_admin/core admin permission.", "Public surveys require status=published and anonymous_allowed=true or public assignment.", "Member/vendor/company surveys require active user plus matching assignment/entitlement.", "Vendor and company report/export reads are scoped to own vendor/company only.", "Sensitive free-text/person-level exports require explicit admin permission and consent/policy basis.", "All publish/archive/export/assignment changes create audit events." ] } ``

• Spec clearly separates standard surveys/forms from maturity assessments.
• A developer can design survey tables, guards, and UI modules from the contracts without guessing source of truth.
• Permission/export boundaries are explicit for public, member, vendor, company, and admin actors.
• No implementation/build is authorized by this artifact alone; PLAN/EXEC_PLAN_REVIEW and Justin build approval remain required.

• qa-release-readiness-spec
• plan