survey-system-spec · supabase_json
B2BEA.org V1 Survey System Spec
survey-system-spec artifact · for B2BEA.org Rebuild · status approved
open questions
| id | blocks | question |
|---|---|---|
| SURV-OQ-001 | Exact first implementation module, not this spec. | Which existing V1 forms should migrate into survey/form system versus remain bespoke contact/application flows? |
| SURV-OQ-002 | Content editing workflow details. | Should survey definitions live only in B2BEA Supabase, or should Sanity own public explanatory copy for standard public surveys? |
| SURV-OQ-003 | Export/report policy. | What respondent-level data is allowed in vendor/company reporting, if any? |
Agent Handoff
Start Here
survey-system-spec artifact · for B2BEA.org Rebuild · status approved
Completion Evidence
- 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.
Open Questions
- SURV-OQ-001: id: string, blocks: string, question: string
- SURV-OQ-002: id: string, blocks: string, question: string
- SURV-OQ-003: id: string, blocks: string, question: string
Structured Payload
Machine-readable source fields
scope
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
title
B2BEA.org V1 Survey System Spec
actors
| 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. |
status
draft
purpose
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.
version
1
project id
a820dd0c-6cef-4133-bfbd-d802fd806e44
updated at
2026-05-07T15:32:18.075Z
artifact type
survey-system-spec
next artifacts
- qa-release-readiness-spec
- plan
open questions
| id | blocks | question |
|---|---|---|
| SURV-OQ-001 | Exact first implementation module, not this spec. | Which existing V1 forms should migrate into survey/form system versus remain bespoke contact/application flows? |
| SURV-OQ-002 | Content editing workflow details. | Should survey definitions live only in B2BEA Supabase, or should Sanity own public explanatory copy for standard public surveys? |
| SURV-OQ-003 | Export/report policy. | What respondent-level data is allowed in vendor/company reporting, if any? |
question model
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
- url
- number
- date
deferred question types
- file_upload
- matrix_grid
- rank_order
- payment
- signature
- complex calculated score blocks
lifecycle models
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
permission model
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.
source artifacts
| status | version | artifact id | artifact type |
|---|---|---|---|
| draft | 1 | 05e0ed7c-416a-4d8f-853a-bc3dfa3d64f6 | company-workspace-data-spec |
| draft | 1 | 2f473004-9063-4fe9-8290-5cbd1b19dfb4 | data-model-spec |
| draft | 1 | 355b3249-3af9-45a4-9c45-67777bd2d72d | entitlement-model-spec |
| draft | 1 | 427c04a9-40b7-4e55-a642-65b2aee20b2b | page-template-spec |
| draft | 3 | 80328220-3deb-4cf9-a68f-d440b41a38da | production-readiness-gap-register |
| draft | 3 | 2cec821e-07ba-4aca-81fb-078f163adf44 | route-family-inventory |
| draft | 9 | 77853042-e7a4-48bd-91a4-6e48d0484b1b | surface-specs |
target data model
tables or entities
| name | purpose | key fields |
|---|---|---|
| survey_definitions | Canonical survey/form definition and lifecycle metadata. | - id - slug - title - description - owner_role - status - audience_policy - consent_text - reporting_policy - created_by - created_at - updated_at - published_at - archived_at |
| survey_questions | Ordered question definitions linked to survey_definitions. | - id - survey_id - stable_key - question_type - label - help_text - required - order_index - options_json - validation_json - show_if_json - sensitive_flag |
| survey_assignments | Audience assignment and availability window for a survey. | - id - survey_id - audience_type - audience_ref - opens_at - closes_at - status - created_by |
| survey_responses | One respondent response session/submission. | - id - survey_id - assignment_id - respondent_person_id - anonymous_token_hash - subject_type - subject_ref - status - started_at - submitted_at - consent_at - ip_hash - user_agent_hash |
| survey_answers | Question-level answer storage with typed values. | - id - response_id - question_id - answer_json - answered_at |
| survey_report_views | Optional materialized/read-model reporting layer for aggregate dashboards. | - survey_id - scope_type - scope_ref - question_key - aggregate_json - updated_at |
| survey_export_events | Audited export requests/generation/downloads. | - id - survey_id - requested_by - scope_type - scope_ref - status - file_ref - created_at - expires_at |
implementation note
Exact SQL/migration belongs in PLAN/build phase. This spec defines target contracts, not implementation approval.
acceptance criteria
- 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.
capability contracts
| 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. - Submission confirmation is clear. - Duplicate/retry behavior is defined. | Respondent completes questions with progress, validation, save/submit, consent, and confirmation states. |
| SurveyReport | b2bea_admin/vendor_admin/company_admin/member | /admin, /vendor, /company, member dashboard | - Admins can see full permitted results. - Vendors/companies see only own-account scoped results. - Sensitive respondent-level data is hidden unless explicitly permitted and consented. | View permitted results and reporting by audience, survey, question, or own-account aggregation. |
| SurveyExport | b2bea_admin/vendor_admin/company_admin | /admin, /vendor, /company | - Exports are audited. - Vendor/company exports are own-account only. - No raw platform-wide or sensitive user-level export without explicit policy/consent. | Export response/report data within policy boundaries. |
qa and release checks
- Anonymous/public survey cannot submit when survey is draft, paused, archived, or closed.
- Unauthorized user cannot access private assignment by URL.
- Required validation works on desktop/mobile and with keyboard input.
- Submitted response persists and cannot be double-submitted unless policy allows updates.
- Own-account vendor/company reports exclude other account data.
- Exports create audit events and expire.
- Sensitive fields are excluded from non-admin exports by default.
page template implications
| implication | page family |
|---|---|
| Needs survey definition list, editor, assignment, report, and export admin modules. | admin_module |
| Can share question controls and validation primitives, but retains maturity-specific scoring/result narrative. | maturity_assessment_special_flow |
| May need vendor-scoped survey response/report widgets for assigned vendor surveys. | vendor_dashboard |
| Future /company templates need employee assignment and own-company aggregate survey reporting. | company_workspace |
relationship to maturity assessments
decision
Maturity assessments are a reusable special assessment pattern, not just generic surveys. The standard survey system may share question/answer primitives, consent, response storage, and reporting components, but maturity assessments retain domain-specific scoring, result narrative, and recommendations.
future alignment
- Use compatible question and response primitives where practical.
- Keep maturity scoring/result models separate from simple survey reports.
- Allow future domain maturity assessments to reuse the maturity_assessment_special_flow page family.
current v1 maturity routes
- /assessments
- /assessments/maturity
- /assessments/maturity/take
- /assessments/maturity/results