Skip to main content
Purpose: Help developers and AI agents choose the correct wizard system for their use case. Last Updated: 2026-04-14

​
Quick Decision

​
Decision Tree

​
Detailed Comparison

​
Form Wizard (FW-31)

What it is: Multi-step mode for FW-01 forms with guided progression, step validation, and draft persistence. Best for:
  • ✅ Multi-page surveys with conditional sections
  • ✅ Intake forms with step-by-step data collection
  • ✅ Assessments that need progress tracking
  • ✅ Forms where all steps are standard form fields
Data storage: fw_form_submissions table Key features:
  • Extends existing FW-01 multi-page forms
  • Step-level validation before advancing
  • Progress tracking with visual indicator
  • Auto-save drafts on step transition
  • Conditional step visibility based on prior answers
Example use cases:
  • Resident intake wizard (collect demographics → medical → emergency contacts)
  • Employee satisfaction survey (multiple sections)
  • Compliance assessment (step through requirements)
  • Application forms (personal → education → experience)
How to create:
  1. Create a multi-page form in FW-01
  2. Enable wizard mode in form settings (wizard_config)
  3. Configure step validation and visibility conditions

​
Module Wizard (PF-41)

What it is: Configurable business process wizard with custom step components, stored in pf_wizard_templates. Best for:
  • ✅ Employee onboarding (creates employee, credentials, access)
  • ✅ Resident admission (creates resident record, bed assignment, intake docs)
  • ✅ Payroll runs (validates, calculates, approves, submits)
  • ✅ Any process that creates records in multiple module tables
Data storage: Module-specific tables (e.g., hr_onboarding_instances, rh_admissions) Key features:
  • Custom React components for complex steps
  • Organization-customizable wizard templates
  • System templates with cloning support
  • Step registry per module
  • Cross-module wizard support (Phase 3)
  • Wizard marketplace for sharing templates
Example use cases:
  • Employee onboarding (HR module) - creates employee, credentials, system access
  • Resident admission (RH module) - creates resident, assigns bed, generates intake forms
  • Payroll run (HR module) - validates data, calculates, gets approval, submits
  • Organization setup (PF) - configures org settings, creates admin, enables modules
How to create:
  1. Create wizard template in pf_wizard_templates
  2. Register custom step components in module step registry
  3. Create wizard page using ModuleWizardRenderer

​
Side-by-Side Comparison

​
Common Mistakes

​
❌ Using Form Wizard for Business Processes

Wrong: Creating an FW-31 form wizard for employee onboarding Problem:
  • Data goes to fw_form_submissions, not HR tables
  • Can’t create employee records, credentials, system access
  • No custom components for complex steps
Solution: Use Module Wizard (PF-41)

​
❌ Using Module Wizard for Simple Data Capture

Wrong: Building a PF-41 wizard for a satisfaction survey Problem:
  • Overkill for simple form data
  • Requires custom step component registration
  • Data needs to go to form submissions anyway
Solution: Use Form Wizard (FW-31)

​
❌ Building Custom Wizard Instead of Using Platform

Wrong: Creating a custom wizard component from scratch Problem:
  • Duplicates existing infrastructure
  • Misses draft persistence, validation, progress tracking
  • No organization customization support
Solution: Use FW-31 or PF-41 based on your needs

​
Integration Points

​
Form Wizard (FW-31) integrates with:

  • FW-01 (Form Builder) - Base form infrastructure
  • FW-05 (Multi-Page Forms) - Page structure
  • FW-15 (Lookups) - Dynamic dropdowns
  • PF-10 (Notifications) - Resume email

​
Module Wizard (PF-41) integrates with:

  • PF-01 (Organizations) - Multi-tenant scoping
  • PF-02 (RBAC) - Permission checks
  • Module step registries - Custom components
  • Module data tables - Record creation

​
Shell Selection (After Choosing FW-31 or PF-41)

Once you’ve decided on FW-31 or PF-41, choose the rendering shell:

​
Shell Decision Tree

​
Shell Quick Reference

​
Step Icons

All wizard steps SHOULD include a Lucide icon. For WizardShell, pass components directly via step.icon. For PF-41 templates, use string keys from WIZARD_STEP_ICONS and resolve with resolveStepIcon() from @/platform/wizards. Common assignments: user (personal info), mail (contact), calendar (schedule), briefcase (employment), wallet (payment), file-text (documents), shield-check (credentials), review (review/summary), complete (success).

​
Validation Pattern Selection

Use one validation pattern per wizard (do not mix):
  • ModuleWizardRenderer template steps: PF-41 validation.rules.
  • registerWizardStep custom steps: StepComponentProps (onValidate) for new code.
  • WizardShell / DialogWizardShell: step-local react-hook-form validation before onNext.

​
Step Naming Conventions

Prefer these standard titles for consistency: Personal Information, Contact Information, Employment Details, Schedule, Payment Information, Documents, Credentials, Consent & Agreements, Configuration, Review & Submit, Complete. When a flow needs domain-specific wording, keep semantic intent equivalent (for example, Position & Department or Review & Finalize).
Last Updated: 2026-05-13