Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Quick Decision

I need to…Use ThisSpec
Create a multi-step data capture formForm Wizard (FW-31)FW-31
Build a business process (onboarding, payroll)Module Wizard (PF-41)PF-41

​
Decision Tree

I need a multi-step guided experience:
│
├─ Is it primarily for DATA CAPTURE?
│   │
│   ├─ YES: Does data go to form submissions?
│   │   │
│   │   ├─ YES → Use Form Wizard (FW-31)
│   │   │   └─ Enable wizard mode on a multi-page form
│   │   │
│   │   └─ NO: Does data go to module-specific tables?
│   │       │
│   │       └─ YES → Use Module Wizard (PF-41)
│   │
│   └─ NO: Is it a BUSINESS PROCESS?
│       │
│       ├─ YES: Does it need custom React components?
│       │   │
│       │   ├─ YES → Use Module Wizard (PF-41)
│       │   │
│       │   └─ NO: Can it be done with form fields only?
│       │       │
│       │       └─ YES → Use Form Wizard (FW-31)
│       │
│       └─ NO → Probably not a wizard use case

​
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

AspectForm Wizard (FW-31)Module Wizard (PF-41)
Primary PurposeData captureBusiness process
Data Destinationfw_form_submissionsModule-specific tables
Step TypesForm fields onlyForm, Custom, Review
Custom Components❌ Not supported✅ Per-module registry
Org CustomizationField configurationFull step customization
Draft Storagewizard_progress JSONBModule execution tables
Template SystemForm templates (FW-01)pf_wizard_templates
Marketplace❌ Not supported✅ Phase 3

​
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

Using PF-41 (Module Wizard)?
│
├─ Is this actually parallel tab navigation (non-sequential)?
│   └─ Not a wizard — use tabs/segmented controls
│
├─ Should orgs customize steps via template builder?
│   └─ ModuleWizardRenderer (data-driven from pf_wizard_templates)
│
├─ Steps are hardcoded (regulatory, tightly coupled)?
│   ├─ 5+ steps, complex layout → WizardShell layout="timeline" or "sidebar"
│   ├─ 3-5 simple steps → WizardShell layout="horizontal"
│   └─ Dialog flow (≤4 steps) → DialogWizardShell
│
└─ Hybrid (some customizable, some custom components)?
    └─ ModuleWizardRenderer + registerWizardStep()

​
Shell Quick Reference

ShellWhenLayout
WizardShell layout="horizontal"3-5 step full-page wizardSticky header stepper
WizardShell layout="timeline"5+ steps, complex flowsVertical timeline sidebar
WizardShell layout="sidebar"Data-heavy operational wizardsFull sidebar with progress
DialogWizardShellShort creation/entry flowsDialog with horizontal stepper
ModuleWizardRendererTemplate-driven configurableAuto-selects layout from config

​
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