crewli/dev-docs/ARCH-FORM-BUILDER.md

# 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:

1. **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.
2. **Four patterns:** entity-bound, submission-bound, event-registration,
   public. Every schema matches one.
3. **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).
4. **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.
5. **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.
6. **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`.
7. **Governance is built-in.** Retention policies, PII-flagging, consent
   versioning, right-to-be-forgotten workflow with anonymisation.
8. **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.
9. **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.
10. **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:

11. **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.
12. **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.
13. **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.

---

## Table of contents

1. Rationale
2. Four form patterns
3. FormPurpose catalogue
   - 3.1 Enum values summary
   - 3.2 [v1.2] Per-purpose lifecycles
4. Core tables
5. FormFieldType catalogue
6. Field binding
7. Filter architecture
8. Conditional logic
9. Signature field details
10. Public token flow
11. Migration plan
12. Seeding strategy
13. Governance & compliance
14. Schema lifecycle & versioning
15. Workflows & submission reviews
16. Internationalisation
17. Extensibility & integrations (webhooks, custom field types, custom purposes)
18. Consistency & interaction rules
19. Self-hosting principle ("eat your own dog food")
20. Trade-offs & cost awareness
21. Pre-flight audit gate
22. Failure-mode resilience
23. Observability & analytics hooks
24. Access control per field
25. Self-hosting reservations (FormPurpose slots)
26. Open questions / deferred decisions
27. Out of scope
28. [v1.2] User guidance principles
29. [v1.2] Documentation coverage requirements per session
30. [v1.2] In-app copy catalogue (living seed)
31. [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:**
1. Person opens the registration form (authenticated or via public URL)
2. `FormSubmission.opened_at` = now; status = draft
3. Fields rendered per conditional_logic + role_restrictions
4. On submit: FormSubmissionSubmitted event fires
5. Integration: PersonIdentityService invoked (see §31.1) to detect match
6. Integration: if form contains AVAILABILITY_PICKER values, shift_assignments
   are provisionally created at status=claim_pending (see §31.3)
7. Integration: if form contains SECTION_PRIORITY values, preferences are
   stored in `person_section_preferences` (existing table)
8. 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:**
1. User opens profile; submission created on-demand if not exists
2. All fields are Pattern A (entity-owned → user_profiles columns)
3. User edits; on save, `updateOrCreate` on user_profiles
4. FormSubmissionSubmitted fires on any update
5. 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:**
1. Submission created when artist is created in system
2. Organisers fill/update artist profile fields
3. Public flow: artist clicks portal_token link, sees profile form
4. On save, entity updates (Pattern A for most fields)
5. 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:**
1. Artist receives email with portal link (triggered by organiser)
2. Opens link → token resolved, submission fetched or created
3. Form shown with sections: General Info, Contacts, Production (power,
   catering, transport), Technical Rider, Hospitality
4. Artist fills sections independently; each section submit separately
5. On section submit: FormSubmissionSectionSubmitted event fires
6. Organiser reviews per section → section status approved/rejected/
   changes_requested
7. When all sections approved: FormSubmissionSubmitted fires at submission level
8. 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:**
1. User accesses via "Rapporteer incident" link in portal (event-scoped)
2. Submission has subject_type=user (submitter), event context in metadata
3. `freeze_on_submit=true` — once submitted, cannot be edited (integrity)
4. Organiser reviews via incident dashboard; review_status workflow applies
5. Integration: critical incidents notify org_admins via CrewliMailable
6. `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:**
1. Organiser clicks "Verstuur evaluatie" in event dashboard
2. Emails sent to all approved persons (see §31.4)
3. Person clicks link, fills form
4. On submit: FormSubmissionSubmitted fires
5. 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:**
1. Schema contains PARAGRAPH with contract text + SIGNATURE field
2. On submit: signature hashed (§9), stored
3. submission locked (`freeze_on_submit=true` enforced)
4. 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:**
1. Person clicks "Ik kan toch niet komen" on shift detail
2. Form opens, subject = person
3. Fields: reason (SELECT), notes (TEXTAREA), affected_shifts (AVAILABILITY_PICKER
   showing their assigned shifts)
4. On submit: for each affected shift, ShiftAssignment.status → cancelled with
   cancellation_source="volunteer_absence"
5. 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:

```json
{
  "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`:

```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`:

```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

```json
// 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:
```json
{
  "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`:

```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:

```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:

```json
{
  "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:
```json
"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`:

```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

1. 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
2. Rename: `registration_form_fields` → `form_fields`; add form_schema_id
   (nullable), keep event_id temporarily
3. Rename: `person_field_values` → `form_values`; add form_submission_id
   (nullable), keep person_id + registration_form_field_id temporarily
4. Rename: `registration_field_templates` → `form_templates`
5. Run data-migration script (§11.2)
6. Drop legacy columns: form_fields.event_id, form_values.person_id,
   form_values.registration_form_field_id
7. 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:

```php
$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:
1. Take a full dump of dev DB
2. Run migration on a copy
3. Run comparison script: per organisation, compare pre/post counts and
   sample 10 random submissions, assert identical rendering
4. If any mismatch: stop, investigate
5. 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)

### 13.4 Right-to-be-forgotten workflow (GDPR)

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

1. All `form_submissions` where `subject_type = 'user'` AND
   `subject_id = that_user` are anonymised
2. All `form_submissions` where `submitted_by_user_id = that_user`:
   `submitted_by_user_id` → null; name/email copied to
   public_submitter_* before clearing
3. `user_profiles` row deleted (cascade via FK)
4. `user_organisation_tags` for that user deleted
5. 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.

### 13.5 Consent tracking

`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:
```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:
1. `submitter.locale` (if submitter is authenticated)
2. Explicit locale passed in request (via `Accept-Language` header)
3. `form_schemas.locale` (schema's primary locale)
4. 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:
1. `users.timezone` (if authenticated)
2. `organisation.timezone`
3. 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:

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

Each handler implements `CustomFieldTypeHandler` interface:

```php
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:
```json
{
  "callback": "App\\Services\\Validators\\KvkValidator@validate"
}
```

Registered callbacks in `config/form_builder.php`:
```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

```json
{
  "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:

```bash
# 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`:
```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:

```php
// 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:

```json
{
  "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

```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

```php
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:
1. What will happen (list)
2. How many records affected
3. Whether action is reversible (and how)
4. 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 |

### 30.2 Tooltip catalogue (selection)

```
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).

### 31.2 GDPR delete workflow integration

**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.

### 31.10 Tag sync integration (BACKLOG FORM-02)

Replaces the S1-era `TagSyncService` that read the legacy
`person_field_values` table. Purged in S2a; rebuilt in S2b/S2c against
the new FormBuilder.

**Trigger:** `FormSubmissionSubmitted` event (ARCH §17.1) OR explicit
call from `PersonController::approve()` after status transitions to
`approved`.

**Listener:** `SyncTagPickerValuesToUserTagsListener` — for the given
submission, finds all `form_values` whose field has
`field_type=TAG_PICKER`, and upserts rows into `user_organisation_tags`
with `source=self_reported`, respecting `person.user_id` (skip if null).
Only syncs to the subject person's user account.

**Failure mode:** log at warning level; never throws into the submission
lifecycle. Reason: a tag-sync failure must not block registration.

**Call site removed in S2a:** `PersonController::approve()` and
`PersonIdentityService::syncRegistrationTags()` used to call
`TagSyncService::syncFromRegistration($person)` directly. The rebuilt
flow is listener-driven — no direct service injection required.

---

## 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.