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.

Status: 📝 Planned
Created: 2026-03-02
Source: specs/cl/CL-STRATEGIC-ROADMAP-20260302.md
Constitution Reference: Section 1.3 (Integration Patterns); no direct core-to-core imports.

​
Purpose

Clinical supervisors and HR workforce planners need provider-level productivity metrics: notes completed per week, documentation timeliness (binned/rounded intervals — e.g. <24h, 24–48h, >48h), active caseload (aggregated to non-clinical buckets where needed), no-show rates, and session volume by category. This data exists in CL (e.g. CL-04 note metadata, PM scheduling) but HR has no access layer. This contract defines a read-only platform layer so HR can consume aggregate productivity data without direct CL/PM table access and without PHI (only aggregate counts and timeliness metrics). Privacy controls: Minimum-threshold suppression — do not publish provider metrics for providers with <5 patients in the period. Remove or aggregate “active caseload by severity” to a higher-level bucket to avoid re-identification. A privacy impact assessment is required; specify de-identification approach (HIPAA Safe Harbor or Expert Determination). For behavioral health data, 42 CFR Part 2 review is required before release. Tracked compliance actions (link from this doc):
  1. PIA-CL-HR-01 — Privacy Impact Assessment (PIA) for provider productivity metrics. Owner: Compliance/Privacy Officer. Due: Before first production release. Acceptance criteria: PIA document completed; risks and mitigations documented; approved by designated authority.
  2. PIA-CL-HR-02 — Select de-identification method (HIPAA Safe Harbor vs. Expert Determination). Owner: Compliance/Privacy Officer. Due: Before first production release. Acceptance criteria: Method selected and documented; applied to provider productivity outputs.
  3. PIA-CL-HR-03 — 42 CFR Part 2 legal review for behavioral health workforce metrics. Owner: Legal/Compliance. Due: Before release of metrics that could identify SUD/MH treatment. Acceptance criteria: Legal opinion or checklist completed; disclosure/consent requirements documented.
  4. PIA-CL-HR-04 — Document results in a compliance artifact and link it from this integration doc. Owner: Compliance. Due: With PIA completion. Acceptance criteria: Artifact (e.g. PIA document, compliance checklist) stored in repo or designated location; this integration doc updated with permalink.
Regulatory driver: AZDHS facility staffing standards; AHCCCS contract staffing requirements; CARF HR standards (§§5.A–5.B).

​
Integration Type

  • Platform layer (read-only): CL (and optionally PM) expose a provider productivity summary view or API consumed by HR.
  • No events required: HR can query on demand (e.g. dashboard load) or via scheduled report.

​
Platform Integration Layer

​
API / View: provider_productivity_summary

Provider: CL (and PM for scheduling data if needed) via Platform Integration Layer
Consumer: HR
Status: 📝 Planned

​
Purpose

HR needs read-only access to aggregate provider productivity metrics: note count per provider per period, average documentation lag (session end to note signed), active caseload count, no-show count/rate, session count by service type. No PHI—only provider_id, org_id, site_id, and aggregates.

​
Contract

  • Location: @/platform/workforce — chosen as the canonical module for provider productivity and other workforce metrics (multi-metric pattern). See PLATFORM_INTEGRATION_LAYERS.md for integration guidance.
  • Function/hook: e.g. getProviderProductivity(organizationId, options?: { siteId?, providerId?, periodStart, periodEnd }): Promise<ProviderProductivitySummary[]>.
  • Return shape (conceptual):
    { provider_id, site_id, organization_id, period_start, period_end, notes_completed_count, avg_documentation_lag_hours, active_caseload_count, no_show_count, no_show_rate, session_count_by_category?: Record<string, number> }.
    Use non-clinical category buckets (e.g. “Individual Therapy”, “Group Services”, “Case Management”); only include a category if count ≥ 5 (minimum-threshold suppression).
  • Security: Organization-scoped; caller must have HR role or permission to view productivity. Use a SECURITY DEFINER function that performs server-side aggregation and returns only non-PHI aggregates. RLS alone is insufficient — SECURITY DEFINER ensures aggregation logic runs with elevated privileges to read CL/PM data while returning only aggregated, non-PHI results to the caller.

​
Data Sources

  • CL-04: Note finalized timestamps, session dates, provider (created_by or assigned clinician).
  • PM-03 (scheduling): See PM-03-appointment-scheduling-INTEGRATION.md (or PM-03 spec). Consumed fields: pm_appointments.status → appointment status; pm_encounters or pm_appointments.attendance_flag → no-show indicator; pm_appointments.service_type → service type. These feed CL-04 provider productivity metrics (finalized timestamps, session dates, created_by/assigned clinician, caseload). Access is abstracted via getProviderProductivity() in the Platform Integration Layer.
  • Caseload: count of distinct patients with activity in period (from CL chart or encounter).

​
Implementation Notes

  • Preferred approach: Implement a SECURITY DEFINER SQL function (e.g. get_provider_productivity(period_start, period_end, org_id, site_id)) that performs server-side aggregation and parameter validation for dynamic period filtering and real-time results. Alternative: A materialized view is only for use cases with fixed pre-defined periods and strict performance needs (with scheduled refreshes). Trade-offs: real-time vs refresh latency, security boundaries, and encapsulation — the RPC approach is preferred for this integration.
  • Platform layer: Expose getProviderProductivity() in @/platform/workforce; HR imports from platform only.
  • HR side: Call platform API from HR dashboard or report; no direct CL/PM imports.

​
Testing Requirements

  • getProviderProductivity returns only org-scoped data; no PHI in response
  • Aggregates match source data (note count, lag, caseload)
  • Tenant A cannot see Tenant B’s productivity
  • Small-n suppression: Providers with <5 patients in period are suppressed or aggregated
  • Service-type sensitivity: session_count_by_category uses non-clinical buckets; no raw service-type granularity that could leak behavioral-health details
  • Documentation-lag: Documentation lag metric does not correlate to identifiable sessions in output
  • Permission boundary: Unauthorized roles cannot call getProviderProductivity
  • Cross-site isolation: Site A cannot see Site B productivity even within same org (when siteId filter applied)
  • Parameter injection: Fuzzing for periodStart/periodEnd/providerId (SQL-injection resistance)
  • Performance: Response <2s for ~50 providers (benchmark)
  • Data lineage: Aggregates traceable to CL-04 notes and PM appointments
  • Audit logging: Every access records caller identity and context

​
References