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.

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