> ## 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.

# Platform Data Features: Clarity Analysis

> Purpose: Comprehensive comparison of all data management features to help choose the right tool for each scenario.

**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](../../architecture/standards/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 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

| 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

### "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

| 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

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

***

## Related Documentation

### Use Case Guides

* [Picklists Use Case Guide](./picklists.md)
* [Custom Fields Use Case Guide](./custom-fields.md)
* [Field Configuration Use Case Guide](./field-configuration.md)
* [Data Manager Use Case Guide](./data-manager.md)
* [Custom Objects Use Case Guide](./custom-objects.md)
* [Forms Use Case Guide](./forms.md)

### Terminology & Analysis

* [Terminology Glossary](../../architecture/standards/TERMINOLOGY.md) - Unified term definitions (including wizards & templates)
* [PF/FW Documentation Review](../../architecture/reviews/PF-FW-DOCUMENTS-REVIEW-2026-02-01.md) - Detailed terminology analysis
* [Template Index](../../../specs/_templates/TEMPLATE_INDEX.md) - Spec template reference

### Specifications

* [FW-31: Form Wizards](../../../specs/fw/archive/FW-31-multi-step-form-wizards.md)
* [PF-41: Module Wizards](../../../specs/pf/specs/PF-41-configurable-module-wizards.md)
* [FW-28: Workflow Templates](../../../specs/fw/archive/FW-28-workflow-templates-marketplace.md)
* [PF-64: Document Templates](../../../specs/pf/specs/PF-64-organization-document-templates.md)

***

**Last Updated:** 2026-02-01