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

# Benefits Administration — Integration

> Version: 1.0.0 Last Updated: 2026-03-20 Spec: HR-11 Benefits Administration Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration P…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-11 Benefits Administration](../../../specs/hr/specs/HR-11-benefits-administration.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-11 manages employee benefits enrollment, plans, and eligibility. It publishes events for enrollment approvals and terminations, and integrates with HR-06 (Leave Management), HR-07 (Payroll), and FA-15 (Cost Allocation).

***

## Integration Points

### Platform Foundation (PF) Dependencies

**Required PF Features:**

* **PF-10 (Notifications)**: Enrollment reminders, approval notifications
  * **Integration Type:** Platform Integration Layer (`@/platform/notifications`)

### Consumer Core Dependencies (Downstream)

**Internal HR Features:**

* **HR-01 (Employee Directory)**: Employee context, employment type, tenure
* **HR-06 (Leave Management)**: Benefits-eligible leave tracking
* **HR-07 (Payroll)**: Benefits deductions, employer contributions

**External Cores:**

* **FA-15 (Cost Allocation & Indirect Cost Rates)**: Benefits cost allocation to departments

***

## Event Contracts

### Event: `hr_benefits_enrollment_approved`

**Publisher:** HR (HR-11)\
**Subscribers:** HR-06 Phase 2 (Leave Management), HR-07 (Payroll)\
**Status:** 📝 Planned

**Purpose:** Notify payroll and leave management of approved enrollment

**Published when:** Enrollment status changes to 'approved' or 'active'

**Payload Schema:**

```typescript theme={null}
interface HrBenefitsEnrollmentApprovedPayload {
  event_type: 'hr_benefits_enrollment_approved';
  enrollment_id: uuid;
  employee_id: uuid;
  plan_id: uuid;
  plan_type: string;
  effective_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

### Event: `hr_benefits_enrollment_terminated`

**Publisher:** HR (HR-11)\
**Subscribers:** HR-06 Phase 2 (Leave Management), HR-07 (Payroll)\
**Status:** 📝 Planned

**Purpose:** Notify payroll and leave management of enrollment termination

**Published when:** Enrollment status changes to 'terminated'

**Payload Schema:**

```typescript theme={null}
interface HrBenefitsEnrollmentTerminatedPayload {
  event_type: 'hr_benefits_enrollment_terminated';
  enrollment_id: uuid;
  employee_id: uuid;
  plan_id: uuid;
  plan_type: string;
  termination_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

### Events Consumed

* `hr_employee_hired` from HR-09 (ATS) - Create initial eligibility check
* `hr_employee_terminated` from HR-03 (Offboarding) - Terminate benefits

***

## API Contracts

### API: Employee Benefit Enrollment Status Query Hook

**Endpoint:** RLS-enforced query to `hr_benefits_enrollments` table\
**Method:** Read-only via Supabase client\
**Provider:** HR (HR-11)\
**Consumers:** HR-06 Phase 2 (Leave Management)\
**Status:** ✅ Available

**Purpose:** Check if an employee is enrolled in a specific benefit plan type (e.g., STD, LTD, disability)

**Example:**

```typescript theme={null}
// src/cores/hr/hooks/useEmployeeBenefitEnrollment.ts
export function useEmployeeBenefitEnrollment(
  employeeId: string, 
  planType: 'std' | 'ltd' | 'disability' | 'health' | 'dental' | 'vision' | 'retirement' | 'life'
) {
  return useQuery({
    queryKey: ['hr-benefits-enrollment', employeeId, planType],
    queryFn: async () => {
      const { data, error } = await supabase
        .from('hr_benefits_enrollments')
        .select(`
          *,
          plan:hr_benefits_plans(*)
        `)
        .eq('employee_id', employeeId)
        .eq('status', 'active')
        .eq('plan.plan_type', planType)
        .maybeSingle();
      
      if (error) throw error;
      return data;
    },
    staleTime: 5 * 60 * 1000,
    gcTime: 10 * 60 * 1000,
    enabled: !!employeeId && !!planType,
  });
}
```

**Implementation Notes:**

* Events should be published via database triggers on `hr_benefits_enrollments` table
* HR-06 Phase 2 subscribes to these events to update leave eligibility in real-time
* See `docs/architecture/integrations/EVENT_CONTRACTS.md` for complete event schema

***

## Platform Integration Layer Usage

**Consumes:**

* **PF-10 (Notifications)**: Enrollment reminders, approval notifications via `@/platform/notifications`

***

## Security Considerations

### Multi-Tenancy

* ✅ **RLS Enforcement**: All `hr_benefits_*` tables filtered by `organization_id` via RLS policies

### Role-Based Access Control

* ✅ **HR Admin**: Full access to all benefits data
* ✅ **Manager**: View benefits for direct reports
* ✅ **Staff**: View own benefits enrollment only

### Data Protection

* ✅ **PII Handling**: Benefits enrollment may contain sensitive employee information; access controlled via RLS
* ✅ **Audit Trail**: All benefits enrollment changes logged via PF-04

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event fires on trigger condition (enrollment approval, termination)
* [ ] Correct `organization_id` included in all events
* [ ] Subscribers handle events correctly (HR-06, HR-07)
* [ ] RLS policies enforce org isolation on benefits queries
* [ ] Enrollment status query hook works correctly

***

## References

* [HR-11 Spec](../../../specs/hr/specs/HR-11-benefits-administration.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)