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

# FLSA Classification & Compliance Engine — Integration Documentation

> -flsa-classification-compliance-engine.md Status: \U0001F4DD Planned Last Updated: 2026-03-25

**Spec:** [HR-29-flsa-classification-compliance-engine.md](../../../specs/hr/specs/HR-29-flsa-classification-compliance-engine.md)
**Status:** 📝 Planned
**Last Updated:** 2026-03-25

***

## Integration Overview

HR-29 integrates within the HR core and with Platform Foundation layers:

| Integration                | Pattern                       | Direction                                               | Status     |
| -------------------------- | ----------------------------- | ------------------------------------------------------- | ---------- |
| HR-01 (Employee Directory) | Direct dependency (same core) | HR-29 reads position data; writes classification status | 📝 Planned |
| HR-07 (Payroll)            | Event-based                   | HR-29 publishes classification change events            | 📝 Planned |
| HR-07-ENHANCEMENTS EN-1    | Direct dependency (same core) | HR-29 creates retroactive pay requests                  | 📝 Planned |
| HR-05 (Time & Attendance)  | Direct data read (same core)  | HR-07 EN-1 reads hours for retroactive calc             | 📝 Planned |
| PF-10 (Notifications)      | Platform Integration Layer    | HR-29 sends threshold and review alerts                 | 📝 Planned |
| PF-30 (RBAC)               | Direct dependency             | Permission checks for all operations                    | 📝 Planned |

***

## 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:**

```typescript theme={null}
{
  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:**

```typescript theme={null}
{
  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)

Threshold change re-evaluation is handled as application-layer logic within HR-29, not as an event contract:

* **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

```plaintext theme={null}
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](../../../specs/hr/specs/HR-29-flsa-classification-compliance-engine.md)
* [HR-07-ENHANCEMENTS EN-1](../../../specs/hr/specs/HR-07-ENHANCEMENTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)