FLSA Classification & Compliance Engine — Integration Documentation

​

Integration Overview

​

Event Contracts

​

Published Events

​

hr.flsa.classification_changed

• Publisher: HR-29
• Subscribers: HR-07 (Payroll), HR-01 (Employee Directory)
• Trigger: When a classification is created, updated, or a reclassification is approved
• Payload Schema:

{
  classification_id: string;
  position_id: string;
  employee_id: string;
  previous_classification: 'exempt' | 'non_exempt';
  new_classification: 'exempt' | 'non_exempt';
  effective_date: string; // ISO 8601
  retroactive_start_date: string | null; // ISO 8601 or null — start of retroactive period when applicable
  retroactive_pay_request_id: string | null; // FK to hr_retroactive_pay_requests when payroll must process back pay
  organization_id: string;
}

• Consumer Action (HR-07): Update overtime eligibility for affected employee in next payroll cycle; when retroactive_pay_request_id is present, HR-07 EN-1 uses it to locate/compute retroactive pay and maintain the audit trail.
• Consumer Action (HR-01): Update authoritative exempt/non-exempt fields on position and employee records per HR-01 data model (e.g. exempt_status / is_exempt — use actual column names from types.ts after migration; HR-29 must not invent parallel payroll-facing fields)

​

hr.flsa.reclassification_approved

• Publisher: HR-29
• Subscribers: HR-07 (Payroll)
• Trigger: When a reclassification is approved
• Payload Schema:

{
  reclassification_id: string;
  employee_id: string;
  new_classification: 'exempt' | 'non_exempt';
  effective_date: string; // ISO 8601
  retroactive_start_date: string | null;
  retroactive_pay_request_id: string | null;
  organization_id: string;
}

• Consumer Action (HR-07): If retroactive_pay_request_id is present, HR-07 EN-1 locates the request in hr_retroactive_pay_requests and computes the retroactive amounts. HR-29 does not include pay amounts in this event.

​

Internal Application Logic (No Consumed Events)

• Immediate re-evaluation: When an admin saves a threshold with effective_date ≤ today, the save handler triggers re-evaluation inline.
• Scheduled re-evaluation: A daily cron job (hr-flsa-threshold-check, 6:00 AM) checks for future-dated thresholds whose effective date has arrived and triggers batch re-evaluation.

​

Platform Integration Layer Usage

• PF-10 (Notifications): @/platform/notifications — threshold proximity alerts, review due notifications, reclassification approval notifications
• PF-30 (RBAC): @/platform/permissions — useHasPermission for all FLSA permission keys

​

Data Flow: Reclassification with Retroactive Pay

1. HR admin initiates reclassification (HR-29)
2. Approver approves reclassification (HR-29)
3. HR-29 creates hr_retroactive_pay_requests record (reason='reclassification')
4. HR-29 publishes hr.flsa.reclassification_approved event
5. HR-07 EN-1 calculates retroactive pay using HR-05 hours data
6. Retroactive amount included as line item in next payroll run (HR-07)

​

Security Considerations

• All event payloads include organization_id for tenant validation
• Subscribers MUST verify organization_id matches their tenant context
• Classification data includes PII (salary); events carry only IDs and classification status, not salary amounts

​

References

• HR-29 Spec
• HR-07-ENHANCEMENTS EN-1
• CROSS_CORE_INTEGRATIONS.md
• EVENT_CONTRACTS.md