Forms

Dynamic form system (Form Builder v3) for creating, configuring, and submitting forms. Admins design forms with conditional logic and field triggers; customers fill them via the Portal; submissions are stored and reviewed internally.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Form Routes	backend/src/routes/admin/forms/
Field Routes	backend/src/routes/admin/form-fields/
Submission Routes	backend/src/routes/form-submissions.ts
Builder Page	frontend/src/pages/admin/FormBuilder.tsx
Forms Admin	frontend/src/pages/admin/FormsAdmin.tsx
Fields Admin	frontend/src/pages/admin/FormFieldsAdmin.tsx
Components	frontend/src/components/form-builder/ (29 files)
Context	frontend/src/contexts/FormBuilderContext.tsx

Database Tables

Table	Purpose
forms	Main entity — name, description, status, version
formFieldDefinitions	Reusable field definitions (type, validation rules, options)
formFieldSections	Logical groupings of fields within a form
formToFormFields	M2M linking forms to field definitions with ordering and config
formToSections	M2M linking forms to sections with ordering
formSubmissions	Completed form submissions with response data

Form Builder Architecture

The Form Builder v3 uses a drag-and-drop editor with three panels:

Panel	Component	Purpose
Sidebar	FormBuilderSidebar	Field palette and section list
Editor	FormBuilderEditor	Canvas for arranging fields and sections
Config	FieldConfigPanel	Properties, validation, and conditions for selected field
Preview	FormBuilderPreview	Live preview of the form as customers see it

State is managed via FormBuilderContext — a React context holding the current form structure, selection state, and undo history.

Key Features

• Conditional visibility — fields can be shown/hidden based on other field values via a condition editor
• Trigger system — field interactions can trigger side effects (e.g., auto-fill, show warning)
• Field types — text, number, date, select, multi-select, file upload, checkbox, radio, rich text, signature
• Sections — fields are grouped into collapsible sections for organization
• Reusable fields — formFieldDefinitions can be shared across multiple forms
• Submissions — responses stored in formSubmissions, viewable in admin

Frontend Components

Component	Purpose
FormRenderer	Renders a form for end-user filling (used in Portal)
ConditionEditor	Visual editor for field visibility conditions
TriggerEditor	Configure field interaction triggers
FieldTypeSelector	Picker for available field types
SectionManager	Add, reorder, and configure sections
FormPreviewDialog	Full-screen preview of the form

Relationships

Form 1──* FormToFormFields ──* FormFieldDefinitions
Form 1──* FormToSections ──* FormFieldSections
Form 1──* FormSubmissions
FormSubmission *──1 Users (submitter)
FormSubmission *──* Files (uploaded attachments)

Integration Points

• Document Obtaining — forms define what information customers must provide for specific document types
• Portal — FormRenderer is the primary way customers interact with forms
• Files — file upload fields store attachments via the file system
• Validation Pattern — form field validation uses Zod schemas generated from field definitions

Related Pages

Form Builder | Document Obtaining | Portal | Files | Validation Pattern | Admin Dashboard | Service Layer Pattern | React Query Pattern