Files

bert.hausmans 032ad9d953 docs(architecture): upgrade form builder architecture to v1.2

2026-04-17 10:39:36 +02:00

111 KiB

Raw Blame History

ARCH — Universal Form Builder (v1.2)

Source of truth for Crewli's universal Form Builder architecture. Any discrepancy with SCHEMA.md is resolved in favour of this document during the refactor. SCHEMA.md is updated at the end of the refactor.

Status: Approved — about to enter S1 implementation Version: 1.2 (expanded with per-purpose lifecycles, integration contracts, user guidance principles, documentation coverage requirements, in-app copy catalogue, and concrete gap fills from v1.1 review) Previous version: 1.1 committed April 2026 Created: April 2026 Owner: Architecture doc; every session reads this before starting

Breaking change acceptance: Crewli currently runs only as a development environment. Full refactor with breaking changes is acceptable and preferred over incremental non-breaking changes that would leave architectural debt.

0. TL;DR — What every session must know

Ten bullets every Claude Code session reads before starting:

Goal: replace the event-scoped registration_form_fields with a polymorphic, universal form builder serving 22 distinct purposes from event registration to incident reports to contract signatures.
Four patterns: entity-bound, submission-bound, event-registration, public. Every schema matches one.
Three tables are core: form_schemas (definitions), form_fields (within schemas), form_submissions + form_values (results). Auxiliary: form_value_options, form_templates, form_field_library, form_schema_webhooks, form_webhook_deliveries, form_schema_sections, form_submission_section_statuses, form_submission_delegations, user_profiles (renamed, slimmed).
Three binding patterns per field: entity-owned (A), form-owned (B), mirrored (C). Controlled via form_fields.binding JSON against a server-side entity column registry.
System-internal lookups bypass the form layer. Reading user_profiles.bio from a service happens directly on the table, never through form_fields. Form layer is for UI rendering and editing only.
Filtering is first-class. form_fields.is_filterable + indexed storage (value_indexed, form_value_options pivot) + filter-registry endpoint. Tag-based filters stay on existing user_organisation_tags.
Governance is built-in. Retention policies, PII-flagging, consent versioning, right-to-be-forgotten workflow with anonymisation.
Schema lifecycle has three mechanisms: schema_version (always tracks edits), schema_snapshot per submission (for audit trails), freeze_on_submit (prevents edits after first submission). See §18 for interaction rules.
Events are the backbone. Every submission state change fires a Laravel event. Webhooks, activity log, analytics, and integrations are all listeners on these events — never ad-hoc in services.
Pre-flight audit is mandatory. Every session starts with the audit block (§21) that verifies no accidental user_profile / volunteer_profile changes slipped into the codebase before work begins.

[v1.2 addition] Three more principles:

User guidance is a first-class concern. Every decision-impacting UI control has contextual help (§28). Every destructive action has a preview. No feature ships without in-app guidance + VitePress docs.
Integration contracts are explicit. The form builder's interaction with identity matching, crowd lists, shifts, and email notifications is contract-defined (§31). No ad-hoc cross-module coupling.
Per-purpose lifecycles are documented. Each of the 22 FormPurpose values has a concrete lifecycle paragraph (§3.2) covering subject handling, submission flow, integrations, and sample fields.

Rationale
Four form patterns
FormPurpose catalogue
- 3.1 Enum values summary
- 3.2 [v1.2] Per-purpose lifecycles
Core tables
FormFieldType catalogue
Field binding
Filter architecture
Conditional logic
Signature field details
Public token flow
Migration plan
Seeding strategy
Governance & compliance
Schema lifecycle & versioning
Workflows & submission reviews
Internationalisation
Extensibility & integrations (webhooks, custom field types, custom purposes)
Consistency & interaction rules
Self-hosting principle ("eat your own dog food")
Trade-offs & cost awareness
Pre-flight audit gate
Failure-mode resilience
Observability & analytics hooks
Access control per field
Self-hosting reservations (FormPurpose slots)
Open questions / deferred decisions
Out of scope
[v1.2] User guidance principles
[v1.2] Documentation coverage requirements per session
[v1.2] In-app copy catalogue (living seed)
[v1.2] Integration contracts

1. Rationale

Crewli has a proven registration form builder with EAV storage, 11 system-seeded templates, and strong adoption. It handles event registration well but is hard-coded to event_id. The same mechanism is desired for:

Artist advancing intake (rider, contacts, production)
Supplier intake (materials, power, transport)
Persistent user/artist/company profile fields
Post-event volunteer evaluations
Signatures for contracts, code-of-conduct, accreditation receipt
Incident reports during events
Absence reports, check-out inventory
Public complaints, press access requests, VIP RSVPs
Onboarding and setup wizards
Custom organisation-specific forms

The legacy volunteer_profiles table (documented in SCHEMA v1.3 but never implemented) mixed truly user-universal data (bio, photo) with event-variable data (tshirt_size, allergies) and skill-like claims (first_aid, driving_licence). Those are redistributed:

tshirt_size, allergies, access_requirements → form_fields per event
first_aid, driving_licence → person_tags (system-seeded)
bio, photo_url, emergency_contact_*, reliability_score, is_ambassador → stay on a renamed, slimmed user_profiles table

The result: user_profiles becomes genuinely user-universal, the form builder handles entity-specific and event-specific variation, and the tag system handles skills and certificates.

2. Four form patterns

Every form in Crewli fits one of four patterns:

Pattern	Description	Subject	Examples
Entity-bound	Values persist on the subject. One submission per subject; updates overwrite.	user, artist, company, organisation	user_profile, artist_profile, company_profile
Submission-bound	Each submission is a standalone document with its own lifecycle. Multiple allowed per subject.	any, incl. null	incident_report, feedback, post_event_evaluation
Event-registration	Hybrid: one submission per person per event. Treated as entity-bound within the event's person context.	person	event_registration
Public	No authenticated subject. Accessed via public token.	null	public_complaint, public_rsvp

3. FormPurpose catalogue

3.1 Enum values summary

Every form_schemas.purpose is one of these values. Purpose determines allowed subject_type, default submission_mode, and whether public access is allowed.

Purpose	Subject type	Mode	Public?	Pattern
`event_registration`	person	draft_single	No	Event-registration
`user_profile`	user	single	No	Entity-bound
`artist_profile`	artist	single	No	Entity-bound
`company_profile`	company	single	No	Entity-bound
`artist_advance`	artist	draft_single	Via artist.portal_token	Entity-bound + sections
`supplier_intake`	company	draft_single	Via production_request.token	Entity-bound + sections
`incident_report`	user / null	multiple	No	Submission-bound
`feedback`	user / null	multiple	No	Submission-bound
`post_event_evaluation`	person	single	No	Submission-bound
`signature_contract`	user / artist	single	No	Submission-bound (frozen)
`signature_code_of_conduct`	user	single	No	Submission-bound (frozen)
`signature_receipt`	person	multiple	No	Submission-bound (frozen)
`absence_report`	person	multiple	No	Submission-bound
`check_out_inventory`	person	multiple	No	Submission-bound
`public_complaint`	null	multiple	Yes + captcha	Public
`public_press_request`	null	multiple	Yes + captcha	Public
`public_rsvp`	person / null	single	Yes via token	Public
`onboarding_wizard`	organisation	single	No	Entity-bound + sections
`event_setup_wizard`	event	single	No	Entity-bound + sections
`company_custom`	company	single	No	Entity-bound
`artist_custom`	artist	single	No	Entity-bound
`custom`	organisation-defined	organisation-defined	organisation-defined	Per §17.3

3.2 [v1.2] Per-purpose lifecycles

This section defines the concrete lifecycle of each FormPurpose: who creates the schema, who submits, what integrations fire, and what the canonical system-seeded template contains. Intended as binding spec for S3 (seeding) and S5 (frontend rendering).

3.2.1 `event_registration`

Who creates the schema: organiser (org_admin or event_manager) per event, via form-builder UI. Seeded from EventRegistrationDefault template on first event_registration form opened.

Who submits: person (via portal, either as authenticated user or as external person during public registration).

Submission flow:

Person opens the registration form (authenticated or via public URL)
FormSubmission.opened_at = now; status = draft
Fields rendered per conditional_logic + role_restrictions
On submit: FormSubmissionSubmitted event fires
Integration: PersonIdentityService invoked (see §31.1) to detect match
Integration: if form contains AVAILABILITY_PICKER values, shift_assignments are provisionally created at status=claim_pending (see §31.3)
Integration: if form contains SECTION_PRIORITY values, preferences are stored in person_section_preferences (existing table)
Integration: confirmation email sent via CrewliMailable (see §31.4)

Canonical system template fields:

Naam (Pattern C → persons.first_name + last_name)
E-mail (Pattern C → persons.email), required
Telefoon (Pattern C → persons.phone)
Geboortedatum (Pattern C → persons.date_of_birth), PII=true
Shirtmaat (SELECT XS/S/M/L/XL/XXL, filterable=true)
Dieetwensen (CHECKBOX_LIST, filterable=true)
Allergieën (TEXTAREA, PII=true)
Toegangsbehoeften (TEXTAREA, PII=true)
Noodcontact naam (Pattern C → user_profiles.emergency_contact_name), PII=true
Noodcontact telefoon (Pattern C → user_profiles.emergency_contact_phone), PII=true
Certificaten & vaardigheden (TAG_PICKER)
Motivatie (TEXTAREA, optional)
Sectie-voorkeuren (SECTION_PRIORITY)
Beschikbaarheid (AVAILABILITY_PICKER)
Toestemming gegevensverwerking (BOOLEAN, required, consent-tracked)

Mode rationale: draft_single — persons may fill across multiple sessions, but only one registration per person per event is meaningful.

freeze_on_submit: false. Organiser may want to add fields mid-campaign.

retention_days default: 1095 (3 years, matches typical volunteer data retention).

3.2.2 `user_profile`

Who creates: organiser per organisation (exactly one schema per organisation, seeded automatically via UserProfileDefault).

Who submits: authenticated user via portal (/profile page).

Submission flow:

User opens profile; submission created on-demand if not exists
All fields are Pattern A (entity-owned → user_profiles columns)
User edits; on save, updateOrCreate on user_profiles
FormSubmissionSubmitted fires on any update
No confirmation email (user-initiated, no notification needed)

Canonical fields:

Bio (Pattern A → user_profiles.bio)
Profielfoto (Pattern A → user_profiles.photo_url, IMAGE_UPLOAD)
Noodcontact naam (Pattern A)
Noodcontact telefoon (Pattern A)

Mode: single (exactly one submission per user, updates overwrite).

freeze_on_submit: false.

retention_days: null (never anonymised — user profile persists while account exists; deletion happens via user-delete flow, see §13.4).

3.2.3 `artist_profile`

Who creates: org-level, one schema per organisation.

Who submits: organiser on behalf of artist (via artist management UI), or artist themselves via artist portal token.

Submission flow:

Submission created when artist is created in system
Organisers fill/update artist profile fields
Public flow: artist clicks portal_token link, sees profile form
On save, entity updates (Pattern A for most fields)
FormSubmissionSubmitted fires

Canonical fields (initial set, extended when artist module lands):

Band/artist naam (Pattern A → artists.name)
Contact naam (Pattern A → artists.contact_name)
Contact e-mail (Pattern A → artists.contact_email)
Genre (SELECT, filterable=true)
Rider-notities (TEXTAREA)
Technische rider (FILE_UPLOAD, PDF)

Mode: single.

freeze_on_submit: false.

retention_days: null (artist relationships persist across events).

3.2.4 `company_profile`

Mirror of artist_profile but for company entities. One schema per org, companies get a row on creation. Pattern A/C mix for contact fields.

Canonical fields: contact_name, contact_email, contact_phone, website, company-type (supplier/partner/etc.), KvK-nummer, BTW-nummer.

3.2.5 `artist_advance`

Who creates: org-level schema (one per org), seeded from ArtistAdvanceDefault. Schema has section_level_submit=true.

Who submits: artist via portal_token (no authentication required).

Submission flow:

Artist receives email with portal link (triggered by organiser)
Opens link → token resolved, submission fetched or created
Form shown with sections: General Info, Contacts, Production (power, catering, transport), Technical Rider, Hospitality
Artist fills sections independently; each section submit separately
On section submit: FormSubmissionSectionSubmitted event fires
Organiser reviews per section → section status approved/rejected/ changes_requested
When all sections approved: FormSubmissionSubmitted fires at submission level
Integration: triggers accreditation generation per ARCH-07 (future)

Mode: draft_single.

freeze_on_submit: false during draft; true after all sections approved.

retention_days: 2555 (7 years, contractual retention).

3.2.6 `supplier_intake`

Who creates: org-level schema seeded from SupplierIntakeDefault. Uses section_level_submit=true.

Who submits: supplier via production_request.token.

Submission flow: analogous to artist_advance. Sections: Company info, Personnel list (TABLE_ROWS), Materials (TABLE_ROWS), Power requirements, Transport + logistics, Accreditation requests.

Integration with existing production_requests infrastructure (see §31.6).

3.2.7 `incident_report`

Who creates: org-level schema from IncidentReportDefault.

Who submits: any authenticated user (volunteer, crew, organiser) during an event. Also available via public form if organiser enables public token (rare — typically internal only).

Submission flow:

User accesses via "Rapporteer incident" link in portal (event-scoped)
Submission has subject_type=user (submitter), event context in metadata
freeze_on_submit=true — once submitted, cannot be edited (integrity)
Organiser reviews via incident dashboard; review_status workflow applies
Integration: critical incidents notify org_admins via CrewliMailable
schema_snapshot stored for legal retention

Canonical fields:

Tijdstip incident (DATETIME, required, defaults to now)
Locatie (TEXT, required)
Type incident (SELECT: medisch/veiligheid/schade/conflict/anders, filterable)
Ernst (SELECT: laag/middel/hoog/kritiek, filterable)
Betrokkenen (TEXTAREA)
Beschrijving (TEXTAREA, required)
Ondernomen actie (TEXTAREA, required)
Foto's (IMAGE_UPLOAD, multiple, max 5)
Politie/ambulance gebeld? (BOOLEAN)

Mode: multiple (same user can report multiple incidents).

freeze_on_submit: true.

retention_days: 3650 (10 years, legal minimum).

snapshot_mode: on_submit.

3.2.8 `feedback`

Who creates: per-event or per-org schema.

Who submits: volunteer / crew / public visitor (public optional).

Submission flow: simple form-submit, fires FormSubmissionSubmitted, organiser can browse responses.

Canonical fields: waardering (NUMBER 1-5), wat ging goed (TEXTAREA), wat kan beter (TEXTAREA), zou je terugkomen (BOOLEAN).

Mode: multiple.

retention_days: 365.

3.2.9 `post_event_evaluation`

Who creates: per-event schema, triggered by organiser after event closes.

Who submits: person who participated (subject = person).

Submission flow:

Organiser clicks "Verstuur evaluatie" in event dashboard
Emails sent to all approved persons (see §31.4)
Person clicks link, fills form
On submit: FormSubmissionSubmitted fires
Aggregation dashboard populates from submissions

Canonical fields:

Algemene waardering (NUMBER 1-5)
Shift-waardering (NUMBER 1-5)
Was de briefing duidelijk? (NUMBER 1-5)
Wil je terugkomen? (BOOLEAN)
Opmerkingen (TEXTAREA)
Verbeterpunten (TEXTAREA)
Anoniem? (BOOLEAN) — if true, submitted_by_user_id cleared on submit

Mode: single (one evaluation per person per event).

snapshot_mode: on_submit (responses frozen post-event).

retention_days: 365.

3.2.10 `signature_contract`

Who creates: per-org, optionally per artist/event.

Who submits: user or artist via authenticated / token flow.

Submission flow:

Schema contains PARAGRAPH with contract text + SIGNATURE field
On submit: signature hashed (§9), stored
submission locked (freeze_on_submit=true enforced)
PDF can be generated later (out of scope for v1)

Mode: single.

retention_days: 2555 (7 years fiscal).

snapshot_mode: on_submit.

3.2.11 `signature_code_of_conduct`

Per-event schema. User must sign code-of-conduct before participating. Linked from portal "Gedragscode tekenen" action. Integration: person cannot claim shifts until code-of-conduct submission exists with status=submitted (see §31.5).

Fields: PARAGRAPH (code text from org config) + BOOLEAN (Ik ga akkoord)

SIGNATURE.

Mode: single per person per event.

3.2.12 `signature_receipt`

Per-event, per-person-per-accreditation. Used at accreditation desk: volunteer signs for received wristband / t-shirt / meal vouchers.

Fields: TABLE_ROWS (items received with quantities) + SIGNATURE.

Mode: multiple (different receipts at different moments).

freeze_on_submit: true.

3.2.13 `absence_report`

Who creates: per-event optional schema. If not present, absence is logged via simple status change on shift_assignment.

Who submits: person via portal when they realise they can't show up.

Submission flow:

Person clicks "Ik kan toch niet komen" on shift detail
Form opens, subject = person
Fields: reason (SELECT), notes (TEXTAREA), affected_shifts (AVAILABILITY_PICKER showing their assigned shifts)
On submit: for each affected shift, ShiftAssignment.status → cancelled with cancellation_source="volunteer_absence"
FormSubmissionSubmitted fires; organiser notification sent

Mode: multiple.

Integration: see §31.3 (shifts) and §31.4 (email).

3.2.14 `check_out_inventory`

Accreditation-desk form used at end of event when volunteer returns gear.

Fields: TABLE_ROWS (items returned, condition per item), SIGNATURE of accreditation officer + volunteer.

Integration: links to accreditation module (ARCH-07, future) — at that point the pre-checkin items list is auto-populated.

3.2.15 `public_complaint`

Public form accessible via crewli.app/f/{token}. Captcha required.

Fields: name (optional), email (required), subject (TEXT), message (TEXTAREA), event (SELECT from org's public events).

Rate limit: 3 per IP per hour.

Integration: triggers email to configured complaints-mailbox (org-level config).

3.2.16 `public_press_request`

Similar to public_complaint but for press accreditation requests. Fields: outlet name, contact details, press card upload, event(s) requested. Captcha required.

3.2.17 `public_rsvp`

VIP RSVP form. Public URL with token. subject_type may be null (truly public) or person (specific VIP invited). Fields: name, email, attending (BOOLEAN), plus_ones (NUMBER), dietary_preference.

3.2.18 `onboarding_wizard`

Self-hosted meta-form. Used when a new organisation is created — the organisation-admin fills org details, brand, contact person, etc.

Uses: section_level_submit=true. Sections: Organisation basics, Brand & communication, Invite members, Create first event.

Pattern A for all fields — writes directly to organisations table (organisation is subject).

Once complete: schema is archived per organisation; never submitted again.

3.2.19 `event_setup_wizard`

Similar to onboarding_wizard but per-event. Sections: Basic details, Crowd types, Registration fields, Communication. Replaces the currently multi- page event setup with a guided form.

3.2.20 `company_custom`

Organisation-specific company fields. E.g., org tracks "preferred bank account" or "fire safety certified?" on companies. One schema per org, fields added by org_admin.

Pattern B for all custom fields (form-owned). Shows up in company detail as a tab.

3.2.21 `artist_custom`

Analogous to company_custom but for artists.

3.2.22 `custom`

See §17.3 — organisations define their own purposes via custom_purpose_slug. Subject type and mode must be explicitly set.

4. Core tables

4.1 `form_schemas`

Column	Type	Notes
`id`	ULID	PK
`organisation_id`	ULID FK	→ organisations
`owner_type`	string nullable	polymorph: `event` / `user_profile` / `artist` / `company` / null
`owner_id`	ULID nullable	polymorph target
`name`	string
`slug`	string	Canonical within org
`purpose`	enum	FormPurpose
`custom_purpose_slug`	string nullable	Required when purpose=custom (see §17.3)
`description`	text nullable
`is_published`	bool, default false
`submission_mode`	enum	FormSubmissionMode
`public_token`	ULID nullable, unique	For public schemas
`public_token_previous`	ULID nullable	For graceful rotation
`public_token_rotated_at`	datetime nullable
`submission_deadline`	datetime nullable
`locale`	string, default 'nl'	Primary locale; translations in form_fields.translations
`settings`	JSON nullable	Opaque UI config
`version`	int, default 1	Bumped on any schema-affecting edit
`snapshot_mode`	enum, default 'never'	never / on_submit / always — see §14
`freeze_on_submit`	bool, default false	After first submitted submission, no more edits
`retention_days`	int nullable	After submitted_at + retention_days: anonymise
`consent_version`	string nullable	e.g. "privacy-v2"
`section_level_submit`	bool, default false	Enables sections-with-own-submit
`auto_save_enabled`	bool, default false	Client does periodic silent saves
`max_submissions`	int nullable	Optional cap for public schemas
`created_by_user_id`	ULID FK nullable	Audit: who created this schema
`last_updated_by_user_id`	ULID FK nullable	Audit: who last edited
`edit_lock_user_id`	ULID FK nullable	Pessimistic lock holder for collaborative editing
`edit_lock_expires_at`	datetime nullable	Auto-release after this time
`created_at`, `updated_at`, `deleted_at`		Soft delete

Relations: hasMany form_fields, hasMany form_submissions, hasMany form_schema_webhooks, hasMany form_schema_sections, belongsTo organisation, morphsTo owner, belongsTo createdBy/lastUpdatedBy/editLockUser (User)

Indexes: (organisation_id, purpose), (owner_type, owner_id), (public_token) partial where not null, (public_token_previous) partial, (custom_purpose_slug) partial

Unique: (organisation_id, slug)

Activity log: yes — via spatie/laravel-activitylog on create/update/delete

4.2 `form_fields`

Column	Type	Notes
`id`	ULID	PK
`form_schema_id`	ULID FK	→ form_schemas, cascadeOnDelete
`form_schema_section_id`	ULID FK nullable	→ form_schema_sections (when section_level_submit)
`field_type`	string	One of FormFieldType or registered custom type (see §17.2)
`slug`	string	Unique within schema
`label`	string	Default-locale label
`help_text`	text nullable
`section`	string nullable	Section header name (visual grouping, different from section_level_submit)
`options`	JSON nullable	Choice options
`validation_rules`	JSON nullable	min/max/regex/allowed_mime_types/etc.
`is_required`	bool, default false
`is_filterable`	bool, default false	See §7
`is_portal_visible`	bool, default true
`is_admin_only`	bool, default false	Convenience for common role restriction
`is_unique`	bool, default false	Value must be unique across submissions (DB-enforced via partial index; see §4.2.1)
`is_pii`	bool, default false	Marks field as personal data (governance, §13)
`display_width`	enum: half/full
`binding`	JSON nullable	See §6
`conditional_logic`	JSON nullable	See §8
`role_restrictions`	JSON nullable	See §24
`translations`	JSON nullable	`{ "en": { "label": "...", "help_text": "...", "options": [...] } }`
`value_storage_hint`	enum, default 'json'	json / string / number / date / bool — enables typed columns in form_values
`review_required`	bool, default false	Individual fields needing review (§15)
`sort_order`	int
`library_field_id`	ULID FK nullable	→ form_field_library (linked reusable definition, §17.4)
`created_at`, `updated_at`, `deleted_at`		Soft delete preserves submission history

Relations: belongsTo form_schema, belongsTo form_schema_section (nullable), belongsTo libraryField (form_field_library), hasMany form_values

Indexes: (form_schema_id, sort_order), (form_schema_id, is_filterable), (library_field_id) partial

Unique: (form_schema_id, slug) on non-deleted

Activity log: yes — via spatie/laravel-activitylog

Soft delete: yes — deleting a field must not break historical submissions

4.2.1 [v1.2] `is_unique` enforcement

When is_unique=true, values for this field must be unique across all submissions of the same schema. Enforcement:

Application-level: FormValueService validates on write, rejects with 422 if duplicate exists among submitted submissions of the same schema
Database-level: partial UNIQUE index UNIQUE(form_field_id, value_indexed) WHERE form_field.is_unique = true AND form_submission.status = 'submitted' — This is implemented via a database-level trigger or application-enforced check because partial indexes with cross-table predicates are engine- specific. Preferred: application-enforced for portability, with a periodic integrity check job that flags violations for admin review.

4.3 `form_submissions`

Column	Type	Notes
`id`	ULID	PK
`form_schema_id`	ULID FK	→ form_schemas
`subject_type`	string nullable	polymorph
`subject_id`	ULID nullable	polymorph target
`submitted_by_user_id`	ULID FK nullable	Authenticated submitter
`public_submitter_name`	string nullable	Public submitters
`public_submitter_email`	string nullable	Public submitters
`public_submitter_ip`	string nullable	For audit/security
`public_submitter_ip_anonymised_at`	datetime nullable	[v1.2] Set when IP is anonymised (default 30 days post-submit unless investigation flag)
`status`	enum	FormSubmissionStatus: draft / submitted / archived
`review_status`	enum nullable	null / pending_review / approved / rejected / changes_requested
`reviewed_by_user_id`	ULID FK nullable
`reviewed_at`	datetime nullable
`review_notes`	text nullable
`submitted_at`	datetime nullable
`schema_version_at_submit`	int nullable	The schema.version at submit time
`schema_snapshot`	JSON nullable	Full snapshot when schema.snapshot_mode dictates (§14)
`is_test`	bool, default false	Test/preview submissions excluded from reporting
`submitted_in_locale`	string nullable	Locale submitter used while filling in
`opened_at`	datetime nullable	First time the form was rendered
`first_interacted_at`	datetime nullable	First field focus/input
`submission_duration_seconds`	int nullable	opened_at → submitted_at
`auto_save_count`	int, default 0	Debug/analytics counter
`idempotency_key`	ULID nullable	Client-provided key preventing duplicate submits
`anonymised_at`	datetime nullable	Set by anonymisation service (§13)
`search_index`	text nullable	Concatenated text values for full-text search (§23)
`created_at`, `updated_at`, `deleted_at`		Soft delete

Relations: belongsTo form_schema, hasMany form_values, hasMany form_submission_section_statuses, hasMany form_submission_delegations, belongsTo submittedBy / reviewedBy (User), morphsTo subject

Indexes: (form_schema_id, status), (subject_type, subject_id), (submitted_by_user_id), (form_schema_id, review_status) partial where not null, FULLTEXT(search_index) (MySQL)

Unique: (form_schema_id, idempotency_key) partial where not null

Soft delete: yes

Events fired: See §17.1 — FormSubmissionCreated, FormSubmissionDraftUpdated, FormSubmissionSubmitted, FormSubmissionReviewed, FormSubmissionAnonymised, FormSubmissionArchived, FormSubmissionDeleted

4.4 `form_values`

Column	Type	Notes
`id`	int AI	PK — integer for join performance
`form_submission_id`	ULID FK	→ form_submissions, cascadeOnDelete
`form_field_id`	ULID FK	→ form_fields
`value`	JSON	Universal storage; interpretation via field_type
`value_indexed`	string(255) nullable	For single-value filtering (§7)
`value_number`	decimal(15,4) nullable	Populated when value_storage_hint=number
`value_date`	date nullable	Populated when value_storage_hint=date
`value_bool`	bool nullable	Populated when value_storage_hint=bool
`value_anonymised`	bool, default false	Set by anonymisation

Indexes: (form_submission_id, form_field_id), (form_field_id, value_indexed) partial where value_indexed not null, (form_field_id, value_number) partial where value_number not null, (form_field_id, value_date) partial where value_date not null

Unique: (form_submission_id, form_field_id)

Observer: On upsert, populates value_indexed / value_number / value_date / value_bool / form_value_options based on field.value_storage_hint and field.is_filterable

4.5 `form_value_options` (filter pivot for multi-value fields)

Column	Type	Notes
`id`	int AI	PK
`form_value_id`	int FK	→ form_values, cascadeOnDelete
`form_field_id`	ULID FK	Denormalised for fast filtering
`form_submission_id`	ULID FK	Denormalised
`option_value`	string(255)	Single selected option

Indexes: (form_field_id, option_value), (form_submission_id), (form_value_id)

4.6 `form_templates`

Column	Type	Notes
`id`	ULID	PK
`organisation_id`	ULID FK	→ organisations
`name`	string
`slug`	string
`purpose`	enum	FormPurpose — constrains target schemas
`description`	text nullable
`schema_snapshot`	JSON	Full schema with fields, order, config
`is_system`	bool	true = shipped with Crewli
`is_active`	bool	Deactivate without deleting
`created_at`, `updated_at`

Indexes: (organisation_id, purpose, is_active)

Unique: (organisation_id, slug)

4.6.1 [v1.2] `schema_snapshot` JSON structure

The snapshot stored in form_templates.schema_snapshot AND in form_submissions.schema_snapshot follows this canonical shape:

{
  "schema_version": 3,
  "snapshot_created_at": "2026-04-17T14:00:00Z",
  "schema": {
    "name": "...",
    "slug": "...",
    "purpose": "event_registration",
    "description": "...",
    "locale": "nl",
    "freeze_on_submit": false,
    "section_level_submit": false,
    "consent_version": "privacy-v2",
    "settings": {}
  },
  "sections": [
    {
      "id": "01H...",
      "slug": "general",
      "name": "Algemeen",
      "sort_order": 1,
      "depends_on_section_slug": null,
      "required_for_schema_submit": true
    }
  ],
  "fields": [
    {
      "id": "01H...",
      "slug": "shirtmaat",
      "field_type": "SELECT",
      "label": "Shirtmaat",
      "help_text": null,
      "section_slug": null,
      "options": ["XS","S","M","L","XL","XXL"],
      "validation_rules": {"required": true},
      "is_required": true,
      "is_filterable": true,
      "is_pii": false,
      "binding": null,
      "conditional_logic": null,
      "translations": {},
      "value_storage_hint": "json",
      "sort_order": 5
    }
  ]
}

Rationale: using slugs (not IDs) in cross-references so snapshots are portable between orgs. library_field_id references are resolved to inline definitions at snapshot time (see §4.7).

4.7 `form_field_library` (cross-schema reusable definitions)

Column	Type	Notes
`id`	ULID	PK
`organisation_id`	ULID FK	→ organisations
`name`	string	"Shirtmaat (standaard)"
`slug`	string
`field_type`	string
`label`	string	Default label when library field is inserted
`help_text`	text nullable
`options`	JSON nullable
`validation_rules`	JSON nullable
`default_is_required`	bool, default false
`default_is_filterable`	bool, default false
`default_binding`	JSON nullable
`translations`	JSON nullable
`description`	text nullable	Admin-only description of intended use
`usage_count`	int, default 0	Cached count of form_fields.library_field_id = this.id
`is_system`	bool	true = shipped with Crewli
`is_active`	bool
`created_at`, `updated_at`

Relations: hasMany form_fields (via library_field_id)

Indexes: (organisation_id, field_type), (organisation_id, is_active)

Unique: (organisation_id, slug)

When an organiser inserts a library field into a schema, a new form_fields row is created with library_field_id = library.id and values copied from the library definition. The inserted field is independent thereafter — editing it does not affect the library, and vice versa. The library_field_id reference exists for analytics ("used 34 times") and for "update all copies" workflows later.

4.8 `form_schema_sections` (for section-level submit)

Only used when form_schemas.section_level_submit = true.

Column	Type	Notes
`id`	ULID	PK
`form_schema_id`	ULID FK	→ form_schemas, cascadeOnDelete
`slug`	string	[v1.2] Added for snapshot portability
`name`	string	"Technical Rider"
`description`	text nullable
`sort_order`	int
`submit_independent`	bool, default true	Whether this section can be submitted independently
`depends_on_section_id`	ULID FK nullable	→ self; section is locked until dependency is approved
`required_for_schema_submit`	bool, default true	If all required sections must be submitted+approved to consider schema submit complete

Indexes: (form_schema_id, sort_order)

Unique: (form_schema_id, slug)

4.8.1 [v1.2] Cycle detection

When saving a section with depends_on_section_id, FormSchemaService validates no cycle is created (depth-first traversal of depends_on_section_id chain). Rejected with 422 on cycle detection.

4.9 `form_submission_section_statuses`

Column	Type	Notes
`id`	ULID	PK
`form_submission_id`	ULID FK	→ form_submissions, cascadeOnDelete
`form_schema_section_id`	ULID FK	→ form_schema_sections
`status`	enum	draft / submitted / approved / rejected / changes_requested
`submitted_at`	datetime nullable
`reviewed_by_user_id`	ULID FK nullable
`reviewed_at`	datetime nullable
`review_notes`	text nullable

Unique: (form_submission_id, form_schema_section_id)

4.10 `form_submission_delegations`

For scenarios like "Nina fills in my advance on my behalf".

Column	Type	Notes
`id`	ULID	PK
`form_submission_id`	ULID FK	→ form_submissions, cascadeOnDelete
`delegated_to_user_id`	ULID FK	→ users
`delegated_by_user_id`	ULID FK	→ users (the subject who granted)
`granted_at`	datetime
`revoked_at`	datetime nullable
`message`	text nullable	Optional context from delegator to delegatee

Indexes: (delegated_to_user_id, revoked_at), (form_submission_id)

4.11 `form_schema_webhooks`

Column	Type	Notes
`id`	ULID	PK
`form_schema_id`	ULID FK	→ form_schemas, cascadeOnDelete
`name`	string	"Zapier — New registration"
`trigger_event`	enum	submission_created / submission_submitted / submission_reviewed / section_submitted / section_approved / section_rejected
`url`	string (encrypted)	Webhook endpoint; validated against allowlist/blocklist
`secret`	string (encrypted) nullable	HMAC secret for payload signing
`is_active`	bool, default true
`created_at`, `updated_at`

Indexes: (form_schema_id, is_active)

4.12 `form_webhook_deliveries`

Column	Type	Notes
`id`	ULID	PK
`form_schema_webhook_id`	ULID FK	→ form_schema_webhooks
`form_submission_id`	ULID FK	→ form_submissions
`trigger_event`	enum	Same as webhook's trigger_event
`status`	enum	pending / delivered / failed / dead_letter
`attempts`	int, default 0
`last_attempt_at`	datetime nullable
`response_status`	int nullable	HTTP status code
`response_body_excerpt`	text nullable	First 1000 chars of response
`next_retry_at`	datetime nullable
`delivered_at`	datetime nullable
`failed_permanently_at`	datetime nullable
`payload_snapshot`	JSON	What was sent (for replay/audit)

Indexes: (status, next_retry_at), (form_schema_webhook_id, status), (form_submission_id)

4.13 `user_profiles` (renamed from legacy volunteer_profiles, slimmed)

Column	Type	Notes
`id`	ULID	PK
`user_id`	ULID FK unique	→ users, cascadeOnDelete
`bio`	text nullable
`photo_url`	string nullable
`emergency_contact_name`	string nullable
`emergency_contact_phone`	string nullable
`reliability_score`	decimal(3,2), default 0.00	System-computed
`is_ambassador`	bool, default false	System-awarded
`settings`	JSON nullable	Strict: opaque UI/notification preferences only (see §4.13.1)
`created_at`, `updated_at`

Computed attributes (Laravel accessors):

last_submitted_at — max(form_submissions.submitted_at WHERE subject=this user AND status=submitted AND is_test=false)

Relations: belongsTo User

Indexes: (reliability_score)

Unique: (user_id)

No soft delete — tightly coupled to user; cascades on user delete

4.13.1 [v1.2] `settings` scope enforcement

user_profiles.settings is a strictly-scoped JSON column. Allowed top-level keys are defined in config/form_builder.php:

'user_profile_settings_whitelist' => [
    'ui.theme',
    'ui.sidebar_collapsed',
    'ui.time_format',
    'notifications.email_digest',
    'notifications.shift_reminders',
    'notifications.event_updates',
],

Forbidden: any queryable business attribute, org-specific preferences (those belong in organisation_user pivot), anything identity-related.

Enforcement: UserProfileSettingsValidator custom rule on the update-request. Rejects keys not in whitelist with 422.

Locale lives on users.locale (already exists). Not duplicated here.

5. FormFieldType catalogue

5.1 Built-in types

Type	Stored value	UI widget	Filterable?
`TEXT`	string	VTextField single-line	Yes
`TEXTAREA`	string	VTextarea	No
`EMAIL`	string	VTextField type=email	Yes
`PHONE`	string (E.164)	VTextField	Yes
`NUMBER`	number	VTextField type=number	Yes (via value_number)
`DATE`	ISO date	VDatePicker	Yes (via value_date)
`DATETIME`	ISO datetime	VDatePicker + time	Yes
`BOOLEAN`	bool	VSwitch	Yes (via value_bool)
`RADIO`	string (one option)	Radio group	Yes
`SELECT`	string	VSelect	Yes
`MULTISELECT`	string[]	VSelect multiple	Yes via form_value_options
`CHECKBOX_LIST`	string[]	Checkbox group	Yes via form_value_options
`FILE_UPLOAD`	string (path)	VFileInput	No
`IMAGE_UPLOAD`	string (path)	VFileInput images only	No
`SIGNATURE`	object (§9)	Signature pad	No
`TAG_PICKER`	string[] (tag IDs)	Tag autocomplete	Yes via user_organisation_tags
`HEADING`	no value	H3	n/a
`PARAGRAPH`	no value	Prose block	n/a
`URL`	string	VTextField URL	Yes
`SECTION_PRIORITY`	`{ section_id, priority }[]`	Drag-to-prioritise	No
`AVAILABILITY_PICKER`	ULID[] (time_slot IDs)	Checkbox per slot	No
`TABLE_ROWS`	`{ [col_slug]: value }[]`	Dynamic rows editor	No

Custom field types registered via CustomFieldTypeRegistry (§17.2) extend this list dynamically. The field_type column is stored as string, not DB enum, to allow this.

5.2 [v1.2] Mapping to value_storage_hint

Field type	Recommended value_storage_hint
TEXT, TEXTAREA, EMAIL, PHONE, URL	string
NUMBER	number
DATE, DATETIME	date
BOOLEAN	bool
RADIO, SELECT	string
Everything else	json (default)

The hint is suggestive, not enforced — organiser can override. Observer populates typed columns accordingly.

6. Field binding

6.1 The three patterns

Pattern A — Entity-owned (binding.mode = "entity_owned"): Value lives in an entity column. Form field is a rendering surface. No form_values row created. Reading: entity column. Writing: entity column.

Pattern B — Form-owned (default, binding = null): Value lives in form_values. No entity column involved. Pure dynamic EAV.

Pattern C — Mirrored (binding.mode = "mirrored"): Value written to entity column AND form_values. Entity is source of truth going forward; form_values is historical audit.

6.2 Entity column registry

Server-side config file config/form_binding.php:

return [
    'user_profile' => [
        'bio' => ['type' => 'text', 'label' => 'Bio', 'writable' => true],
        'photo_url' => ['type' => 'image', 'label' => 'Profielfoto', 'writable' => true],
        'emergency_contact_name' => ['type' => 'string', 'label' => 'Noodcontact naam', 'writable' => true],
        'emergency_contact_phone' => ['type' => 'string', 'label' => 'Noodcontact telefoon', 'writable' => true],
    ],
    'person' => [
        'first_name' => ['type' => 'string', 'label' => 'Voornaam', 'writable' => true],
        'last_name' => ['type' => 'string', 'label' => 'Achternaam', 'writable' => true],
        'email' => ['type' => 'string', 'label' => 'E-mail', 'writable' => true],
        'phone' => ['type' => 'string', 'label' => 'Telefoon', 'writable' => true],
        'date_of_birth' => ['type' => 'date', 'label' => 'Geboortedatum', 'writable' => true],
        'admin_notes' => ['type' => 'text', 'label' => 'Notities', 'writable' => true, 'admin_only' => true],
    ],
    'company' => [
        'contact_first_name' => ['type' => 'string', 'label' => 'Contact voornaam', 'writable' => true],
        'contact_last_name' => ['type' => 'string', 'label' => 'Contact achternaam', 'writable' => true],
        'contact_email' => ['type' => 'string', 'label' => 'Contact e-mail', 'writable' => true],
        'contact_phone' => ['type' => 'string', 'label' => 'Contact telefoon', 'writable' => true],
    ],
    'artist' => [
        // populated when artist module lands
    ],
    'organisation' => [
        'name' => ['type' => 'string', 'label' => 'Organisatienaam', 'writable' => true],
        'slug' => ['type' => 'string', 'label' => 'Slug', 'writable' => true],
        'contact_name' => ['type' => 'string', 'label' => 'Contactpersoon', 'writable' => true],
        'contact_email' => ['type' => 'string', 'label' => 'Contact-e-mail', 'writable' => true],
        'phone' => ['type' => 'string', 'label' => 'Telefoon', 'writable' => true],
        'website' => ['type' => 'string', 'label' => 'Website', 'writable' => true],
    ],
];

Only registered columns are valid binding targets. Form Request validates at save time.

6.3 Binding JSON specification

// Pattern B (default)
"binding": null

// Pattern A
"binding": {
  "mode": "entity_owned",
  "entity": "user_profile",
  "column": "bio"
}

// Pattern C
"binding": {
  "mode": "mirrored",
  "entity": "user_profile",
  "column": "emergency_contact_name",
  "sync_direction": "write_on_submit"
}

6.4 Read/write semantics per pattern

Operation	Pattern A	Pattern B	Pattern C
Initial render	Read entity column	Read form_value (null if new)	Read entity column
Save draft	Update entity	Upsert form_value	Update entity + upsert form_value
Final submit	Update entity	Upsert form_value	Update entity + upsert form_value
Historical view	Not possible — always current	Show stored form_value	Show stored form_value
form_values row?	No	Yes	Yes
Filter source	Entity column	form_values.value_indexed / value_number / etc.	Entity column (preferred)

6.5 Binding-change safety

Changing a field's binding is a DANGEROUS OPERATION. Rules:

If schema has zero submissions: free to change
If schema has submissions but all are drafts: allowed with warning
If schema has submitted submissions: REJECTED unless organiser provides explicit ?force_binding_change=true query param AND the change is logged with elevated audit level
Changing binding from B → A/C: orphans all historical form_values for that field (they remain in DB but no longer the source of truth). Documented in activity log.
Changing binding from A/C → B: entity columns retain their values; new submissions start storing in form_values again

Always logged via activity log with old/new binding for audit.

6.6 Cross-entity binding

Pattern C fields on event_registration schemas (subject = person) CAN bind to user_profile columns IF person.user_id is set. When user_id is null (external person), the mirror write is skipped gracefully and logged. form_values row is still written in both cases.

7. Filter architecture

A form_fields.is_filterable = true marks a field as queryable in list views.

7.1 Filter strategy per field type

Field type	Filter mechanism	Storage
TEXT, EMAIL, PHONE, URL	LIKE on value_indexed	form_values.value_indexed
NUMBER	Range on value_number	form_values.value_number
DATE, DATETIME	Range on value_date / value_indexed	form_values.value_date / value_indexed
BOOLEAN	Exact on value_bool	form_values.value_bool
RADIO, SELECT	Exact/IN on value_indexed	form_values.value_indexed
MULTISELECT, CHECKBOX_LIST	JOIN on form_value_options	form_value_options
TAG_PICKER	JOIN on user_organisation_tags	existing tag pivot
Pattern A/C entity-owned	WHERE on entity column	entity column
TEXTAREA, FILE_*, SIGNATURE, HEADING, PARAGRAPH, TABLE_ROWS, SECTION_PRIORITY, AVAILABILITY_PICKER	Not filterable	n/a — is_filterable forced to false

7.2 Observer mechanics

When a form_value is upserted for a field with is_filterable=true:

Single-value types: value_indexed = cast to string(255), truncated with warning log if longer
Number type: value_number = cast to decimal(15,4)
Date type: value_date = cast to date
Bool type: value_bool = cast to bool
Multi-value types: rebuild form_value_options (delete all, insert current)

When is_filterable=false: all indexed columns NULL, pivot rows removed.

When toggling is_filterable: queued job backfills (or clears) existing submissions. Job is observable (metric on queue depth).

7.3 Filter registry endpoint

Example: Personen-module

GET /api/v1/organisations/{org}/persons/filter-registry?event_id={ulid?}

Response:

{
  "data": [
    { "source": "entity_column", "key": "crowd_type_id", "label": "Crowd Type", "field_type": "SELECT", "options": [...] },
    { "source": "entity_column", "key": "status", "label": "Status", "field_type": "SELECT", "options": [...] },
    { "source": "tags", "key": "tags", "label": "Vaardigheden", "field_type": "TAG_PICKER", "options": [...] },
    {
      "source": "form_field",
      "key": "form_field:01HZ...",
      "form_field_id": "01HZ...",
      "schema_slug": "...",
      "label": "Shirtmaat",
      "field_type": "SELECT",
      "options": ["XS","S","M","L","XL","XXL"]
    }
  ]
}

Caching: response cached on (organisation_id, purpose, event_id?) with invalidation via form_schema/form_field activity log events.

7.4 [v1.2] Filter registry — entity column sources

The entity_column source in the filter registry is separate from the binding registry (§6.2). Filterable entity columns per context are defined in config/form_filter_registry.php:

return [
    'persons' => [
        'crowd_type_id' => ['label' => 'Crowd Type', 'field_type' => 'SELECT', 'options_source' => 'crowd_types'],
        'status' => ['label' => 'Status', 'field_type' => 'SELECT', 'options_enum' => PersonStatus::class],
        'is_blacklisted' => ['label' => 'Uitgesloten', 'field_type' => 'BOOLEAN'],
    ],
    'companies' => [...],
    'events' => [...],
];

Rationale: not every bindable column is filterable (admin_notes shouldn't be filtered), and not every filterable column is bindable (PersonStatus is enum-driven, not user-editable via form).

7.5 Applying filters in list endpoints

A generic FilterQueryBuilder service:

Takes URL params and the filter-registry definition
Joins the appropriate tables based on source
Applies WHERE/HAVING as appropriate
Respects role-based access (a filter on admin_only field is rejected for non-admin requester with 403)

7.6 Organiser UX

Form-builder UI shows "Gebruik als filter in overzichten" checkbox per field. Disabled with tooltip for non-filterable types. Hint on enabling: "Dit wordt extra geïndexeerd voor snelle filtering — alleen aanvinken voor velden die je echt als filter gebruikt."

8. Conditional logic

form_fields.conditional_logic JSON:

{
  "show_when": {
    "all": [
      { "field_slug": "has_allergies", "operator": "equals", "value": true }
    ]
  }
}

Operators: equals, not_equals, contains, not_contains, in, not_in, greater_than, less_than, empty, not_empty.

Groups: all (AND), any (OR), nestable.

References: by field_slug within same schema. Cyclic dependencies rejected at save time via depth-first traversal check.

9. Signature field

Stored value JSON structure:

{
  "file_path": "signatures/01HZ.../signature.png",
  "disk": "s3",
  "signed_at": "2026-04-17T14:23:11Z",
  "signer_name": "Bert Hausmans",
  "signer_ip": "10.0.0.1",
  "hash": "sha256:..."
}

Hash = SHA-256 of file_bytes + signed_at + signer_name + signer_ip. Computed server-side on submit.

Once submitted, a signature form_value is immutable. The whole submission transitions to an archived-locked state preventing further edits.

9.1 [v1.2] Storage disk configuration

File paths relative to disk specified in signature value. Disk comes from config('filesystems.default') unless overridden per field:

"validation_rules": { "storage_disk": "s3-private" }

9.2 [v1.2] Signature verification

SignatureVerificationService::verify(FormValue $value): bool:

Reads file bytes from stored disk + path
Recomputes SHA-256 using stored signed_at/signer_name/signer_ip
Compares with stored hash
Returns true/false

Used by: admin UI ("Verify integrity" button on submitted signatures), legal-export endpoint (out of scope for v1, but service exists from day 1).

Integrity-mismatch triggers activity log entry at warning level AND notification to org_admin.

10. Public token flow

Schemas with public purposes get a public_token ULID.

URL: https://app.crewli.app/f/{public_token}

Rules:

GET on token URL: returns schema + empty submission state
POST on token URL: creates submission; subject_type = null (or derived from token)
No authentication required
Rate-limited per IP per schema per hour (configurable, default 5)
Captcha REQUIRED for truly public purposes: public_complaint, public_press_request
Captcha NOT required for entity-token flows (artist_advance via artist.portal_token; supplier_intake via production_request.token)
public_submitter_email: collected but never echoed in public responses

Token rotation: setting a new public_token moves current to public_token_previous and stamps public_token_rotated_at. Requests using the previous token are accepted for a grace period (default 7 days), allowing users to complete already-opened forms. After grace: old token returns 410 Gone.

10.1 [v1.2] Captcha provider

Cloudflare Turnstile (free, privacy-first, EU-friendly). Configuration in config/form_builder.php:

'captcha' => [
    'provider' => 'turnstile',
    'site_key' => env('TURNSTILE_SITE_KEY'),
    'secret_key' => env('TURNSTILE_SECRET_KEY'),
    'required_for_purposes' => ['public_complaint', 'public_press_request'],
],

Frontend embeds Turnstile widget. Backend validates token via CaptchaVerificationService::verify(string $token, string $remoteIp): bool before allowing submission.

Invalid captcha → 422 with clear error.

10.2 [v1.2] Rate limit storage

Uses Laravel's native RateLimiter facade. Backing store is config('cache.default') — typically Redis in production, array-cache in tests.

Rate limit key format: form-submit:{public_token}:{ip}

When limit hit: 429 Too Many Requests, with Retry-After header.

10.3 [v1.2] public_submitter_ip retention

public_submitter_ip is stored for audit/abuse-prevention. Automatically anonymised after 30 days post-submission by scheduled job (configurable via config/form_builder.php.public_submitter_ip_retention_days).

When anonymised: IP replaced with "[anonymised]" and public_submitter_ip_anonymised_at set.

Exception: if submission is flagged for investigation (organiser marks it), anonymisation is paused until flag is cleared.

11. Migration plan

Breaking change. No dual-support phase. Frontend updated in same PR.

11.1 Migration order

Create new tables: form_schemas, form_submissions, form_value_options, form_field_library, form_schema_sections, form_submission_section_statuses, form_submission_delegations, form_schema_webhooks, form_webhook_deliveries, user_profiles
Rename: registration_form_fields → form_fields; add form_schema_id (nullable), keep event_id temporarily
Rename: person_field_values → form_values; add form_submission_id (nullable), keep person_id + registration_form_field_id temporarily
Rename: registration_field_templates → form_templates
Run data-migration script (§11.2)
Drop legacy columns: form_fields.event_id, form_values.person_id, form_values.registration_form_field_id
Apply new indexes

Each step is a separate migration file with reversible down().

11.2 Data migration script

Runs per organisation inside a transaction. Fails fast on unexpected shapes.

For each distinct event_id in (legacy) form_fields:
  1. Create form_schemas row:
     - organisation_id = event.organisation_id
     - owner_type = 'event', owner_id = event.id
     - purpose = 'event_registration'
     - name = event.name + ' registratie'
     - slug = event.slug + '-registratie'
     - is_published = (event status allows it)
     - submission_mode = 'draft_single'
     - version = 1
     - snapshot_mode = 'never'
     - created_by_user_id = first event_user_roles.user_id WHERE role=admin
  2. Update form_fields rows for that event:
     - form_schema_id = newly created schema's id
     - Preserve slug, field_type, config
     - Set is_pii via heuristic (see §11.2.1)
  3. For each distinct person with form_values for this event:
     - Create form_submissions:
       - form_schema_id = schema.id
       - subject_type = 'person', subject_id = person.id
       - submitted_by_user_id = person.user_id (may be null)
       - status = 'submitted' (if person.status >= applied) else 'draft'
       - submitted_at = MIN(form_values.created_at for that person)
       - schema_version_at_submit = 1
       - is_test = false
     - Update form_values:
       - form_submission_id = submission.id
       - For value_storage_hint != 'json': backfill typed columns
       - For is_filterable fields: backfill value_indexed / form_value_options
  4. For each registration_field_template:
     - Compute schema_snapshot
     - Create form_templates row with purpose='event_registration'

After all organisations processed:
  - Seed system templates per org (idempotent)
  - Seed system person_tags per org (idempotent)
  - Seed form_field_library system fields per org (idempotent)

Verification queries:
  - Count old registration_form_fields = count new form_fields
  - Count old person_field_values = count new form_values
  - Every form_field has non-null form_schema_id
  - Every form_value has non-null form_submission_id
  - Sample submission round-trip: render matches old view
  - Orphan check: no form_values with null form_submission_id
  - Orphan check: no form_values referencing non-existent form_field_id

11.2.1 [v1.2] PII heuristic

For legacy fields without is_pii flag:

$piiSlugPatterns = [
    'email', 'phone', 'telefoon', 'adres', 'address',
    'emergency_contact', 'noodcontact', 'noodnummer',
    'geboort', 'birthdate', 'birth_date', 'dob',
    'allergie', 'allergy', 'medisch', 'medical',
    'dieet', 'diet',
    'toegangs', 'access',
    'bsn', 'social_security',
    'iban', 'bank',
];

$piiFieldTypes = ['EMAIL', 'PHONE'];

$isPii = in_array($field->field_type, $piiFieldTypes)
    || collect($piiSlugPatterns)->contains(fn($p) => str_contains(strtolower($field->slug), $p));

Organisers can fine-tune after migration via form-builder UI.

11.3 Rollback

Each migration has down(). Rollback restores legacy columns (event_id, person_id, registration_form_field_id) from the new structure before renaming tables back.

11.4 Migration rehearsal (mandatory)

Before running on real data:

Take a full dump of dev DB
Run migration on a copy
Run comparison script: per organisation, compare pre/post counts and sample 10 random submissions, assert identical rendering
If any mismatch: stop, investigate
Only after clean rehearsal run on main dev DB

12. Seeding strategy

12.1 System form templates (on org creation, idempotent)

Every new organisation gets these with is_system = true. Detailed field lists in §3.2 (per-purpose lifecycles).

EventRegistrationDefault (§3.2.1)
UserProfileDefault (§3.2.2)
ArtistAdvanceDefault (§3.2.5)
SupplierIntakeDefault (§3.2.6)
IncidentReportDefault (§3.2.7)
PostEventEvaluationDefault (§3.2.9)
SignatureContractDefault (§3.2.10)
SignatureCodeOfConductDefault (§3.2.11)
SignatureReceiptDefault (§3.2.12)
FeedbackDefault (§3.2.8)

System templates can be customised per org but not deleted; only deactivated.

12.2 System form_field_library entries (on org creation, idempotent)

Common reusable fields seeded per organisation:

Shirtmaat (SELECT, options: XS/S/M/L/XL/XXL, is_filterable=true)
Dieetwensen (CHECKBOX_LIST, options: vegetarisch/veganistisch/ glutenvrij/lactosevrij/halal/kosher, is_filterable=true)
Noodcontact naam (TEXT, is_pii=true)
Noodcontact telefoon (PHONE, is_pii=true)
Geboortedatum (DATE, is_pii=true)
Toestemming AVG (BOOLEAN, required, consent field)
Opmerkingen (TEXTAREA)

Organiser can insert these into any schema with one click.

12.3 System person_tags (on org creation, idempotent)

Certificates (category: Certificaat): EHBO, BHV, VCA-VOL, VCA-BASIS, SVH Sociale Hygiëne, Horeca-diploma, Keuringsregister, Rijbewijs A, Rijbewijs B, Rijbewijs BE, Rijbewijs C, Rijbewijs CE, Aanhangwagen-rijbewijs, Heftruckcertificaat, Hoogwerker-certificaat, AED-training.

Languages (category: Taal): Engels, Duits, Frans, Spaans, Italiaans, Arabisch, Turks, Pools, Portugees.

Skills (category: Vaardigheid): Tapper, Barista, Kassa-ervaring, Security-ervaring, Podium-ervaring, Techniek-ervaring, Logistiek-ervaring, Cateringervaring, Schoonmaak-ervaring, Verkeersregelaar, Parkeerplaats-ervaring.

Seeded via PersonTagSystemSeeder using updateOrCreate keyed on (organisation_id, name). Organisations can deactivate seeded tags; cannot delete (hidden flag is_system_seed = true).

13. Governance & compliance

13.1 PII-flagging

form_fields.is_pii = true marks a field as personal data. Effects:

Included in PII-audit endpoint: GET /organisations/{org}/forms/pii-fields
Treated as sensitive in exports (red border, extra confirmation)
Subject to retention_days when set
Displayed with PII-indicator icon in organiser UI

13.2 Retention policies

form_schemas.retention_days (nullable int). When set:

Scheduled job FormSubmissionRetentionJob runs daily at 03:00
Finds submissions where submitted_at < NOW() - retention_days AND is_test = false AND anonymised_at IS NULL
Calls FormSubmissionAnonymisationService (§13.3)
Sends aggregate notification email to org_admin at end of run: "{count} submissions anonymised today for organisation X"

13.3 Right-to-be-forgotten (anonymisation)

FormSubmissionAnonymisationService::anonymise(FormSubmission):

For each form_value of a submission:
- If field.is_pii: set value='[ANONYMISED]', value_indexed=null, value_number/date/bool=null, value_anonymised=true
- If signature field: delete signature file, replace value with {anonymised: true}
- If file_upload field: delete file, replace value with {anonymised: true, original_filename_redacted: true}
Set submission.anonymised_at = NOW()
Clear submission.search_index
Log activity log entries per field (one entry per anonymised field)
Fire FormSubmissionAnonymised event

Called by:

Admin action via POST /form-submissions/{id}/anonymise (org_admin only)
Automatic retention job based on retention_days
GDPR user-initiated deletion request (see §13.4)

When a user requests data deletion (§31.2 integration contract):

All form_submissions where subject_type = 'user' AND subject_id = that_user are anonymised
All form_submissions where submitted_by_user_id = that_user: submitted_by_user_id → null; name/email copied to public_submitter_* before clearing
user_profiles row deleted (cascade via FK)
user_organisation_tags for that user deleted
Activity log entries for that user anonymised (causer replaced with "[deleted-user]" but action records preserved)

GDPR export endpoint (§31.2):

GET /api/v1/users/{user}/gdpr-export

Returns JSON with all user-owned data. Organiser-initiated via admin action, or user-initiated via portal profile page. Format: JSON (v1). PDF export deferred.

form_schemas.consent_version — when a submission is made, the schema's current consent_version is snapshotted into the submission's schema_snapshot (if snapshot_mode != 'never') OR logged in activity log at minimum. Organiser can demonstrate which consent text the submitter accepted.

13.6 Test submissions

form_submissions.is_test = true:

Excluded from all list/aggregate endpoints by default
Excluded from retention policies (never anonymised)
Excluded from export endpoints
Accessible only via explicit include_test=true query param
Created via "Test submission" button in form preview
Do not fire webhooks
Do not count toward max_submissions cap

Organiser can create test submissions without cluttering real data. Test submissions are purged manually via a "Clear test data" action.

14. Schema lifecycle & versioning

Three independent mechanisms; each with a distinct purpose.

14.1 `form_schemas.version`

Always active. Integer, starts at 1, bumped on any schema-structural edit (fields added/removed/reordered, required/optional changes, options changes). Bump triggered by FormSchemaService on save. Used for:

Detecting schema drift between current and submission-time state
Generating ETags for caching
Cache invalidation

Version bumps do NOT produce separate activity log entries when snapshot_mode=never — the field-level activity log entries already cover the actual change. When snapshot_mode=on_submit or always, the version bump is logged for cross-reference with stored snapshots.

14.2 `form_schemas.snapshot_mode` + `form_submissions.schema_snapshot`

Controls whether and when full schema snapshots are stored per submission:

never (default) — no snapshot; trust version number + audit log for history
on_submit — snapshot stored when submission transitions to status=submitted
always — snapshot stored on any save, including drafts

Used for high-stakes submissions (contracts, signature_receipt, post_event_evaluation for regulatory retention). Trade-off: more storage, but bulletproof audit trail.

Snapshot structure defined in §4.6.1.

14.3 `form_schemas.freeze_on_submit`

If true: once the schema has at least one submission with status=submitted, the schema becomes read-only at the field-structure level. Labels/help_text can still be edited (lightly); fields cannot be added, removed, or have their type changed. Bypass requires elevated permission and creates a loud audit log entry.

Complementary to version + snapshot, not overlapping: freeze_on_submit prevents edits; version tracks them; snapshot preserves history.

14.4 Test/preview submissions

form_submissions.is_test = true for:

Submissions created from form preview mode
Submissions created with an X-Crewli-Test-Mode: true header

See §13.6 for test submission semantics.

14.5 [v1.2] Edit-lock mechanism

form_schemas.edit_lock_user_id + edit_lock_expires_at implement pessimistic locking for collaborative editing:

When organiser A opens the form-builder in edit mode: acquire lock with edit_lock_user_id = A, edit_lock_expires_at = now() + 10 minutes
Heartbeat: every 2 minutes while edit is open, extend edit_lock_expires_at by another 10 minutes
When organiser B tries to open the same schema in edit mode:
- If current lock expired: auto-release, B acquires
- If current lock still valid: 409 Conflict with holder's name + expiration time
- B can force-steal via explicit confirmation (creates audit log entry)
On save/close: release lock
On logout/connection loss: heartbeat stops, lock auto-expires

Frontend UX: lock banner shows "Schema wordt bewerkt door {naam} (nog {X} minuten)" with "Vraag toegang" button that triggers force-steal flow.

14.6 [v1.2] Form preview mode

Preview endpoint:

GET /api/v1/organisations/{org}/form-schemas/{schema}/preview

Returns the schema in render-ready format with sample field values that drive conditional_logic. No submission created; values are mocked per-field-type (TEXT = "Lorem ipsum", SELECT = first option, etc.).

Frontend renders preview in a side-panel or separate route without the normal submit flow (submit button disabled or replaced with "Dit is een voorbeeld").

Organiser can toggle "Test mode" in preview — triggers actual submission with is_test=true so they can verify the whole flow end-to-end.

15. Workflows & submission reviews

15.1 Simple review flow

Every submission supports review regardless of schema:

review_status on form_submissions: null / pending_review / approved / rejected / changes_requested
Set via POST /form-submissions/{id}/review with body { status, review_notes }
Fires FormSubmissionReviewed event
Activity log records reviewer, decision, notes

15.2 Section-level submit (for advancing)

When form_schemas.section_level_submit = true:

form_schema_sections define independent submit units
form_submission_section_statuses track per-section state
Each section has its own submit/review flow
Section dependencies (depends_on_section_id) gate later sections until earlier ones are approved

15.3 Delegation

For "Nina fills in my advance on my behalf":

Subject grants delegation via POST /form-submissions/{id}/delegate
Delegated user can view and edit that submission
Delegator retains full control and can revoke
Delegation audited via activity log

Note: delegation is per-submission, not per-schema. Organisers don't grant delegations — subjects do.

15.4 Multi-step gating

Via form_schema_sections.depends_on_section_id. A section is locked (read-only, clearly marked) until the dependency's section_status is 'approved'. Used for workflows like "finish general info first, then rider details unlock".

15.5 [v1.2] Review workflow notifications

On status change:

pending_review → notify org_admins (or event_managers if schema is event-scoped) via CrewliMailable
approved → notify submitter (if authenticated user) via CrewliMailable
rejected / changes_requested → notify submitter with review_notes in email

Notification flow is asynchronous via FormSubmissionReviewed event listener SendReviewNotificationListener. Recipients configurable per schema via form_schemas.settings.review_notification_recipients (array of user_ids or role names).

16. Internationalisation

16.1 Per-field translations

form_fields.translations JSON:

{
  "en": {
    "label": "T-shirt size",
    "help_text": "What size do you wear?",
    "options": ["XS", "S", "M", "L", "XL", "XXL"]
  },
  "de": {
    "label": "T-Shirt Größe",
    "help_text": "Welche Größe trägst du?",
    "options": ["XS", "S", "M", "L", "XL", "XXL"]
  }
}

If no translation exists for a locale, fallback applies (§16.2).

16.2 Locale fallback chain

FormLocaleResolver service determines the effective locale:

submitter.locale (if submitter is authenticated)
Explicit locale passed in request (via Accept-Language header)
form_schemas.locale (schema's primary locale)
App default locale (config('app.locale'))

Each field label/help_text/options resolved per-locale, with graceful fallback to default-locale values when translation is missing.

16.3 Timezone handling

DATETIME values are stored as UTC ISO-8601. Display-time conversion to submitter's timezone:

users.timezone (if authenticated)
organisation.timezone
App default (config('app.timezone'))

submitted_in_locale on form_submissions stores the locale used at submit time for audit.

16.4 Runtime resolution deferred

For v1, translations column EXISTS but runtime locale resolution is minimal (schema.locale + fallback only). Full per-field runtime swap is deferred; v1 renders in the schema's primary locale with translations column available for future activation.

17. Extensibility & integrations (webhooks, custom field types, custom purposes)

17.1 Laravel events

Every submission state change fires a Laravel event. Registered in EventServiceProvider.

Submission lifecycle events:

FormSubmissionCreated(FormSubmission $submission) — on insert
FormSubmissionDraftUpdated(FormSubmission $submission, array $changedFields) — on draft save (rate-limited to once per 30s to prevent spam)
FormSubmissionSubmitted(FormSubmission $submission) — status → submitted
FormSubmissionReviewed(FormSubmission $submission, string $outcome) — review_status change
FormSubmissionAnonymised(FormSubmission $submission) — on anonymisation
FormSubmissionArchived(FormSubmission $submission) — status → archived
FormSubmissionDeleted(FormSubmission $submission) — soft-deleted
FormSubmissionSectionSubmitted(FormSubmission, FormSchemaSection) — section submit
FormSubmissionSectionReviewed(FormSubmission, FormSchemaSection, string $outcome) — section review

Schema lifecycle events (optional, activity log covers most):

FormSchemaPublished(FormSchema $schema)
FormSchemaUnpublished(FormSchema $schema)
FormSchemaTokenRotated(FormSchema $schema)

All events implement ShouldBroadcast so real-time UI updates are possible in future iterations.

17.2 Custom field types

CustomFieldTypeRegistry allows extensions without core code changes:

// config/form_builder.php
'custom_field_types' => [
    'rich_text' => \App\FormFieldTypes\RichTextFieldHandler::class,
    // ...
],

Each handler implements CustomFieldTypeHandler interface:

interface CustomFieldTypeHandler
{
    public function validateValue(mixed $value): ValidationResult;
    public function transformForStorage(mixed $value): array;
    public function transformForDisplay(array $storedValue): mixed;
    public function getUISchema(): array; // tells frontend how to render
    public function supportsFiltering(): bool;
    public function getValueStorageHint(): ?string;
}

FormSchemaService uses the registry when validating field_type on create/ update. Built-in types are registered by default. Custom types extend the list without code changes to core.

17.3 Custom purposes per organisation

FormPurpose::CUSTOM + form_schemas.custom_purpose_slug string. Organisations define their own purposes (e.g., brandweertraining_certificering).

Rules:

custom_purpose_slug required when purpose=custom
Unique(organisation_id, custom_purpose_slug) when purpose=custom
Subject type and submission_mode must be explicitly set (no purpose- derived defaults)
Public token not allowed for custom purposes in v1 (future: per-slug allowlist)

17.4 Custom validation callbacks

form_fields.validation_rules JSON supports callback references:

{
  "callback": "App\\Services\\Validators\\KvkValidator@validate"
}

Registered callbacks in config/form_builder.php:

'validation_callbacks' => [
    'kvk_lookup' => \App\Services\Validators\KvkValidator::class,
    // ...
],

Unregistered callbacks rejected at save time.

17.5 Webhooks

17.5.1 Schema

See §4.11 form_schema_webhooks and §4.12 form_webhook_deliveries.

17.5.2 Dispatcher

FormWebhookDispatcher listens for FormSubmissionSubmitted / Reviewed / SectionSubmitted / SectionReviewed events. On trigger:

Finds matching webhooks for the schema
For each: creates a form_webhook_delivery row with status=pending
Queues DeliverFormWebhookJob per delivery on dedicated webhooks queue

17.5.3 Delivery job

DeliverFormWebhookJob on webhooks queue:

Idempotent (Laravel job with unique ID per delivery)
Timeout: 30s per attempt
On execution:
- Builds payload (submission data + trigger_event + schema metadata)
- Signs with HMAC-SHA256 if webhook.secret is set, header: X-Crewli-Signature: sha256=...
- POSTs to webhook.url with 10-second HTTP timeout
- On 2xx: updates delivery status=delivered, delivered_at=now()
- On retriable (5xx, timeout, network): exponential backoff (1m, 5m, 30m, 2h, 8h). Max 5 attempts.
- On non-retriable (4xx except 408/429): delivery status=failed, logged
- After all retries exhausted: status=dead_letter

Response body first 1000 chars stored in response_body_excerpt for debugging.

17.5.4 Security

URL validation in FormWebhookDispatcher:

Parse URL; reject non-http(s)
Resolve host; reject private IP ranges (10.x, 172.16–31.x, 192.168.x, 127.x, 169.254.x — AWS metadata)
Check allowlist if configured in config/form_builder.php.webhooks.allowlist_domains
Check blocklist; configurable IP ranges default to private + metadata

Admin UI shows validation status + last delivery attempt per webhook.

17.5.5 Webhook payload format

{
  "event": "form_submission.submitted",
  "triggered_at": "2026-04-17T14:23:11Z",
  "organisation": {
    "id": "01H...",
    "name": "...",
    "slug": "..."
  },
  "schema": {
    "id": "01H...",
    "purpose": "event_registration",
    "slug": "...",
    "version": 3
  },
  "submission": {
    "id": "01H...",
    "subject_type": "person",
    "subject_id": "01H...",
    "submitted_at": "2026-04-17T14:23:11Z",
    "submitted_by_user_id": null,
    "values": {
      "shirtmaat": "M",
      "dieetwensen": ["vegetarisch"],
      ...
    }
  }
}

PII fields are included in webhook payloads only if subscriber has been acknowledged (future feature: per-webhook PII opt-in). For v1, PII is sent — organisers warned during webhook creation.

18. Consistency & interaction rules

This section prevents components built in isolation from conflicting.

18.1 Schema evolution mechanisms

Three orthogonal mechanisms; never use them interchangeably:

schema_version = MARKS edits (always active)
schema_snapshot = BACKS UP state (per schema's snapshot_mode)
freeze_on_submit = PREVENTS edits (after first submission)

Pairing guidance:

Low-stakes forms (event_registration): snapshot_mode=never, freeze_on_submit=false
Audited forms (incident_report): snapshot_mode=on_submit, freeze_on_submit=true
Legal/contract forms (signature_contract): snapshot_mode=on_submit, freeze_on_submit=true

18.2 Hergebruik mechanisms

Three forms of reuse; distinct roles:

form_templates = COMPLETE starting point for new schemas (apply → new schema with copied fields)
form_field_library = SINGLE reusable field definition (insert → new form_field with reference)
schema_snapshot = FROZEN copy for audit (auto-generated, not reused)

A template can reference library fields in its schema_snapshot; when the template is applied, library fields are resolved to current library definitions at that moment (denormalised into the resulting form_fields).

18.3 Role restrictions vs Pattern C interaction

Rule: role_restrictions gate what OTHER users see. A subject always sees their own entity-owned or mirrored values. Example: a volunteer sees their own emergency_contact_phone even if role_restrictions hide it from organiser_members.

Validated by FieldAccessService: canRead(user, field, submission) returns true when user.id == submission.subject_id (and subject_type is 'user' or submission.subject is user's person) regardless of role_restrictions.

18.4 Auto-save vs is_test vs status

Auto-save always produces submissions with is_test=false and status='draft'
Test mode (form preview) produces submissions with is_test=true — regardless of auto-save setting
Status='draft' becomes 'submitted' only on explicit user submit, never on auto-save

18.5 Events as backbone

Webhooks, activity log, analytics, emails, and all integrations attach as LISTENERS on Laravel events. Never fire webhooks or log activity ad-hoc inside services. Rule: if your service needs to trigger a side effect on submission state change, add a listener to the relevant event. This keeps services testable and the event graph discoverable.

18.6 System-internal vs form-rendered reads

Services that consume profile/person/artist data for internal purposes (e.g., computing reliability_score, matching identity, sending briefings) read DIRECTLY from entity tables (user_profiles, persons, etc.). They do NOT go through form_fields/form_values.

The form layer is ONLY for:

Rendering forms to end users (reading bindings to prefill)
Accepting submissions (writing bindings back)
Displaying submissions to organisers (rendering stored form_values)

This rule is enforced by architecture reviews.

19. Self-hosting principle ("eat your own dog food")

Wherever possible, internal Crewli forms are expressed through the form builder itself. This is a test of universality: if our builder can't produce our own configuration UIs, it's not universal enough.

Targets in v1:

Onboarding wizard (FormPurpose::ONBOARDING_WIZARD) and event_setup_wizard ARE self-hosted from day one — they exist in the enum and are a test of universality.

20. Trade-offs & cost awareness

20.1 Performance contract

Pattern A lookups MUST be as fast as current direct-column lookups. The form layer is NOT a performance tax on system-internal reads — see §18.6. Pattern A bindings are documented, but services reading them consume the entity table directly.

20.2 Testing strategy

The FormPurpose × pattern × field-type matrix is combinatorially large. Pragmatic coverage:

Integration tests per FormPurpose: happy path for each of the 22 purposes, minimum one test each
Unit tests per field type: value transformation on read/write
Security invariant tests: admin_only fields never leak, role_restrictions enforced, SSRF blocked, binding-change-safeguard triggers
Migration rehearsal test: fixture-based test replicating the §11.2 script on a seeded dataset
Integration contract tests: per §31 contract, verify forms-to-other- module handoffs work

Target: 95%+ coverage on FormSchemaService, FormSubmissionService, FormValueService, FieldAccessService, FormLocaleResolver, FormWebhookDispatcher.

20.3 Developer onboarding

A new developer should be able to:

Understand "what is a form_schema" in under 10 minutes (TL;DR section)
Create a new FormPurpose and wire up a schema in under 1 hour (with template)
Add a custom field_type in under 4 hours (with CustomFieldTypeHandler example)

Quality gate: during implementation, write a /dev-docs/form-builder-getting-started.md with code examples per common scenario (new schema, new field type, new webhook, new subject type).

20.4 Migration risk

Mandatory rehearsal (§11.4) on dev DB copy before real migration. Comparison script output is part of the migration approval gate.

21. Pre-flight audit gate

Every Claude Code session starts with this audit, BEFORE any code changes:

# 1. Migration files
find api/database/migrations -name "*volunteer_profile*" -o -name "*user_profile*"

# 2. Model classes
find api/app/Models -name "VolunteerProfile*" -o -name "UserProfile*"

# 3. Resources
find api/app/Http/Resources -name "VolunteerProfile*" -o -name "UserProfile*"

# 4. References
grep -rn "volunteer_profile\|VolunteerProfile\|user_profile\|UserProfile" \
  api/app/ api/database/ --include="*.php"

# 5. Legacy column leakage
grep -rn "access_requirements\|tshirt_size\|first_aid\|driving_licence" \
  api/database/migrations/

# 6. Git history
git log --oneline --all | grep -iE "volunteer.profile|user.profile|volunteer_profiles"

# 7. Working tree
git status
git diff

Report findings. Nothing found → proceed. Anything found → STOP, report, wait for Bert's approval of proposed revert plan.

Audit is MANDATORY until the refactor completes and ARCH-FORM-BUILDER.md is marked as "refactor complete". After that, the audit is removed from session prompts.

22. Failure-mode resilience

22.1 Idempotency

Client-generated idempotency_key (ULID) in submission submit requests. Backend: UNIQUE(form_schema_id, idempotency_key) partial where not null. Duplicate request with same key is a no-op returning the original submission.

22.2 Auto-save

When form_schemas.auto_save_enabled=true:

Frontend debounces input at 2s; sends PUT on the draft submission
Backend endpoint PUT /form-submissions/{id}/auto-save accepts partial payloads (only changed fields)
Increments auto_save_count for debugging
Does not fire FormSubmissionDraftUpdated event on every auto-save (rate-limited to one event per 30s per submission) to prevent webhook storms
On auto-save failure: client retains local-storage backup and retries. Max 3 retry attempts with exponential backoff, then UI shows "Kon niet opslaan — probeer handmatig" warning.

22.3 Binding-change safeguard

See §6.5.

22.4 Audit trail

form_schemas.created_by_user_id, last_updated_by_user_id
Activity log on form_schemas, form_fields, form_submissions
Webhook deliveries logged with payload snapshots

22.5 Webhook security

See §17.5.4. SSRF prevention, allowlist/blocklist, timeouts.

22.6 File upload security

For FILE_UPLOAD / IMAGE_UPLOAD field types:

Server-side MIME type validation (never trust client)
Default allowed MIMEs in config/form_builder.php.file_uploads.default_allowed_mime_types
Per-field override via validation_rules.allowed_mime_types
Size cap default 5MB, per-field override via validation_rules.max_size_mb
Stored under {storage_disk}/form-uploads/{submission_id}/{ulid}.{ext}
Filename sanitised; original name stored as metadata only

Storage disk: config('filesystems.default') by default. Per-field override: validation_rules.storage_disk.

22.7 Soft limits

config/form_builder.php:

return [
    'limits' => [
        'max_fields_per_schema' => 100,
        'max_filterable_fields_per_schema' => 20,
        'max_options_per_field' => 100,
        'max_submissions_per_public_schema_per_ip_per_hour' => 5,
    ],
    'webhooks' => [
        'allowlist_domains' => [],
        'blocklist_ips' => ['127.0.0.0/8', '10.0.0.0/8', '172.16.0.0/12',
                             '192.168.0.0/16', '169.254.169.254/32'],
        'timeout_seconds' => 10,
        'max_attempts' => 5,
    ],
    'file_uploads' => [
        'default_allowed_mime_types' => ['image/jpeg', 'image/png', 'image/webp',
                                          'application/pdf'],
        'default_max_size_mb' => 5,
    ],
    'search_index' => [
        'max_chars' => 10000,
    ],
    'captcha' => [
        'provider' => 'turnstile',
        'required_for_purposes' => ['public_complaint', 'public_press_request'],
    ],
    'public_submitter_ip_retention_days' => 30,
    'user_profile_settings_whitelist' => [
        'ui.theme', 'ui.sidebar_collapsed', 'ui.time_format',
        'notifications.email_digest', 'notifications.shift_reminders',
        'notifications.event_updates',
    ],
    'custom_field_types' => [],
    'validation_callbacks' => [],
];

Violations rejected at Form Request validation layer with clear error messages.

22.8 Destructive operations

Deleting a schema with submissions requires typed confirmation (organiser types the schema name). Deleting a field with values requires same. Confirmation flow implemented in frontend; backend accepts ?confirmed_name=<n> query param.

22.9 Admin-only field leak prevention

Test class FormResourceSecurityTest covers:

For each FormPurpose, a submission is fetched by non-admin user
Assert admin_only fields are not in the response
Applied to both list and detail endpoints
Run as part of CI

22.10 [v1.2] Queue configuration

Dedicated queues for form-builder jobs:

// config/queue.php — add
'connections' => [
    'webhooks' => [
        'driver' => 'redis',
        'queue' => 'webhooks',
        'retry_after' => 120,
        'block_for' => null,
    ],
],

Jobs and their queues:

DeliverFormWebhookJob → webhooks queue (dedicated, can be throttled separately)
FormSubmissionRetentionJob → default queue (daily schedule)
BackfillFormValueIndexedJob → default queue (on is_filterable toggle)
RebuildSearchIndexJob → default queue (on is_filterable or binding change)

Frontend event broadcasts (Reverb/Pusher) use their own broadcast queue.

23. Observability & analytics hooks

23.1 Timestamps for funnel analytics

opened_at — first GET on the form (or first frontend render)
first_interacted_at — first field interaction (focus or input)
submitted_at — status → submitted
submission_duration_seconds = submitted_at - opened_at (populated on submit)

23.2 Universal text search

form_submissions.search_index populated by an observer on form_values save. Concatenates all text-type values of a submission (TEXT, TEXTAREA, EMAIL, PHONE, URL, SELECT, RADIO option labels) into a space-separated text field. Indexed with MySQL FULLTEXT.

Max chars configurable (default 10000). Truncated with ellipsis.

For drafts: rebuilt on every form_values save. For submissions: frozen at submit (no further updates unless value changes).

23.3 Activity log depth

form_schemas: create, update (label/field additions/removals), delete, duplicate, version bumps, lock/unlock
form_fields: create, update (with old/new binding, old/new is_filterable, old/new role_restrictions), delete
form_submissions: create, status changes, review changes, delegate, anonymise, delete
form_templates: create, update, activate/deactivate
form_field_library: create, update, activate/deactivate

Activity log entries for webhook deliveries NOT added (they have their own audit table form_webhook_deliveries).

23.4 [v1.2] Anonymisation audit

Each anonymised field produces a SEPARATE activity log entry:

{
  "log_name": "form_value",
  "description": "field.anonymised",
  "subject_type": "FormValue",
  "subject_id": 12345,
  "properties": {
    "field_slug": "emergency_contact_phone",
    "reason": "retention_policy",
    "original_was_pii": true
  },
  "causer_type": "System",
  "causer_id": null
}

Rationale: field-level audit dichtheid matters for GDPR compliance demos.

24. Access control per field

24.1 `form_fields.role_restrictions` JSON

{
  "read": {
    "any_of_roles": ["org_admin", "event_manager"]
  },
  "write": {
    "any_of_roles": ["org_admin"]
  }
}

Operators on roles:

any_of_roles: user needs at least one listed role
all_of_roles: user needs all listed roles
not_roles: user must not have any listed role
subject_self: true → the subject themselves always has access (overrides other rules)

If role_restrictions is null: defaults to { read: true, write: { any_of_roles: ["org_admin", "event_manager"] } } for is_admin_only=false fields, and stricter for is_admin_only=true.

24.2 FieldAccessService

class FieldAccessService
{
    public function canRead(User $user, FormField $field, FormSubmission $submission): bool;
    public function canWrite(User $user, FormField $field, FormSubmission $submission): bool;
    public function filterVisibleFields(User $user, Collection $fields, FormSubmission $submission): Collection;
}

Used by:

FormResource / FormSubmissionResource when rendering API responses (hides invisible fields)
FormValueService when accepting submits (rejects writes to fields user can't write)
FilterQueryBuilder when applying filters (rejects filters on invisible fields with 403)
Form-builder UI (hides disallowed actions)

24.3 Test coverage

FieldAccessServiceTest and FormResourceSecurityTest ensure:

Per role, correct fields visible/editable
Subject-self always has access
Cross-org attempts blocked
role_restrictions=null defaults applied consistently

25. Self-hosting reservations (FormPurpose slots)

FormPurpose enum values reserved for future self-hosting (not implemented in v1.2):

schema_editor — would host the "create/edit form_schema" form as a form itself
field_editor — would host the "create/edit form_field" form as a form

When these become implemented, they demonstrate §19 (self-hosting) by making the builder's own UI a form defined through the builder.

26. Open questions / deferred decisions

Analytics dashboards — drop-off detection, A/B testing, completion rate dashboards. Telemetry client-side required. Deferred.
Marketplace templates — sharing templates between orgs. Deferred.
AI-generated schemas — LLM scaffolding of form definitions. Deferred.
Org-specific bindable columns — orgs adding custom columns on user_profile and binding to them. Needs a schema-extension subsystem. Deferred.
Bulk-edit values — "set dietary_preference=null for all persons". UX-heavy, needs audit. Deferred.
Schema-editor self-hosting — see §25. Deferred to a future phase.
Realtime collaborative editing — multiple editors with live cursors. Current v1.2 uses pessimistic locks (§14.5 edit_lock_*). Deferred to later phase with CRDT.
PDF export of submissions — deferred to PDF module.
Print layouts — deferred to PDF module.
Per-webhook PII opt-out — webhooks always receive PII in v1. Deferred.

27. Out of scope for this refactor

Workflow / approval escalation chains beyond the simple review flow
Notifications on submit/update beyond core integrations (advanced notification preferences UI)
PDF export of submissions (PDF module)
Rich-text TipTap-based fields (TIPTAP field type comes in a later phase)
Client-side field-by-field drop-off analytics
A/B testing of schema variants
Email bounce verification for public submissions
Legal signature-verification service (exists as stub in v1.2; UI deferred)

28. [v1.2] User guidance principles

This section defines the non-negotiable UX standards for form-builder features. No feature ships without complying with all five principles.

28.1 Every decision-impacting control has contextual help

Controls that change system behaviour in non-obvious ways must have an icon-triggered tooltip or inline explanation. Examples:

is_filterable toggle — tooltip: "Dit veld wordt extra geïndexeerd voor snelle filtering in overzichten. Alleen aanvinken voor velden die je daadwerkelijk als filter gebruikt."
is_pii toggle — tooltip: "Dit veld bevat persoonsgegevens. Bij retentie-verwerking worden deze waardes geanonimiseerd."
freeze_on_submit toggle — tooltip: "Na de eerste ingediende submissie kunnen de velden niet meer gewijzigd worden. Gebruik dit voor contracten of audit-kritieke formulieren."
snapshot_mode dropdown — per optie een korte uitleg in de dropdown zelf.
retention_days input — tooltip: "Na deze periode worden PII-velden geanonimiseerd. Vraag bij twijfel je privacy-officer om advies."

Rule of thumb: if an organiser has to guess what a toggle does, it's a bug in the UX.

28.2 Every destructive action has a preview or confirmation

Actions that cannot be undone (or are painful to undo) require either:

A preview showing consequences before the action, OR
A typed-confirmation dialog (user types the item name)

Destructive actions in scope:

Delete schema with submissions → typed confirmation
Delete field with values → typed confirmation
Change field's binding when submissions exist → preview showing "X submissions will be orphaned" + typed confirmation
Rotate public_token → preview showing grace period
Anonymise submission manually → typed confirmation
Change field_type (changes storage format) → preview + typed confirmation

Preview structure:

What will happen (list)
How many records affected
Whether action is reversible (and how)
Typed confirmation input if irreversible

28.3 Schema preview before publishing

Organiser can preview a schema at any time:

As each supported user role (volunteer, organiser admin, etc.)
In each locale (if translations exist)
With sample data driving conditional_logic
On mobile + desktop viewport

Preview button is prominently visible in form-builder UI, not hidden in a menu. Published schemas show a "Bekijk live formulier" link in the same place.

28.4 Onboarding for new features

Any new major feature (e.g., webhooks, section-level submit, custom field types) includes onboarding:

First-time dialog when the feature is accessed, explaining it briefly
Link to full VitePress documentation
Dismissible with "Niet meer tonen" checkbox — preference stored in user_profiles.settings

28.5 In-app documentation links

Every complex screen has a link to the relevant VitePress documentation:

Form-builder UI → /docs/organizer/forms/form-builder-overview
Webhook configuration → /docs/organizer/forms/webhooks
Retention policies → /docs/organizer/forms/privacy-and-retention
Field library → /docs/organizer/forms/reusable-fields
Section-level submit → /docs/organizer/forms/advancing-forms

Links open in new tab, marked with external-link icon.

29. [v1.2] Documentation coverage requirements per session

Every S1-S6 session MUST ship VitePress documentation alongside the code. Documentation is not an afterthought; it is part of Definition of Done.

29.1 Per-session docs requirement

Each implementation session delivers documentation covering:

User-facing feature — what the feature is, in organiser's language
How-to guide — step-by-step for the most common use-case
Reference — every configuration option explained
Edge cases — what happens in error conditions

Session cannot be marked complete until corresponding docs are reviewed and committed.

29.2 Documentation targets per session

Mapping of ARCH sections to docs pages (written during S1-S6):

ARCH section	VitePress page	Session
§3 FormPurpose	`/docs/organizer/forms/what-is-a-form-purpose`	S3
§4 Core tables	(developer-only, `/dev-docs/form-builder-getting-started.md`)	S1
§5 FormFieldType	`/docs/organizer/forms/field-types`	S3
§6 Field binding	`/docs/organizer/forms/binding-and-entity-columns`	S3
§7 Filter architecture	`/docs/organizer/forms/filtering-submissions`	S4
§8 Conditional logic	`/docs/organizer/forms/conditional-logic`	S3
§9 Signature	`/docs/organizer/forms/signatures-and-contracts`	S3
§10 Public tokens	`/docs/organizer/forms/public-forms`	S3
§13 Governance	`/docs/organizer/forms/privacy-and-retention`	S2
§14 Schema lifecycle	`/docs/organizer/forms/versioning-and-snapshots`	S2
§15 Workflows	`/docs/organizer/forms/reviews-and-delegation`	S4
§17.5 Webhooks	`/docs/organizer/forms/webhooks`	S5

29.3 Migration-specific docs

Before the data migration runs (end of S1), publish:

/docs/organizer/forms/migration-what-changes.md — user-facing changelog
/dev-docs/form-builder-migration-playbook.md — developer runbook

29.4 Copy catalogue as living document

/dev-docs/COPY_CATALOGUE.md is maintained across all sessions — see §30.

29.5 Quality gate

Docs reviewer checks:

No jargon without explanation
Screenshots of the UI where applicable (Cursor/Claude generates, Bert validates in manual verification)
"Als je vastloopt..." troubleshooting section
Link in in-app help menu (§28.5)

30. [v1.2] In-app copy catalogue (living seed)

A single source of truth for user-facing Dutch copy used in form-builder UI. Stored in /dev-docs/COPY_CATALOGUE.md and used as reference for frontend implementation.

Rationale: prevents inconsistent terminology ("Dienst" vs "Shift" vs "Taak") and centralises warnings/tooltips so they can be edited in one place.

30.1 Naming conventions

Concept	Canonical Dutch term	Never use
`form_schema`	Formulier	Schema, template
`form_field`	Veld	Vraag, item
`form_template`	Formulier-sjabloon	Template (alleen in dev-docs)
`form_field_library`	Veldenbibliotheek	Library, bibliotheek alleen
`form_submission`	Inzending	Submission, antwoord
`is_filterable`	Filterbaar	Queryable, zoekbaar
`is_pii`	Bevat persoonsgegevens	Privacy-gevoelig
`freeze_on_submit`	Bevriezen na inzending	Vergrendelen
`consent_version`	Toestemmingsversie	Consent-versie

is_filterable:
  "Filterbaar — dit veld wordt extra geïndexeerd voor snelle filtering
   in overzichten. Alleen aanvinken voor velden die je daadwerkelijk als
   filter gebruikt (bijvoorbeeld: shirtmaat wel, motivatie niet)."

is_pii:
  "Bevat persoonsgegevens — bij retentie-verwerking worden deze waardes
   geanonimiseerd volgens je privacy-instellingen. Vink aan voor velden
   zoals telefoon, e-mail, noodcontact, medische info."

is_unique:
  "Uniek per formulier — waardes van dit veld moeten uniek zijn over alle
   inzendingen heen. Geschikt voor bijvoorbeeld BSN of werknemersnummer.
   Dubbele waardes worden afgewezen."

freeze_on_submit:
  "Bevriezen na eerste inzending — zodra iemand het formulier indient
   kunnen de velden niet meer gewijzigd worden. Gebruik dit voor
   contracten, signatures, of formulieren waar de structuur vast moet
   staan voor audit-doeleinden."

snapshot_mode:
  never: "Geen snapshot — wijzigingen worden alleen in het activity log
         bijgehouden."
  on_submit: "Snapshot bij inzending — bij elke indiening wordt het
             complete formulier gesnapshot voor audit-doeleinden."
  always: "Altijd snapshot — elke wijziging (ook drafts) wordt
          gesnapshot. Gebruikt meer opslag maar biedt het volledige
          audit-spoor."

retention_days:
  "Bewaartermijn — na deze periode (vanaf inzendingsdatum) worden
   PII-velden automatisch geanonimiseerd. Typische waardes: 1095 dagen
   (3 jaar) voor vrijwilligers, 2555 dagen (7 jaar) voor contracten,
   null voor onbeperkt bewaren."

30.3 Warning catalogue (selection)

binding_change_with_submissions:
  "Je staat op het punt de koppeling van dit veld te wijzigen terwijl er
   al {count} ingediende inzendingen zijn. De historische waardes blijven
   bestaan, maar zijn niet meer de bron-van-waarheid. Dit kan niet
   ongedaan worden gemaakt."

delete_schema_with_submissions:
  "Dit formulier heeft {count} inzendingen. Als je het verwijdert, blijven
   de inzendingen bewaard als archief maar zijn niet meer nieuw in te
   dienen. Type de naam van het formulier om te bevestigen:"

field_type_change:
  "Je wijzigt het veldtype van {old} naar {new}. Bestaande waardes worden
   mogelijk niet correct omgezet — sommige kunnen onleesbaar worden.
   Aanbevolen: maak een nieuw veld aan in plaats van dit veld te
   wijzigen."

public_token_rotation:
  "Je roteert de publieke link voor dit formulier. Bestaande gebruikers
   kunnen nog 7 dagen inzenden met de oude link; daarna krijgen ze een
   410 Gone foutmelding."

30.4 Maintenance

Copy catalogue is updated in every session that adds new UI:

Check existing terms before creating new
Propose new terms to COPY_CATALOGUE.md
Bert reviews before merge

31. [v1.2] Integration contracts

The form builder does not operate in isolation. Other modules produce or consume form submissions, and these interactions must be contract-defined to prevent ad-hoc coupling.

31.1 Person Identity Matching integration

Trigger: FormSubmissionSubmitted event where form_schema.purpose == 'event_registration' and submission is public OR the submitter's user_id is not already linked to a person.

Listener: TriggerIdentityMatchOnRegistration

Contract:

Input: FormSubmission with subject_type=person (or null for public pre-
       submission).
Behaviour: Call PersonIdentityService::detectMatches($person) per
           existing logic. Service creates person_identity_matches rows
           with status=pending.
           Does NOT auto-confirm. Auto-linking is explicitly forbidden —
           organiser must confirm.
Output: No direct return. Side-effect: potential person_identity_matches
        rows.

Failure mode: if PersonIdentityService throws, listener logs at error level and does NOT fail the FormSubmission event propagation (other listeners continue).

Trigger: User account deletion (existing flow in UserController::destroy or dedicated GDPR-delete endpoint).

Contract:

Input: User about to be deleted.
Behaviour (in order):
  1. For every form_submission where subject_type='user' AND
     subject_id=that_user: call FormSubmissionAnonymisationService::anonymise
  2. For every form_submission where submitted_by_user_id=that_user
     AND subject_type != 'user' (i.e., user submitted for others or anonymous):
     clear submitted_by_user_id → null; copy user.name/email to
     public_submitter_name/public_submitter_email; set
     public_submitter_ip_anonymised_at = now().
  3. Delete user_profiles row (cascade via FK on user_id).
  4. Delete user_organisation_tags rows for this user.
  5. Anonymise activity_log entries where causer_id=that_user: replace
     causer_name with "[deleted-user]" but preserve log integrity.
Output: User fully disconnected from form-related data while audit trail
        preserved.

Transactional: all steps wrapped in DB transaction. If any step fails, rollback; user deletion is also rolled back.

GDPR export endpoint:

GET /api/v1/users/{user}/gdpr-export

Response: 200 OK with Content-Type: application/json
{
  "user": { ... core user attributes ... },
  "user_profile": { ... user_profiles row ... },
  "tags": [ ... user_organisation_tags ... ],
  "submissions": [
    {
      "schema": { "slug", "purpose", "organisation_name" },
      "values": { ... form_values keyed by field slug ... },
      "submitted_at": "...",
      "status": "..."
    }
  ]
}

Access: user themselves OR org_admin of any org the user is a member of. Format: JSON (v1). PDF export deferred.

31.3 Shift assignments integration

Trigger: FormSubmissionSubmitted where schema purpose is event_registration AND submission contains AVAILABILITY_PICKER field values.

Listener: CreateProvisionalShiftAssignmentsFromRegistration

Contract:

Input: FormSubmission with subject_type=person, AVAILABILITY_PICKER
       values (array of time_slot_id ULIDs), and optionally SECTION_PRIORITY
       values.
Behaviour:
  1. For each time_slot_id in AVAILABILITY_PICKER value:
     - Find shifts within that time_slot that match person's crowd_type
     - If person has section priorities: prefer shifts in priority sections
     - Create ShiftAssignment with status='claim_pending'
     - Do NOT auto-confirm; requires organiser approval
  2. For each SECTION_PRIORITY value: upsert row in
     person_section_preferences (existing table).
Output: ShiftAssignments in claim_pending status. Organiser sees them in
        the standard shift-assignments approval queue.

Cancellation flow: when a person submits an absence_report form (§3.2.13), the listener HandleAbsenceReport flips affected ShiftAssignment.status → cancelled with cancellation_source='volunteer_absence'.

31.4 Email notifications integration

Form-builder uses the existing CrewliMailable + email-template infrastructure (built April 2026).

Mailables used:

Event	Mailable	Template
FormSubmissionSubmitted (event_registration)	`RegistrationConfirmation`	`registration_confirmation`
FormSubmissionReviewed (approved)	`SubmissionApproved`	`submission_approved`
FormSubmissionReviewed (rejected/changes_requested)	`SubmissionNeedsAttention`	`submission_needs_attention`
FormSubmissionSubmitted (pending review)	`ReviewPending`	`review_pending`
Retention job run	`RetentionReport` (aggregated, daily)	`retention_report`
Incident report (kritiek ernst)	`CriticalIncidentAlert`	`critical_incident_alert`
Post-event evaluation trigger	`EvaluationInvitation`	`evaluation_invitation`

Contract:

All listeners use Mail::queue (not Mail::send) to avoid blocking the
event dispatch. Mailables respect org-level branding config (logo,
primary_color, sender_name, reply_to, footer_text).

Template override: orgs can override default templates via existing org-level email-template management UI.

31.5 Code-of-conduct gating integration

Trigger: any shift-claim attempt (existing endpoint POST /portal/shifts/{shift}/claim).

Check: before accepting the claim, verify:

Does a form_submission exist where
  form_schema.purpose = 'signature_code_of_conduct' AND
  subject_type = 'person' AND
  subject_id = claimer_person_id AND
  status = 'submitted' AND
  form_schema.organisation_id = current_organisation_id ?

If NO: reject claim with 422 "Je moet eerst de gedragscode tekenen". Response includes link to the code-of-conduct form URL.

If YES: accept claim.

Implementation: in ShiftClaimService::canClaim().

31.6 Supplier intake / production_requests integration

Trigger: organiser creates a production_requests row (existing infrastructure) with company_id and selects a form_schema of purpose supplier_intake.

Behaviour:

form_schema's public_token is created/reused
production_request.token is generated (existing logic)
Supplier receives email with URL combining both tokens: {APP_URL}/f/{public_token}?pr={production_request.token}
When supplier opens URL: both tokens validated, submission created with subject_type=company, subject_id=production_request.company_id

31.7 Accreditation engine integration (ARCH-07, future)

Reserved contract for when accreditation engine lands:

When signature_receipt submissions are created: attached accreditation items from ARCH-07's accreditation_items are listed in the submission as pre-filled TABLE_ROWS values
When check_out_inventory submissions are reviewed as complete: accreditation_item.returned_at is updated per item

Exact contract TBD when ARCH-07 implementation starts. v1.2 leaves the hooks in place (purpose enum values exist, no code integration yet).

31.8 Crowd list integration

Trigger: FormSubmissionSubmitted where purpose=event_registration AND submission results in a new Person being created.

Listener: AddPersonToApplicableCrowdListsOnRegistration

Contract:

Input: FormSubmission with subject_type=person (new person).
Behaviour:
  1. Fetch crowd_lists where organisation_id matches AND
     crowd_list.auto_add_criteria matches the new person (e.g.,
     crowd_type matches).
  2. For each matching crowd_list: add person via existing
     CrowdListService::addPerson.
  3. Crowd_lists without auto_add_criteria are ignored (manual
     management).
Output: person_crowd_list pivot rows for applicable lists.

Crewli Context: Crowd lists are optional organizational tools, not mandatory gatekeepers. Not every registration needs a crowd list membership.

31.9 Integration contract tests

Every contract in §31.1-31.8 has a corresponding integration test in tests/Feature/FormBuilder/Integration/:

IdentityMatchTriggerTest
GdprDeleteCascadeTest
ShiftAssignmentFromRegistrationTest
EmailNotificationFlowTest
CodeOfConductGatingTest
SupplierIntakeFlowTest
CrowdListAutoAddTest

Tests are part of CI. Contract changes require test updates (and this ARCH section update) before merge.

End of ARCH v1.2

Refactor completion checklist (updated at end of S6):

All migrations applied in dev
All 431 existing tests green + ≥200 new tests
Migration rehearsal passed
Real migration run successful
All 22 FormPurposes seed-tested
All integration contracts (§31) tested
VitePress documentation complete per §29
SCHEMA.md updated to reflect final state
Pre-flight audit removed from session prompts
This document marked "refactor complete"

When complete: add a "Refactor complete — effective {DATE}" banner at top of this document. Pre-flight audit gate (§21) becomes optional.

111 KiB Raw Blame History Unescape Escape

ARCH — Universal Form Builder (v1.2)

0. TL;DR — What every session must know

[v1.2 addition] Three more principles:

Table of contents

1. Rationale

2. Four form patterns

3. FormPurpose catalogue

3.1 Enum values summary

3.2 [v1.2] Per-purpose lifecycles

3.2.1 event_registration

3.2.2 user_profile

3.2.3 artist_profile

3.2.4 company_profile

3.2.5 artist_advance

3.2.6 supplier_intake

3.2.7 incident_report

3.2.8 feedback

3.2.9 post_event_evaluation

3.2.10 signature_contract

3.2.11 signature_code_of_conduct

3.2.12 signature_receipt

3.2.13 absence_report

3.2.14 check_out_inventory

3.2.15 public_complaint

3.2.16 public_press_request

3.2.17 public_rsvp

3.2.18 onboarding_wizard

3.2.19 event_setup_wizard

3.2.20 company_custom

3.2.21 artist_custom

3.2.22 custom

4. Core tables

4.1 form_schemas

4.2 form_fields

4.2.1 [v1.2] is_unique enforcement

4.3 form_submissions

4.4 form_values

4.5 form_value_options (filter pivot for multi-value fields)

4.6 form_templates

4.6.1 [v1.2] schema_snapshot JSON structure

4.7 form_field_library (cross-schema reusable definitions)

4.8 form_schema_sections (for section-level submit)

4.8.1 [v1.2] Cycle detection

4.9 form_submission_section_statuses

4.10 form_submission_delegations

4.11 form_schema_webhooks

4.12 form_webhook_deliveries

4.13 user_profiles (renamed from legacy volunteer_profiles, slimmed)

4.13.1 [v1.2] settings scope enforcement

5. FormFieldType catalogue

5.1 Built-in types

5.2 [v1.2] Mapping to value_storage_hint

6. Field binding

6.1 The three patterns

6.2 Entity column registry

6.3 Binding JSON specification

6.4 Read/write semantics per pattern

6.5 Binding-change safety

6.6 Cross-entity binding

7. Filter architecture

7.1 Filter strategy per field type

7.2 Observer mechanics

7.3 Filter registry endpoint

7.4 [v1.2] Filter registry — entity column sources

7.5 Applying filters in list endpoints

7.6 Organiser UX

8. Conditional logic

9. Signature field

9.1 [v1.2] Storage disk configuration

9.2 [v1.2] Signature verification

10. Public token flow

10.1 [v1.2] Captcha provider

10.2 [v1.2] Rate limit storage

10.3 [v1.2] public_submitter_ip retention

11. Migration plan

11.1 Migration order

11.2 Data migration script

11.2.1 [v1.2] PII heuristic

11.3 Rollback

111 KiB

Raw Blame History

3.2.1 `event_registration`

3.2.2 `user_profile`

3.2.3 `artist_profile`

3.2.4 `company_profile`

3.2.5 `artist_advance`

3.2.6 `supplier_intake`

3.2.7 `incident_report`

3.2.8 `feedback`

3.2.9 `post_event_evaluation`

3.2.10 `signature_contract`

3.2.11 `signature_code_of_conduct`

3.2.12 `signature_receipt`

3.2.13 `absence_report`

3.2.14 `check_out_inventory`

3.2.15 `public_complaint`

3.2.16 `public_press_request`

3.2.17 `public_rsvp`

3.2.18 `onboarding_wizard`

3.2.19 `event_setup_wizard`

3.2.20 `company_custom`

3.2.21 `artist_custom`

3.2.22 `custom`

4.1 `form_schemas`

4.2 `form_fields`

4.2.1 [v1.2] `is_unique` enforcement

4.3 `form_submissions`

4.4 `form_values`

4.5 `form_value_options` (filter pivot for multi-value fields)

4.6 `form_templates`

4.6.1 [v1.2] `schema_snapshot` JSON structure

4.7 `form_field_library` (cross-schema reusable definitions)

4.8 `form_schema_sections` (for section-level submit)

4.9 `form_submission_section_statuses`

4.10 `form_submission_delegations`

4.11 `form_schema_webhooks`

4.12 `form_webhook_deliveries`

4.13 `user_profiles` (renamed from legacy volunteer_profiles, slimmed)

4.13.1 [v1.2] `settings` scope enforcement

14.1 `form_schemas.version`

14.2 `form_schemas.snapshot_mode` + `form_submissions.schema_snapshot`

14.3 `form_schemas.freeze_on_submit`