Encore OS — Documentation

Purpose: Comprehensive comparison of all data management features to help choose the right tool for each scenario. Last Updated: 2026-02-01

See Also: TERMINOLOGY.md for full glossary including wizards and templates.

Master Comparison Matrix

Feature	Purpose	Storage	Scope	Use When
Picklists (PF-15)	Reusable dropdown values	`pf_picklists` + `pf_picklist_items`	Organization	Values used across multiple forms/entities
Custom Fields (PF-16)	Extend existing entity schemas	`{table}.custom_fields` JSONB	Organization + Entity	Adding metadata to existing entities
Field Configuration (PF-17)	Control field behavior	`pf_entity_field_configs`	Organization + Entity + Context	Visibility, required rules, ordering
Object Browser (PF-23)	Discover and manage objects	`pf_object_metadata`	Organization	Browse, categorize, favorite objects
Custom Objects (PF-24)	Create new entity types	`pf_custom_objects` + `pf_custom_object_records`	Organization	New entities with CRUD operations
Raw Data Editor (PF-25)	Browse and edit records	Core tables	Organization	View records, edit custom fields, export CSV
Form Builder (FW-01)	Data capture interfaces	`fw_forms` + `fw_form_submissions`	Organization	One-time data capture, workflows
Lookups (FW-15)	Dynamic dropdown from tables	Database tables	Database	Dropdown values from existing data
Form Wizards (FW-31)	Multi-step data capture	`fw_forms.wizard_config`	Organization	Guided form completion with steps
Module Wizards (PF-41)	Business process guidance	`pf_wizard_templates`	Organization	Onboarding, payroll, admissions
Workflow Templates (FW-28)	Reusable automation	`fw_workflow_templates`	Organization	Shareable workflow patterns
Document Templates (PF-64)	Printable PDFs	`pf_document_templates`	Organization	Policies, letters, reports

Feature Relationship Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Encore OS Data Architecture                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      VALUE PROVIDERS                                 │   │
│  │                                                                      │   │
│  │  ┌───────────────┐              ┌───────────────┐                   │   │
│  │  │  Picklists    │              │   Lookups     │                   │   │
│  │  │   (PF-15)     │              │   (FW-15)     │                   │   │
│  │  │               │              │               │                   │   │
│  │  │ Static        │              │ Dynamic       │                   │   │
│  │  │ dropdown      │              │ dropdown      │                   │   │
│  │  │ values        │              │ from tables   │                   │   │
│  │  └───────┬───────┘              └───────┬───────┘                   │   │
│  │          │                              │                            │   │
│  └──────────┼──────────────────────────────┼────────────────────────────┘   │
│             │ provides options to          │                                │
│             ▼                              ▼                                │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      SCHEMA EXTENDERS                                │   │
│  │                                                                      │   │
│  │  ┌───────────────┐              ┌───────────────┐                   │   │
│  │  │ Custom Fields │              │ Custom Objects│                   │   │
│  │  │    (PF-16)    │              │    (PF-24)    │                   │   │
│  │  │               │              │               │                   │   │
│  │  │ Extend        │              │ Create new    │                   │   │
│  │  │ existing      │              │ entity types  │                   │   │
│  │  │ entities      │              │               │                   │   │
│  │  └───────┬───────┘              └───────┬───────┘                   │   │
│  │          │                              │                            │   │
│  └──────────┼──────────────────────────────┼────────────────────────────┘   │
│             │ configured by                │ managed by                     │
│             ▼                              ▼                                │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      BEHAVIOR CONTROLLERS                            │   │
│  │                                                                      │   │
│  │  ┌───────────────┐              ┌───────────────┐                   │   │
│  │  │ Field Config  │              │ Object Browser│                   │   │
│  │  │    (PF-17)    │              │    (PF-23)    │                   │   │
│  │  │               │              │               │                   │   │
│  │  │ Visibility,   │              │ Discover,     │                   │   │
│  │  │ required,     │              │ categorize,   │                   │   │
│  │  │ ordering      │              │ favorite      │                   │   │
│  │  └───────────────┘              └───────────────┘                   │   │
│  │                                                                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      DATA INTERFACES                                 │   │
│  │                                                                      │   │
│  │  ┌───────────────┐              ┌───────────────┐                   │   │
│  │  │ Form Builder  │              │ Raw Data      │                   │   │
│  │  │    (FW-01)    │              │ Editor(PF-25) │                   │   │
│  │  │               │              │               │                   │   │
│  │  │ Data capture  │              │ Browse, edit, │                   │   │
│  │  │ interfaces    │              │ export data   │                   │   │
│  │  └───────────────┘              └───────────────┘                   │   │
│  │                                                                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Master Decision Tree

I need to work with data
│
├─► I need DROPDOWN OPTIONS
│   │
│   ├─ Used across multiple forms/entities?
│   │   ├─ Yes → From database table?
│   │   │   ├─ Yes → Use Lookups (FW-15)
│   │   │   └─ No  → Organization-specific?
│   │   │       ├─ Yes → Use Picklists (PF-15)
│   │   │       └─ No  → Use TypeScript Enum
│   │   └─ No → Use Form Options (FW-01)
│   │
├─► I need to ADD A FIELD
│   │
│   ├─ To existing entity?
│   │   ├─ Yes → Organization-specific metadata?
│   │   │   ├─ Yes → Frequently queried?
│   │   │   │   ├─ Yes → Use proper DB column
│   │   │   │   └─ No  → Use Custom Fields (PF-16)
│   │   │   └─ No → Use proper DB column
│   │   └─ No → Creating form?
│   │       ├─ Yes → Use Form Builder (FW-01)
│   │       └─ No  → Use Custom Objects (PF-24)
│   │
├─► I need to CONTROL A FIELD
│   │
│   ├─ Control visibility by role?
│   │   └─ Yes → Use Field Configuration (PF-17)
│   ├─ Make field conditionally required?
│   │   └─ Yes → Use Field Configuration (PF-17)
│   ├─ Change field order in forms?
│   │   └─ Yes → Use Field Configuration (PF-17)
│   └─ Create form layout?
│       └─ Yes → Use Form Builder (FW-01)
│   │
├─► I need to CREATE NEW ENTITY
│   │
│   ├─ Track multiple records over time?
│   │   ├─ Yes → Need CRUD operations?
│   │   │   ├─ Yes → Use Custom Objects (PF-24)
│   │   │   └─ No  → Use Forms (FW-01)
│   │   └─ No → One-time data capture?
│   │       └─ Yes → Use Forms (FW-01)
│   │
├─► I need to BROWSE/MANAGE DATA
│   │
│   ├─ Discover available objects?
│   │   └─ Yes → Use Object Browser (PF-23)
│   ├─ View/edit records?
│   │   └─ Yes → Use Raw Data Editor (PF-25)
│   └─ Export to CSV?
│       └─ Yes → Use Raw Data Editor (PF-25)
│   │
└─► I need to CAPTURE DATA
    │
    ├─ One-time submission?
    │   └─ Yes → Use Form Builder (FW-01)
    ├─ With workflow?
    │   └─ Yes → Use Form Builder (FW-01)
    └─ Directly into entity?
        └─ Use module-specific forms or Raw Data Editor

Detailed Feature Comparisons

Picklists vs Lookups vs Form Options

Aspect	Picklists (PF-15)	Lookups (FW-15)	Form Options (FW-01)
Data Source	`pf_picklist_items`	Database tables	Form definition
Scope	Organization	Database/RLS	Single form
Management	Settings UI	Automatic	Form Builder
Reusable	✅ Yes	✅ Yes	❌ No
Dynamic	❌ Static	✅ Real-time	❌ Static
Example	Employment status	Departments list	Yes/No question

Custom Fields vs Custom Objects

Aspect	Custom Fields (PF-16)	Custom Objects (PF-24)
Purpose	Extend existing entity	Create new entity
Storage	JSONB column on entity	Separate table
Records	1:1 with entity	Independent records
CRUD	Via entity	Full CRUD
Example	Badge number on employee	Clinical licenses

Forms vs Custom Objects

Aspect	Forms (FW-01)	Custom Objects (PF-24)
Purpose	Data capture	Entity management
Data Model	Form → Submissions	Object → Records
Lifecycle	Submit once	CRUD operations
Workflow	✅ Built-in	❌ Manual
Example	Intake form	License tracking

Field Configuration vs Form Builder

Aspect	Field Configuration (PF-17)	Form Builder (FW-01)
Purpose	Control field behavior	Build data capture forms
Scope	Entity fields	Form-specific fields
Visibility	Role-based	Everyone
Required	Context-based	Fixed
Example	Hide salary from staff	Create intake form

Common Scenarios Quick Reference

→ Picklist (PF-15) - Reusable across forms/entities → Lookup (FW-15) - Dynamic from hr_departments table

”I need Yes/No in this form only”

→ Form Options (FW-01) - Form-specific static options

”I need to add badge number to employees”

→ Custom Fields (PF-16) - Extend hr_employees

”I need to track clinical licenses”

→ Custom Objects (PF-24) - New entity type

”I need to hide salary from non-admins”

→ Field Configuration (PF-17) - Role-based visibility

”I need to create an intake form”

→ Form Builder (FW-01) - Data capture with workflow

”I need to see all employees and export to CSV”

→ Raw Data Editor (PF-25) - Browse and export

”I need to find what objects exist”

→ Object Browser (PF-23) - Discover and categorize

Wizard Comparison

Form Wizard vs Module Wizard

Aspect	Form Wizard (FW-31)	Module Wizard (PF-41)
Purpose	Multi-step data capture	Business process guidance
Data Storage	`fw_form_submissions`	Module-specific tables
Step Types	Form fields only	Form, Custom, Review
Customization	Field configuration	Full step customization
Use Case	Surveys, intake forms	Onboarding, payroll

When to Use Each Wizard

Use Form Wizard (FW-31) when:

You have a multi-page form that needs guided progression
Data should go to form submissions table
All steps are form fields (no custom components)
Example: Resident intake, satisfaction survey

Use Module Wizard (PF-41) when:

You’re building a business process (onboarding, payroll)
Data should go to module-specific tables
Steps need custom React components
Organizations need to customize the wizard flow
Example: Employee onboarding, resident admission

Template Comparison

Template Types

Template Type	Spec	Purpose	Storage	Use Case
Workflow Templates	FW-28	Automation patterns	`fw_workflow_templates`	Reusable workflows
Document Templates	PF-64	Printable PDFs	`pf_document_templates`	Policies, letters
Form Templates	FW-01	Clonable forms	`fw_forms`	Form patterns
Wizard Templates	PF-41	Business wizards	`pf_wizard_templates`	Onboarding wizards
Spec Templates	-	Documentation	`specs/_templates/`	Writing specs

When to Use Each Template Type

I need a reusable template for:
│
├─ Automating workflows?
│   └─ Workflow Template (FW-28)
│
├─ Generating printable documents?
│   └─ Document Template (PF-64)
│
├─ Creating reusable form structures?
│   └─ Form Template (FW-01)
│
├─ Business process wizards?
│   └─ Wizard Template (PF-41)
│
└─ Writing specifications?
    └─ Spec Template (specs/_templates/)

Anti-Patterns to Avoid

❌ Using Picklists for Database Table Data

Problem: Creating picklist for departments when hr_departments exists
Solution: Use Lookups (FW-15)

❌ Using Custom Objects for Entity Extension

Problem: Creating custom object to add badge number to employees
Solution: Use Custom Fields (PF-16)

❌ Using Custom Objects for Forms

Problem: Creating custom object for intake form
Solution: Use Form Builder (FW-01)

❌ Using Custom Fields for New Entities

Problem: Adding “license_number” custom field when you need license tracking
Solution: Use Custom Objects (PF-24)

❌ Using Form Builder for Entity Extension

Problem: Creating form to capture employee badge number
Solution: Use Custom Fields (PF-16) + entity form

❌ Using Field Configuration to Add Fields

Problem: Trying to add new field via field configuration
Solution: Use Custom Fields (PF-16) first, then configure

❌ Using Form Wizard for Business Processes

Problem: Using FW-31 form wizard for employee onboarding
Solution: Use Module Wizard (PF-41) - data needs to go to HR tables

❌ Using Module Wizard for Data Capture

Problem: Using PF-41 wizard for a survey or intake form
Solution: Use Form Wizard (FW-31) - simpler, data goes to form submissions

❌ Using Workflow Template for Documents

Problem: Creating workflow template to generate PDF letters
Solution: Use Document Template (PF-64) for printable documents

❌ Using Document Template for Automation

Problem: Trying to automate approval flow with document template
Solution: Use Workflow Template (FW-28) for automation patterns

Integration Patterns

Pattern 1: Picklist → Custom Field → Field Config

Create Picklist (PF-15): employee_shirt_sizes
Create Custom Field (PF-16): shirt_size → uses picklist
Configure Visibility (PF-17): visible to HR only

Pattern 2: Custom Object → Form Reference

Create Custom Object (PF-24): Clinical Licenses
Create Form (FW-01): License Renewal Form
Add Lookup Field (FW-15): → pf_custom_object_records

Pattern 3: Custom Fields → Raw Data Export

Create Custom Fields (PF-16): badge_number, shirt_size
Browse in Raw Data Editor (PF-25)
Export to CSV with all fields

Use Case Guides

Terminology & Analysis

Terminology Glossary - Unified term definitions (including wizards & templates)
PF/FW Documentation Review - Detailed terminology analysis
Template Index - Spec template reference

Specifications

Last Updated: 2026-02-01

​Master Comparison Matrix

​Feature Relationship Diagram

​Master Decision Tree

​Detailed Feature Comparisons

​Picklists vs Lookups vs Form Options

​Custom Fields vs Custom Objects

​Forms vs Custom Objects

​Field Configuration vs Form Builder

​Common Scenarios Quick Reference

​”I need a dropdown for employment status”

​”I need a dropdown of departments”

​”I need Yes/No in this form only”

​”I need to add badge number to employees”

​”I need to track clinical licenses”

​”I need to hide salary from non-admins”

​”I need to create an intake form”

​”I need to see all employees and export to CSV”

​”I need to find what objects exist”

​Wizard Comparison

​Form Wizard vs Module Wizard

​When to Use Each Wizard

​Template Comparison

​Template Types

​When to Use Each Template Type

​Anti-Patterns to Avoid

​❌ Using Picklists for Database Table Data

​❌ Using Custom Objects for Entity Extension

​❌ Using Custom Objects for Forms

​❌ Using Custom Fields for New Entities

​❌ Using Form Builder for Entity Extension

​❌ Using Field Configuration to Add Fields

​❌ Using Form Wizard for Business Processes

​❌ Using Module Wizard for Data Capture

​❌ Using Workflow Template for Documents

​❌ Using Document Template for Automation

​Integration Patterns

​Pattern 1: Picklist → Custom Field → Field Config

​Pattern 2: Custom Object → Form Reference

​Pattern 3: Custom Fields → Raw Data Export

​Related Documentation

​Use Case Guides

​Terminology & Analysis

​Specifications