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 Status: πŸ“ Planned Created: 2026-03-21 Last Updated: 2026-03-21 Constitution Reference: Section 1.3 (Integration Patterns β€” Pattern 1: Platform Integration Layer, Pattern 2: Event-Based)

Overview

This document defines the integration contract between the HR (Human Resources) core and the FW (Forms & Workflow) core. HR uses FW for dynamic forms, approval workflows, event-driven automations, and business rules across multiple HR features. Related Specifications:
  • HR-02: Credentialing & Compliance
  • HR-03: Onboarding & Offboarding
  • HR-06: PTO & Leave Management
  • HR-10: Performance Management & Reviews
  • HR-11: Benefits Administration
  • HR-14: Employee Relations
  • HR-15: Compensation Management
FW Features Consumed:
  • FW-01/FW-05: Forms (single-page and multi-page)
  • FW-03: Automation Engine (event triggers, actions)
  • FW-15: Form Field Lookups (employee/department dropdowns)
  • FW-16: Event-Based Workflow Triggers
  • FW-34: Approval Workflows (multi-level with delegation)
  • FW-45: Decision Tables (routing rules)
Cross-cutting guide: See FW Cross-Core Integration Guide for shared patterns, platform layer imports, and testing requirements.

Integration Pattern

Primary Pattern: Pattern 1 β€” Platform Integration Layer Secondary Pattern: Pattern 2 β€” Event-Based Integration HR accesses FW capabilities through:
  • @/platform/forms β€” form rendering and submission
  • @/platform/approvals β€” approval chain submission and inbox
  • @/platform/events β€” publishing HR events for FW automation triggers
  • @/platform/data-lookup β€” HR data as form field lookup sources
  • @/platform/calendar β€” business day calculations for SLA deadlines

Event Contracts (HR β†’ FW)

Events published by HR that trigger FW automations and workflows.

HR-03: Employee Lifecycle Events

Event: hr_employee_hired

Event: hr_employee_hired Channel: hr_events Publisher: HR (HR-03 Onboarding) Subscribers: FW-03 (onboarding workflow trigger), PF-10 (notification) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers the employee onboarding workflow when a new hire record is created.
Trigger Conditions
  • Trigger: New employee record created with status = 'active' or onboarding instance started
Payload Schema
interface HrEmployeeHiredPayload {
  organization_id: string;  // UUID - tenant isolation
  employee_id: string;      // UUID - hr_employees.id
  department_id: string;    // UUID - pf_departments.id
  position_id: string;      // UUID - hr_positions.id
  site_id?: string;         // UUID - pf_sites.id
  manager_id?: string;      // UUID - hr_employees.id (reporting manager)
  start_date: string;       // ISO date - employment start date
  employment_type: string;  // 'full_time' | 'part_time' | 'contractor'
  timestamp: string;        // ISO timestamp
}
Consumer Actions
ConsumerActionStatus
FW-03 AutomationTrigger onboarding workflow (parallel tasks to HR, IT, Facilities)πŸ“
PF-10 NotificationNotify HR admin and hiring managerπŸ“
Testing Requirements
  • Event fires when new employee created
  • Payload includes organization_id, employee_id, department_id
  • No PII (name, SSN, DOB) in payload
  • Onboarding workflow triggered within FW

Event: hr_employee_terminated

Event: hr_employee_terminated Channel: hr_events Publisher: HR (HR-03 Offboarding) Subscribers: FW-03 (offboarding workflow trigger), PF-10 (notification) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers the employee offboarding workflow when an employee is terminated or resigns.
Payload Schema
interface HrEmployeeTerminatedPayload {
  organization_id: string;
  employee_id: string;
  department_id: string;
  termination_type: string;    // 'voluntary' | 'involuntary' | 'retirement'
  last_working_date: string;   // ISO date
  timestamp: string;
}
Consumer Actions
ConsumerActionStatus
FW-03 AutomationTrigger offboarding checklist (IT deprovisioning, asset return, exit interview)πŸ“
PF-10 NotificationNotify HR admin, IT, facilitiesπŸ“

HR-02: Credential Management Events

Event: hr_credential_expired

Event: hr_credential_expired Channel: hr_events Publisher: HR (HR-02 Credentialing) Subscribers: FW-03 (renewal reminder automation) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers renewal reminder workflow when an employee credential expires or approaches expiry.
Payload Schema
interface HrCredentialExpiredPayload {
  organization_id: string;
  credential_id: string;        // UUID - hr_credentials.id
  employee_id: string;          // UUID - hr_employees.id
  credential_type: string;      // e.g., 'license', 'certification', 'cpr'
  expiration_date: string;      // ISO date
  days_until_expiry?: number;   // Negative if already expired
  timestamp: string;
}
Consumer Actions
ConsumerActionStatus
FW-03 AutomationTrigger credential reminder workflow (email at 90/60/30/7 days)πŸ“
FW-03 AutomationCreate renewal task for HR compliance teamπŸ“
PF-10 NotificationAlert employee and compliance officerπŸ“

Event: hr_credential_verified

Event: hr_credential_verified Channel: hr_events Publisher: HR (HR-02 Credentialing) Subscribers: FW-03 (compliance status update) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Updates compliance tracking when a credential is verified or renewed.
Payload Schema
interface HrCredentialVerifiedPayload {
  organization_id: string;
  credential_id: string;
  employee_id: string;
  credential_type: string;
  new_expiration_date: string;
  verified_by: string;           // UUID - user who verified
  timestamp: string;
}

HR-06: Leave Management Events

Event: hr_leave_request_submitted

Event: hr_leave_request_submitted Channel: hr_events Publisher: HR (HR-06 PTO & Leave Management) Subscribers: FW-34 (approval workflow) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers the leave request approval workflow when an employee submits a leave request.
Payload Schema
interface HrLeaveRequestSubmittedPayload {
  organization_id: string;
  leave_request_id: string;     // UUID - hr_leave_requests.id
  employee_id: string;          // UUID
  leave_type: string;           // 'vacation' | 'sick' | 'personal' | 'fmla' | 'bereavement'
  start_date: string;           // ISO date
  end_date: string;             // ISO date
  total_days: number;
  department_id: string;
  manager_id: string;           // UUID - direct manager
  timestamp: string;
}
Consumer Actions
ConsumerActionStatus
FW-34 ApprovalRoute to approval chain based on leave type and durationπŸ“
FW-45 Decision TableDetermine approval chain (leave type Γ— days β†’ chain)πŸ“

HR-10: Performance Management Events

Event: hr_performance_review_due

Event: hr_performance_review_due Channel: hr_events Publisher: HR (HR-10 Performance Management) Subscribers: FW-03 (review cycle workflow) Status: πŸ“ Planned (not yet in KnownEventName)
Purpose
Triggers the performance review cycle workflow when reviews are due for employees.
Payload Schema
interface HrPerformanceReviewDuePayload {
  organization_id: string;
  review_cycle_id: string;
  employee_id: string;
  reviewer_id: string;          // UUID - manager conducting review
  review_type: string;          // 'annual' | 'quarterly' | 'probationary' | 'project'
  due_date: string;
  timestamp: string;
}

Event: hr_pip_initiated

Event: hr_pip_initiated Channel: hr_events Publisher: HR (HR-10 Performance Management) Subscribers: FW-03 (PIP tracking workflow) Status: πŸ“ Planned (not yet in KnownEventName; related hr_pip_terminated is registered)
Purpose
Triggers PIP tracking workflow with milestone reminders and escalation deadlines.
Payload Schema
interface HrPipInitiatedPayload {
  organization_id: string;
  pip_id: string;
  employee_id: string;
  manager_id: string;
  start_date: string;
  end_date: string;              // PIP deadline
  review_milestones: string[];   // ISO dates for check-in milestones
  timestamp: string;
}

HR-11: Benefits Events

Event: hr_benefits_enrollment_approved

Event: hr_benefits_enrollment_approved Channel: hr_events Publisher: HR (HR-11 Benefits Administration) Subscribers: FW-03 (enrollment processing automation) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers post-approval processing when a benefits enrollment is approved.
Payload Schema
interface HrBenefitsEnrollmentApprovedPayload {
  organization_id: string;
  enrollment_id: string;
  employee_id: string;
  plan_type: string;             // 'medical' | 'dental' | 'vision' | '401k'
  effective_date: string;
  timestamp: string;
}

HR-14: Employee Relations Events

Event: hr_disciplinary_action_termination

Event: hr_disciplinary_action_termination Channel: hr_events Publisher: HR (HR-14 Employee Relations) Subscribers: FW-03 (termination workflow), HR-03 (offboarding trigger) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers termination workflow when a disciplinary action results in termination.
Payload Schema
interface HrDisciplinaryTerminationPayload {
  organization_id: string;
  disciplinary_action_id: string;
  employee_id: string;
  action_type: string;           // 'termination'
  effective_date: string;
  timestamp: string;
}

Event: hr_incident_reported

Event: hr_incident_reported Channel: hr_events Publisher: HR (HR-14 Employee Relations) Subscribers: FW-03 (investigation workflow) Status: βœ… Implemented (registered in KnownEventName)
Purpose
Triggers investigation workflow when an employee incident is reported.
Payload Schema
interface HrIncidentReportedPayload {
  organization_id: string;
  incident_id: string;
  reporter_id: string;          // UUID - employee who reported
  incident_type: string;        // 'harassment' | 'safety' | 'policy_violation' | 'other'
  severity: string;             // 'low' | 'medium' | 'high' | 'critical'
  site_id?: string;
  timestamp: string;
}

Approval Chain Configurations

Leave Request Approval

Chain ID: hr-leave-request-approval Entity Type: hr_leave_requests Based On: HR-06
StepApprover TypeConditionTimeoutEscalation
1submitter_managerAlways48hdepartment_head
2role: hr_managerLeave > 5 days OR FMLA72hrole: hr_director
Decision Table for Routing:
Leave TypeDays→ Chain Steps
Vacation≀ 5Manager only
Vacation> 5Manager β†’ HR
SickAnyManager only (auto-approve if balance sufficient)
FMLAAnyManager β†’ HR β†’ Compliance
BereavementAnyManager only (auto-approve)

Credential Renewal Approval

Chain ID: hr-credential-renewal-approval Entity Type: hr_credentials Based On: HR-02
StepApprover TypeConditionTimeoutEscalation
1role: compliance_officerAlways72hrole: hr_director
2role: hr_directorCritical credentials only48hβ€”

Performance Review Approval

Chain ID: hr-performance-review-approval Entity Type: hr_performance_reviews Based On: HR-10
StepApprover TypeConditionTimeoutEscalation
1submitter_manager (reviewer’s manager)Always5 business daysdepartment_head
2department_headRating: β€œexceeds expectations” or β€œunsatisfactory”3 business daysrole: hr_director

Compensation Change Approval

Chain ID: hr-compensation-change-approval Entity Type: hr_compensation_changes Based On: HR-15
StepApprover TypeConditionTimeoutEscalation
1submitter_managerAlways48hdepartment_head
2role: hr_managerAlways72hrole: hr_director
3role: finance_managerIncrease > 10% OR salary > threshold72hrole: cfo
Decision Table for Routing:
Increase %Salary Level→ Approval Levels
≀ 5%AnyManager β†’ HR
5-10%AnyManager β†’ HR β†’ Finance
> 10%AnyManager β†’ HR β†’ Finance β†’ CFO
Any> $150KManager β†’ HR β†’ Finance β†’ CFO

Form Templates

HR uses these FW form templates (specs in specs/fw/templates/):
Template IDTypeSpec LocationDescription
hr-leave-request-formFormspecs/fw/templates/forms/hr-leave-request-form.mdLeave request data capture
hr-employee-w4-formFormspecs/fw/templates/forms/hr-employee-w4-form.mdFederal W-4 tax withholding
hr-employee-i9-formFormspecs/fw/templates/forms/hr-employee-i9-form.mdEmployment eligibility verification
hr-leave-request-bundleBundlespecs/fw/templates/bundles/hr-leave-request-bundle.mdForm + approval workflow

Planned Form Templates (Not Yet Specced)

Template IDTypePriorityDescription
hr-performance-review-formFormP1Performance review data capture
hr-onboarding-checklist-formFormP1New hire checklist (multi-page)
hr-exit-interview-formFormP2Employee exit interview survey
hr-pip-tracking-formFormP2PIP progress documentation
hr-direct-deposit-formFormP2Banking information capture
hr-onboarding-acknowledgment-formFormP2Policy acknowledgment signatures

Workflow Templates

Template IDSpec LocationDescription
hr-leave-request-approvalspecs/fw/templates/workflows/hr-leave-request-approval.mdLeave request through approval chain
hr-credential-reminderspecs/fw/templates/workflows/hr-credential-reminder.mdCredential expiry reminders at 90/60/30/7 days
Template IDPriorityDescription
hr-employee-onboardingP0Multi-department parallel onboarding (HR, IT, Facilities, Manager)
hr-employee-offboardingP0Offboarding checklist with IT deprovisioning, asset return
hr-pip-trackingP1PIP milestone reminders and escalation
hr-performance-review-cycleP1Annual/quarterly review cycle with self-assessment β†’ manager β†’ calibration
hr-benefits-enrollmentP2Open enrollment workflow with deadline reminders
hr-compensation-approvalP2Multi-level compensation change approval

Form Field Lookups

HR exposes these data sources for FW form field lookups (FW-15):
Lookup SourceTableValue ColumnLabel ColumnFilterUsed By
Employeeshr_employeesidfull_namestatus = 'active'Leave forms, review forms
Departmentspf_departmentsidnameorganization_idAll HR forms
Positionshr_positionsidtitlestatus = 'active'Onboarding, compensation
Managershr_employeesidfull_nameis_manager = trueReview forms, leave forms
Leave Typeshr_leave_typesidnameis_active = trueLeave request form
Credential Typeshr_credential_typesidnameβ€”Credential forms

Platform Layer Usage

Hooks HR Components Import

// Forms
import { useFormTemplate, FormRenderer } from '@/platform/forms';

// Approvals
import { useSubmitApprovalRequest, useMyApprovalRequests } from '@/platform/approvals';

// Events
import { publishEvent } from '@/platform/events';
import type { KnownEventName } from '@/platform/events';

// Data lookups for form fields
import { useLookupOptions } from '@/platform/data-lookup';

Testing Requirements

Unit Tests

  • HR event payloads match documented schemas
  • Leave request decision table returns correct approval chain
  • Compensation decision table returns correct approval levels
  • No PII/PHI in event payloads

Integration Tests

  • hr_employee_hired event triggers onboarding workflow in FW
  • hr_leave_request_submitted event routes to correct approval chain
  • hr_credential_expired event triggers reminder automation
  • Approval request status updates propagate back to HR entity
  • Form field lookups return correct HR data

E2E Tests

  • Complete leave request flow: form submission β†’ approval β†’ balance update
  • Complete onboarding flow: hire β†’ workflow β†’ parallel tasks β†’ completion
  • Credential expiry β†’ reminder β†’ renewal β†’ verification flow

RLS Tests

  • HR events filtered by organization_id
  • Approval requests scoped to submitter’s organization
  • Form submissions isolated per tenant

Implementation Status

IntegrationStatusNotes
HR events in KnownEventNameβœ… Partial12 events registered; hr_performance_review_due, hr_pip_initiated pending
Leave request approval chainπŸ“ PlannedChain config needed; form + workflow templates ready
Onboarding workflowπŸ“ PlannedTemplate recommended in FW-28; not yet implemented
Credential reminder automationπŸ“ PlannedWorkflow template ready (hr-credential-reminder)
Performance review workflowπŸ“ PlannedEvents and chain not yet registered
Compensation approval chainπŸ“ PlannedDecision table needed for amount-based routing
Form field lookupsπŸ“ PlannedHR table lookup configs not yet registered