Enterprise Schema

Purpose: Employer healthcare benefits, employee health programs, and provider empanelment Tenant Scoped: No (cross-tenant by design) RLS Enabled: No (employer-based access control)

Overview

The enterprise schema manages B2B relationships between employers and healthcare facilities. Employers (companies) are customers of healthcare facilities, not healthcare providers themselves. This schema operates cross-tenant because:

A single employer may contract with multiple healthcare facilities across different tenants
Employees may receive care at any empaneled provider
Benefit plans and claims span multiple facilities

This is similar to the Connect schema, which also operates cross-tenant for professional networking.

Design Principles

Cross-Tenant Architecture

Unlike tenant-scoped schemas (clinical, billing), the enterprise schema uses employer-based access control:

Employer A
    |
    +-- Employees --> Patient links (cross-tenant)
    |       |
    |       +-- Facility 1 (Tenant X)
    |       +-- Facility 2 (Tenant Y)
    |       +-- Facility 3 (Tenant Z)
    |
    +-- Benefit Plans
    |
    +-- Empaneled Providers (cross-tenant)

Employee-Patient Linkage

Employees link to patients in the clinical schema. An employee at one company can be a patient at any facility, and their clinical data remains tenant-scoped while their employment/benefits data is managed here.

enterprise.employer_employees.patient_id --> clinical.patients.id

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
name	String	Yes	Company name
display_name	String	No	Marketing/display name
employer_type	Enum	Yes	corporation, small_business, non_profit, government
industry	String	No	Industry sector
employee_count	Integer	No	Total employee count
identifiers	JSONB	No	Business identifiers
primary_contact_name	String	No	Primary contact
primary_contact_email	String	No	Contact email
primary_contact_phone	String	No	Contact phone
address	JSONB	No	Headquarters address
website	String	No	Company website
logo_url	String	No	Company logo
country_code	String	Yes	Primary country
timezone	String	No	Primary timezone
fiscal_year_start	Integer	No	Fiscal year start month (1-12)
status	Enum	Yes	active, suspended, terminated
contract_start_date	Date	No	Contract with platform
contract_end_date	Date	No	Contract end
settings	JSONB	No	Employer-level settings
created_at	Timestamp	Yes	Registration date

Employer Type Values:

corporation - Large corporation
small_business - Small/medium business
non_profit - Non-profit organization
government - Government entity

Identifiers Structure:

{
  "ein": "12-3456789",
  "gstin": "29ABCDE1234F1Z5",
  "duns": "123456789"
}

Settings Structure:

{
  "benefits_portal_enabled": true,
  "sso_enabled": true,
  "claims_auto_adjudication": false,
  "wellness_programs_enabled": true,
  "dependent_coverage_allowed": true
}

Relationships:

Has many: EmployerEmployees, EmployerFacilities, BenefitPlans, EmpaneledProviders, WellnessPrograms

Entity: EmployerDepartment

Purpose: Organizational units within an employer

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Parent employer
parent_id	UUID	No	Parent department (hierarchy)
name	String	Yes	Department name
code	String	No	Department code
manager_employee_id	UUID	No	Department manager
is_active	Boolean	Yes	Active status

Relationships:

Belongs to: Employer
Self-referential: parent_id for hierarchy
Has many: EmployerEmployees

Entity: EmployerLocation

Purpose: Physical locations/offices of an employer

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Parent employer
name	String	Yes	Location name
location_code	String	No	Location identifier
address	JSONB	No	Full address
city	String	No	City
state	String	No	State/province
country_code	String	Yes	Country
timezone	String	No	Location timezone
is_primary	Boolean	No	Primary location
is_active	Boolean	Yes	Active status

Relationships:

Belongs to: Employer
Has many: EmployerEmployees

Employees

Entity: EmployerEmployee

Purpose: Employee records linked to patients

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Parent employer
patient_id	UUID	No	Linked patient (cross-tenant)
user_id	UUID	No	Linked user account
employee_id	String	Yes	Employee ID/number
email	String	No	Work email
first_name	String	Yes	First name
last_name	String	No	Last name
date_of_birth	Date	No	Date of birth
gender	Enum	No	male, female, other
phone	String	No	Contact phone
department_id	UUID	No	Department
location_id	UUID	No	Work location
job_title	String	No	Job title
employment_type	Enum	No	full_time, part_time, contractor
hire_date	Date	No	Employment start date
termination_date	Date	No	Employment end date
is_benefits_eligible	Boolean	No	Eligible for benefits
benefits_effective_date	Date	No	Benefits start date
status	Enum	Yes	active, on_leave, terminated
created_at	Timestamp	Yes	Record creation

Employment Type Values:

full_time - Full-time employee
part_time - Part-time employee
contractor - Contractor (may have limited benefits)

Relationships:

Belongs to: Employer, EmployerDepartment, EmployerLocation
Links to: clinical.patients (cross-tenant), identity.users
Has many: EmployeeEnrollments, EmployeeDependents

Entity: EmployeeDependent

Purpose: Employee dependents for family coverage

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_employee_id	UUID	Yes	Employee reference
patient_id	UUID	No	Linked patient (if exists)
first_name	String	Yes	First name
last_name	String	No	Last name
date_of_birth	Date	No	Date of birth
gender	Enum	No	male, female, other
relationship	Enum	Yes	spouse, child, domestic_partner, parent
is_benefits_eligible	Boolean	No	Eligible for coverage
coverage_start_date	Date	No	Coverage start
coverage_end_date	Date	No	Coverage end
status	Enum	Yes	active, inactive

Relationships:

Belongs to: EmployerEmployee
Links to: clinical.patients (cross-tenant)

Benefit Plans

Entity: BenefitPlan

Purpose: Healthcare benefit plan definitions

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Offering employer
name	String	Yes	Plan name
description	Text	No	Plan description
plan_type	Enum	Yes	medical, dental, vision, wellness, ichra
coverage_type	Enum	No	employee_only, employee_spouse, employee_children, family
contribution_type	Enum	No	employer_paid, employee_paid, shared
employer_contribution	Decimal	No	Employer contribution amount/percentage
employee_contribution	Decimal	No	Employee contribution amount/percentage
contribution_frequency	Enum	No	monthly, bi_weekly, per_paycheck
deductible_individual	Decimal	No	Individual deductible
deductible_family	Decimal	No	Family deductible
out_of_pocket_max_individual	Decimal	No	Individual OOP max
out_of_pocket_max_family	Decimal	No	Family OOP max
plan_details	JSONB	No	Detailed plan benefits
network_type	Enum	No	open, preferred, exclusive
effective_date	Date	Yes	Plan start date
termination_date	Date	No	Plan end date
enrollment_start_date	Date	No	Open enrollment start
enrollment_end_date	Date	No	Open enrollment end
is_active	Boolean	Yes	Active plan
currency	String	Yes	Currency code

Plan Type Values:

medical - Medical/health insurance
dental - Dental coverage
vision - Vision coverage
wellness - Wellness allowance
ichra - Individual Coverage HRA

Network Type Values:

open - Any provider
preferred - PPO-style (in/out of network)
exclusive - HMO-style (empaneled only)

Plan Details Structure:

{
  "copay": {
    "primary_care": 20,
    "specialist": 40,
    "urgent_care": 50,
    "emergency": 150
  },
  "coinsurance": {
    "in_network": 20,
    "out_of_network": 40
  },
  "covered_services": ["preventive", "specialist", "hospital", "rx", "mental_health"],
  "excluded_services": ["cosmetic", "experimental"],
  "annual_max": null,
  "lifetime_max": null,
  "rx_tiers": {
    "tier1_generic": 10,
    "tier2_preferred": 30,
    "tier3_non_preferred": 50,
    "tier4_specialty": "30%"
  }
}

Relationships:

Belongs to: Employer
Has many: EmployeeEnrollments, EmpanelmentRates

Entity: EmployeeEnrollment

Purpose: Employee enrollment in benefit plans

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_employee_id	UUID	Yes	Employee reference
benefit_plan_id	UUID	Yes	Enrolled plan
coverage_level	Enum	Yes	employee_only, employee_spouse, employee_children, family
effective_date	Date	Yes	Coverage start
termination_date	Date	No	Coverage end
termination_reason	Enum	No	voluntary, involuntary, life_event, employer_termination
employee_contribution	Decimal	No	Per-period contribution
employer_contribution	Decimal	No	Per-period contribution
enrolled_dependents	JSONB	No	Covered dependent IDs
status	Enum	Yes	pending, active, terminated
enrollment_source	Enum	No	open_enrollment, new_hire, life_event
life_event_type	String	No	If life event enrollment
life_event_date	Date	No	Life event date
created_at	Timestamp	Yes	Enrollment date

Coverage Level Values:

employee_only - Employee only
employee_spouse - Employee + spouse/partner
employee_children - Employee + children
family - Employee + spouse + children

Enrollment Source Values:

open_enrollment - Annual open enrollment
new_hire - New employee enrollment
life_event - Qualifying life event (marriage, birth, etc.)

Relationships:

Belongs to: EmployerEmployee, BenefitPlan
Links to: billing.patient_policies (creates policy record)

Provider Empanelment

Entity: EmployerFacility

Purpose: Links employers to contracted healthcare facilities

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Employer reference
facility_id	UUID	Yes	Facility reference (cross-tenant)
contract_type	Enum	No	exclusive, preferred, in_network
contract_start_date	Date	No	Contract start
contract_end_date	Date	No	Contract end
discount_percentage	Decimal	No	Negotiated discount
terms	JSONB	No	Contract terms
status	Enum	Yes	active, suspended, terminated
created_at	Timestamp	Yes	Creation date

Contract Type Values:

exclusive - Exclusive provider for employer
preferred - Preferred provider (lower copay)
in_network - Standard in-network provider

Relationships:

Belongs to: Employer
Links to: identity.facilities (cross-tenant)

Entity: EmpaneledProvider

Purpose: Individual practitioners empaneled for an employer

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Employer reference
practitioner_id	UUID	Yes	Practitioner reference (cross-tenant)
specialty_id	UUID	No	Practicing specialty
empanelment_type	Enum	No	preferred, standard
effective_date	Date	No	Empanelment start
termination_date	Date	No	Empanelment end
max_patients	Integer	No	Capacity limit
current_patient_count	Integer	No	Current assignments
status	Enum	Yes	active, suspended, terminated

Relationships:

Belongs to: Employer
Links to: identity.practitioners (cross-tenant)
References: reference.specialties

Entity: EmpanelmentRate

Purpose: Negotiated rates for empaneled providers under benefit plans

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Employer reference
benefit_plan_id	UUID	Yes	Benefit plan
facility_id	UUID	No	Facility (if facility-specific)
practitioner_id	UUID	No	Practitioner (if practitioner-specific)
service_type	String	No	Service category
procedure_code	String	No	Specific procedure
rate_type	Enum	Yes	fixed, percentage_of_billed, fee_schedule
rate_amount	Decimal	No	Rate value
effective_date	Date	Yes	Rate start
termination_date	Date	No	Rate end
currency	String	Yes	Currency code

Rate Type Values:

fixed - Fixed fee per service
percentage_of_billed - Percentage of billed amount
fee_schedule - Reference to fee schedule

Relationships:

Belongs to: Employer, BenefitPlan
Links to: identity.facilities, identity.practitioners (cross-tenant)

Wellness Programs

Entity: WellnessProgram

Purpose: Employer-sponsored wellness initiatives

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
employer_id	UUID	Yes	Sponsoring employer
name	String	Yes	Program name
description	Text	No	Program description
program_type	Enum	Yes	health_camp, screening, challenge, education, incentive
category	String	No	Health category
target_audience	Enum	No	all_employees, at_risk, voluntary
start_date	Date	No	Program start
end_date	Date	No	Program end
registration_deadline	Date	No	Registration cutoff
max_participants	Integer	No	Capacity
incentive_type	Enum	No	points, cash, pto, gift_card
incentive_value	Decimal	No	Incentive amount
completion_criteria	JSONB	No	How to complete
partner_vendor_id	UUID	No	Partner vendor (if external)
is_active	Boolean	Yes	Active program
created_at	Timestamp	Yes	Creation date

Program Type Values:

health_camp - On-site health camp/screening event
screening - Health screening program
challenge - Fitness/wellness challenge
education - Health education sessions
incentive - Incentive-based wellness

Completion Criteria Structure:

{
  "type": "challenge",
  "requirements": [
    { "action": "log_steps", "target": 10000, "frequency": "daily", "duration_days": 30 },
    { "action": "complete_assessment", "required": true }
  ],
  "verification": "self_reported"
}

Relationships:

Belongs to: Employer
Links to: identity.vendors (if partner)
Has many: ProgramRegistrations

Entity: ProgramRegistration

Purpose: Employee registration for wellness programs

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
wellness_program_id	UUID	Yes	Program reference
employer_employee_id	UUID	Yes	Employee reference
registration_date	Timestamp	Yes	Registration time
status	Enum	Yes	registered, in_progress, completed, withdrawn
completion_date	Date	No	Completion date
completion_percentage	Decimal	No	Progress percentage
incentive_earned	Boolean	No	Earned incentive
incentive_paid_date	Date	No	Incentive payment date
progress_data	JSONB	No	Progress tracking
notes	Text	No	Notes

Progress Data Structure:

{
  "steps_logged": 250000,
  "days_completed": 25,
  "assessment_completed": true,
  "milestones": [
    { "name": "Week 1", "completed_at": "2024-01-07" },
    { "name": "Week 2", "completed_at": "2024-01-14" }
  ]
}

Relationships:

Belongs to: WellnessProgram, EmployerEmployee

Schema Diagram

+------------------------------------------------------------------+
|                       ENTERPRISE SCHEMA                           |
|                     (Cross-Tenant Design)                         |
+------------------------------------------------------------------+
|                                                                    |
|  +---------------+                                                 |
|  |   employers   |                                                 |
|  +---------------+                                                 |
|         |                                                          |
|         +----------------+----------------+----------------+       |
|         |                |                |                |       |
|         v                v                v                v       |
|  +---------------+ +---------------+ +---------------+ +---------+ |
|  | employer_     | | employer_     | | benefit_      | | wellness| |
|  | departments   | | locations     | | plans         | | programs| |
|  +---------------+ +---------------+ +---------------+ +---------+ |
|         |                |                |                |       |
|         v                v                v                v       |
|  +---------------+ +---------------+ +---------------+ +---------+ |
|  | employer_     | | employer_     | | employee_     | | program_| |
|  | employees     | | facilities    | | enrollments   | | regist- | |
|  +---------------+ +---------------+ +---------------+ | rations | |
|         |                |                             +---------+ |
|         v                v                                         |
|  +---------------+ +---------------+                               |
|  | employee_     | | empaneled_    |                               |
|  | dependents    | | providers     |                               |
|  +---------------+ +---------------+                               |
|                          |                                         |
|                          v                                         |
|                   +---------------+                                |
|                   | empanelment_  |                                |
|                   | rates         |                                |
|                   +---------------+                                |
|                                                                    |
+------------------------------------------------------------------+

                    CROSS-TENANT LINKAGES
+------------------------------------------------------------------+
|                                                                    |
|  enterprise.employer_employees.patient_id                          |
|      --> clinical.patients.id (any tenant)                         |
|                                                                    |
|  enterprise.employer_facilities.facility_id                        |
|      --> identity.facilities.id (any tenant)                       |
|                                                                    |
|  enterprise.empaneled_providers.practitioner_id                    |
|      --> identity.practitioners.id (cross-tenant)                  |
|                                                                    |
|  enterprise.employee_enrollments                                   |
|      --> billing.patient_policies (creates policy records)         |
|                                                                    |
+------------------------------------------------------------------+

Access Control

Since this schema is cross-tenant, access control is based on employer membership rather than tenant isolation:

-- Example: Employer-based access
CREATE POLICY employer_access ON enterprise.employer_employees
    USING (
        employer_id IN (
            SELECT employer_id
            FROM enterprise.employer_admins
            WHERE user_id = current_setting('app.current_user_id')::uuid
        )
    );

Access Patterns

Role	Access Level	Description
Employer Admin	Full	All employer data
HR Manager	Department	Department employees and enrollments
Benefits Admin	Benefits	Benefit plans and enrollments
Employee	Self	Own records and dependents
Facility Staff	Limited	Employee eligibility verification

Integration with Other Schemas

Clinical Schema

employer_employees.patient_id links to clinical.patients
When an employee visits a facility, their patient record is tenant-scoped
The employee linkage allows eligibility verification

Billing Schema

employee_enrollments create billing.patient_policies
Claims filed under employer benefit plans
Reimbursements tracked for ICHRA plans

Identity Schema

employer_facilities links to identity.facilities
empaneled_providers links to identity.practitioners
These are cross-tenant references

Entity Summary

Entity	Description
Employer	Company/organization providing benefits
EmployerDepartment	Organizational units
EmployerLocation	Physical office locations
EmployerEmployee	Employee records (links to patients)
EmployeeDependent	Employee family members
BenefitPlan	Healthcare benefit definitions
EmployeeEnrollment	Employee plan enrollments
EmployerFacility	Contracted healthcare facilities
EmpaneledProvider	Empaneled practitioners
EmpanelmentRate	Negotiated provider rates
WellnessProgram	Wellness initiatives
ProgramRegistration	Program participation

Enterprise Schema

Overview

Design Principles

Cross-Tenant Architecture

Employee-Patient Linkage

Entities

Employers

Entity: Employer

Entity: EmployerDepartment

Entity: EmployerLocation

Employees

Entity: EmployerEmployee

Entity: EmployeeDependent

Benefit Plans

Entity: BenefitPlan

Entity: EmployeeEnrollment

Provider Empanelment

Entity: EmployerFacility

Entity: EmpaneledProvider

Entity: EmpanelmentRate

Wellness Programs

Entity: WellnessProgram

Entity: ProgramRegistration

Schema Diagram

Access Control

Access Patterns

Integration with Other Schemas

Clinical Schema

Billing Schema

Identity Schema

Entity Summary

On this page

Enterprise Schema

OverviewCopy Anchor Link

Design PrinciplesCopy Anchor Link

Cross-Tenant ArchitectureCopy Anchor Link

Employee-Patient LinkageCopy Anchor Link

EntitiesCopy Anchor Link

EmployersCopy Anchor Link

Entity: EmployerCopy Anchor Link

Entity: EmployerDepartmentCopy Anchor Link

Entity: EmployerLocationCopy Anchor Link

EmployeesCopy Anchor Link

Entity: EmployerEmployeeCopy Anchor Link

Entity: EmployeeDependentCopy Anchor Link

Benefit PlansCopy Anchor Link

Entity: BenefitPlanCopy Anchor Link

Entity: EmployeeEnrollmentCopy Anchor Link

Provider EmpanelmentCopy Anchor Link

Entity: EmployerFacilityCopy Anchor Link

Entity: EmpaneledProviderCopy Anchor Link

Entity: EmpanelmentRateCopy Anchor Link

Wellness ProgramsCopy Anchor Link

Entity: WellnessProgramCopy Anchor Link

Entity: ProgramRegistrationCopy Anchor Link

Schema DiagramCopy Anchor Link

Access ControlCopy Anchor Link

Access PatternsCopy Anchor Link

Integration with Other SchemasCopy Anchor Link

Clinical SchemaCopy Anchor Link

Billing SchemaCopy Anchor Link

Identity SchemaCopy Anchor Link

Entity SummaryCopy Anchor Link

On this page

Overview

Design Principles

Cross-Tenant Architecture

Employee-Patient Linkage

Entities

Employers

Entity: Employer

Entity: EmployerDepartment

Entity: EmployerLocation

Employees

Entity: EmployerEmployee

Entity: EmployeeDependent

Benefit Plans

Entity: BenefitPlan

Entity: EmployeeEnrollment

Provider Empanelment

Entity: EmployerFacility

Entity: EmpaneledProvider

Entity: EmpanelmentRate

Wellness Programs

Entity: WellnessProgram

Entity: ProgramRegistration

Schema Diagram

Access Control

Access Patterns

Integration with Other Schemas

Clinical Schema

Billing Schema

Identity Schema

Entity Summary