Credentialing & Compliance — Integration

​

Overview

​

Integration Points

​

Platform Foundation (PF) Dependencies

• PF-10 (Notifications): Send expiration alerts (90/60/30/14/7 days), verification status notifications
• PF-11 (Document Management): Store credential PDFs, manage versions, secure access
• PF-04 (Audit Logging): Log credential uploads, verifications, expirations for compliance
• FW (Forms & Workflow): Credential renewal workflows (Enhancement 1)

​

Consumer Core Dependencies (Downstream)

• HR-01 (Employee Directory): Links credentials to employees, displays compliance status on profile
• HR-03 (Onboarding): New hire checklist includes credential uploads
• HR-04 (Scheduling): Blocks scheduling for employees with expired credentials (via event subscription)
• HR-05 (Time Tracking): Blocks clock-in for employees with expired credentials (via event subscription)
• HR-07 (Payroll): Compliance report for payroll eligibility

• RH (Recovery Housing): Clinical staff credential verification for resident care (future)
• GR (Governance): Training completion tracking (future)

​

Event Contracts

​

Event: hr_credential_expired (canonical)

interface HrCredentialExpiredPayload {
  event_type: 'hr_credential_expired';
  employee_id: uuid;
  credential_id: uuid;
  credential_type_id: uuid;
  expiration_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}

​

Event: hr_credential_verified

interface HrCredentialVerifiedPayload {
  event_type: 'hr_credential_verified';
  employee_id: uuid;
  credential_id: uuid;
  verification_status: 'verified' | 'rejected';
  verified_by: uuid;
  verified_at: timestamptz;
  organization_id: uuid;
  timestamp: timestamptz;
}

​

Event: hr_credential_renewal_workflow_started (Enhancement 1)

interface HrCredentialRenewalWorkflowStartedPayload {
  event_type: 'hr_credential_renewal_workflow_started';
  credential_id: uuid;
  employee_id: uuid;
  credential_type: string;
  expiration_date: date;
  days_until_expiration: number;
  organization_id: uuid;
  timestamp: timestamptz;
}

​

Event: hr_credential_renewed (Enhancement 1)

interface HrCredentialRenewedPayload {
  event_type: 'hr_credential_renewed';
  credential_id: uuid;
  employee_id: uuid;
  new_expiration_date: date;
  renewal_workflow_id: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}

​

Platform Integration Layer Usage

• PF-10 (Notifications):
  • Expiration alerts via send_notification() function
  • Notification types: credential_expiring, credential_expired, credential_verified
  • Channels: in_app, email (future)
• PF-11 (Document Management):
  • Credential PDFs stored in pf_documents bucket
  • Category: credential
  • Access controlled via document permissions
• PF-12 (Reports):
  • Compliance reports (expiration forecasts, audit reports)
  • Pre-built templates for credential compliance
• FW (Forms & Workflow):
  • Credential renewal workflows via @/platform/forms
  • Renewal form templates and approval gates
  • Workflow triggers based on credential expiration dates

​

Integration Examples

​

Example 1: Send Expiration Alert via PF-10

-- In credential expiration check function
SELECT send_notification(
  _user_id := employee.profile_id,
  _title := 'Credential Expiring Soon',
  _body := credential_type.name || ' expires on ' || credential.expiration_date,
  _type := 'credential_expiring',
  _channel := 'in_app',
  _data := jsonb_build_object(
    'credential_id', credential.id,
    'expiration_date', credential.expiration_date,
    'days_until_expiration', days_until_expiration
  )
);

​

Example 2: Store Credential Document via PF-11

// In credential upload handler
import { useDocumentUpload } from '@/platform/documents';

const { upload } = useDocumentUpload();

await upload({
  file: credentialFile,
  title: `${credentialType.name} - ${employee.full_name}`,
  category: 'credential',
  organization_id: currentOrg.id,
  site_id: employee.primary_site_id,
  metadata: {
    employee_id: employee.id,
    credential_type_id: credentialType.id,
    expiration_date: expirationDate
  }
});

​

Security Considerations

​

Multi-Tenancy

• ✅ RLS Enforcement: All hr_credentials tables filtered by organization_id via RLS policies
• ✅ Document Access: Credential PDFs access-controlled via PF-11 document permissions

​

Role-Based Access Control

• ✅ HR Admin: Full access to all credentials (CRUD)
• ✅ Manager: View credentials for direct reports
• ✅ Staff: View own credentials only

​

Data Protection

• ✅ PII Handling: Credential documents may contain PII; stored securely in PF-11
• ✅ Audit Trail: All credential uploads, verifications, expirations logged via PF-04

​

Testing Requirements

• Event payload structure validation
• Event fires on trigger condition (credential expiration, verification)
• Correct organization_id included in all events
• Subscribers handle events correctly (HR-04, HR-05, FW)
• PF-10 notifications sent at correct expiration thresholds
• PF-11 document upload and access control works correctly
• RLS policies enforce org isolation on credential queries

​

References

• HR-02 Spec
• EVENT_CONTRACTS.md
• CROSS_CORE_INTEGRATIONS.md