Benefits Administration — Integration

​

Overview

​

Integration Points

​

Platform Foundation (PF) Dependencies

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

​

Consumer Core Dependencies (Downstream)

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

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

​

Event Contracts

​

Event: hr_benefits_enrollment_approved

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

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

// 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,
  });
}

• 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

• 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
• EVENT_CONTRACTS.md
• CROSS_CORE_INTEGRATIONS.md