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

FeaturePurposeStorageScopeUse When
Picklists (PF-15)Reusable dropdown valuespf_picklists + pf_picklist_itemsOrganizationValues used across multiple forms/entities
Custom Fields (PF-16)Extend existing entity schemas{table}.custom_fields JSONBOrganization + EntityAdding metadata to existing entities
Field Configuration (PF-17)Control field behaviorpf_entity_field_configsOrganization + Entity + ContextVisibility, required rules, ordering
Object Browser (PF-23)Discover and manage objectspf_object_metadataOrganizationBrowse, categorize, favorite objects
Custom Objects (PF-24)Create new entity typespf_custom_objects + pf_custom_object_recordsOrganizationNew entities with CRUD operations
Raw Data Editor (PF-25)Browse and edit recordsCore tablesOrganizationView records, edit custom fields, export CSV
Form Builder (FW-01)Data capture interfacesfw_forms + fw_form_submissionsOrganizationOne-time data capture, workflows
Lookups (FW-15)Dynamic dropdown from tablesDatabase tablesDatabaseDropdown values from existing data
Form Wizards (FW-31)Multi-step data capturefw_forms.wizard_configOrganizationGuided form completion with steps
Module Wizards (PF-41)Business process guidancepf_wizard_templatesOrganizationOnboarding, payroll, admissions
Workflow Templates (FW-28)Reusable automationfw_workflow_templatesOrganizationShareable workflow patterns
Document Templates (PF-64)Printable PDFspf_document_templatesOrganizationPolicies, letters, reports

​
Feature Relationship Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Encore Health 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

AspectPicklists (PF-15)Lookups (FW-15)Form Options (FW-01)
Data Sourcepf_picklist_itemsDatabase tablesForm definition
ScopeOrganizationDatabase/RLSSingle form
ManagementSettings UIAutomaticForm Builder
Reusable✅ Yes✅ Yes❌ No
Dynamic❌ Static✅ Real-time❌ Static
ExampleEmployment statusDepartments listYes/No question

​
Custom Fields vs Custom Objects

AspectCustom Fields (PF-16)Custom Objects (PF-24)
PurposeExtend existing entityCreate new entity
StorageJSONB column on entitySeparate table
Records1:1 with entityIndependent records
CRUDVia entityFull CRUD
ExampleBadge number on employeeClinical licenses

​
Forms vs Custom Objects

AspectForms (FW-01)Custom Objects (PF-24)
PurposeData captureEntity management
Data ModelForm → SubmissionsObject → Records
LifecycleSubmit onceCRUD operations
Workflow✅ Built-in❌ Manual
ExampleIntake formLicense tracking

​
Field Configuration vs Form Builder

AspectField Configuration (PF-17)Form Builder (FW-01)
PurposeControl field behaviorBuild data capture forms
ScopeEntity fieldsForm-specific fields
VisibilityRole-basedEveryone
RequiredContext-basedFixed
ExampleHide salary from staffCreate intake form

​
Common Scenarios Quick Reference

​
”I need a dropdown for employment status”

→ Picklist (PF-15) - Reusable across forms/entities

​
”I need a dropdown of departments”

→ 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

AspectForm Wizard (FW-31)Module Wizard (PF-41)
PurposeMulti-step data captureBusiness process guidance
Data Storagefw_form_submissionsModule-specific tables
Step TypesForm fields onlyForm, Custom, Review
CustomizationField configurationFull step customization
Use CaseSurveys, intake formsOnboarding, 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 TypeSpecPurposeStorageUse Case
Workflow TemplatesFW-28Automation patternsfw_workflow_templatesReusable workflows
Document TemplatesPF-64Printable PDFspf_document_templatesPolicies, letters
Form TemplatesFW-01Clonable formsfw_formsForm patterns
Wizard TemplatesPF-41Business wizardspf_wizard_templatesOnboarding wizards
Spec Templates-Documentationspecs/_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

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

​
Pattern 2: Custom Object → Form Reference

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

​
Pattern 3: Custom Fields → Raw Data Export

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

​
Use Case Guides

​
Terminology & Analysis

​
Specifications

Last Updated: 2026-02-01