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.

Feature ID: CL-29-EN-65
Parent: CL-29 Discharge & Aftercare Planning — CL-29-discharge-aftercare-planning-INTEGRATION.md
Status: 📋 Specification
Spec Reference: CL-29-EN-65-hedis-fuh-fum-tracking.md
Last Updated: 2026-03-03

​
Overview

Extends cl_aftercare_plans with 6 HEDIS FUH/FUM boolean flag columns. Exposes a cl_hedis_fuh_fum_summary view consumed by CL-15 (Quality Measures Dashboard) and CL-35 (Population Health) for measure performance reporting and care gap calculation. Flag-setting logic runs application-side at discharge save and follow-up contact save. No new cross-core dependencies beyond what CL-29 already uses; PM encounter type accessed via @/platform/scheduling and @/platform/types.

​
Quick Reference

  • Data contract: cl_hedis_fuh_fum_summary view — aggregates FUH/FUM numerator/denominator counts by organization_id and measurement_year
  • Flag tables: cl_aftercare_plans (6 new boolean columns; inherit existing RLS)
  • Consumers: CL-15 (rates/export UI), CL-35 (care gap input)
  • Producers: Application-level hooks on cl_aftercare_plans save and cl_follow_up_contacts save
  • Permission gates: cl.hedis-tracking.view, cl.hedis-tracking.export

​
Data Contract: cl_hedis_fuh_fum_summary View

CREATE OR REPLACE VIEW cl_hedis_fuh_fum_summary
WITH (security_invoker = true)
AS
SELECT
  organization_id,
  date_trunc('year', plan_date)   AS measurement_year,
  COUNT(*) FILTER (WHERE hedis_fuh_denominator)          AS fuh_denominator,
  COUNT(*) FILTER (WHERE hedis_fuh_7day_numerator)       AS fuh_7day_numerator,
  COUNT(*) FILTER (WHERE hedis_fuh_30day_numerator)      AS fuh_30day_numerator,
  COUNT(*) FILTER (WHERE hedis_fum_denominator)          AS fum_denominator,
  COUNT(*) FILTER (WHERE hedis_fum_7day_numerator)       AS fum_7day_numerator,
  COUNT(*) FILTER (WHERE hedis_fum_30day_numerator)      AS fum_30day_numerator
FROM cl_aftercare_plans
GROUP BY organization_id, date_trunc('year', plan_date);
Security: security_invoker = true — RLS on cl_aftercare_plans applies to the caller’s identity. Consumers must pass a valid authenticated session; hooks must include organization_id filter. Columns:
ColumnTypeDescription
organization_idUUIDTenant identifier
measurement_yearTIMESTAMPTZTruncated to year (Jan 1 of measurement year)
fuh_denominatorBIGINTCount of qualifying inpatient discharge events (FUH index events)
fuh_7day_numeratorBIGINTCount with qualifying follow-up within 7 days (different date from discharge)
fuh_30day_numeratorBIGINTCount with qualifying follow-up within 30 days
fum_denominatorBIGINTCount of qualifying ED visit events (FUM index events)
fum_7day_numeratorBIGINTCount with qualifying follow-up within 7 days (same date allowed)
fum_30day_numeratorBIGINTCount with qualifying follow-up within 30 days

​
Integration: CL-15 (Quality Measures Dashboard)

  • Pattern: Intra-core query via Supabase client hook
  • Consumer hook: useHedisFuhFumSummary(organizationId, measurementYear) — queries cl_hedis_fuh_fum_summary view
  • Permission gate: cl.hedis-tracking.view (rates panel), cl.hedis-tracking.export (export)
  • UI: Rates panel in CL-15 with measurement year selector; FUH 7-day/30-day rate and FUM 7-day/30-day rate displayed as percentages; CSV export
  • Status: 📋 Planned

​
Integration: CL-35 (Population Health — Care Gap)

  • Pattern: Intra-core query via Supabase client hook
  • Consumer hook: useHedisCareGaps(organizationId, measurementYear) — queries cl_hedis_fuh_fum_summary view; identifies patients with open denominator events (numerator not yet met)
  • Permission gate: cl.hedis-tracking.view
  • Status: 📋 Planned

​
Integration: PM Encounters

  • Pattern: Platform Integration Layer — @/platform/scheduling (useEncounterContext) and @/platform/types (EncounterContext)
  • Data accessed: encounter_type (FUH proxy: residential_daily; FUM proxy: crisis — see spec for full mapping), principal_diagnosis_code, visit_date
  • No direct cross-core import: All PM encounter data accessed via platform types
  • Status: 📋 Planned

​
Integration: PF-70 (Medical Terminology)

  • Pattern: Direct PF query (intra-platform)
  • Query: SELECT code FROM pf_icd10_codes WHERE metadata_tags @> '["hedis_fuh_qualifying"]'; similarly for hedis_fum_qualifying
  • Usage: Denominator flag logic evaluates principal diagnosis against PF-70 code lists at discharge/encounter save time
  • No hardcoded code lists — always query PF-70 at runtime
  • Status: 📋 Planned
  • Pre-Phase 1 verification: The metadata tags hedis_fuh_qualifying and hedis_fum_qualifying are not currently seeded in PF-70 (no existing spec or seed/migration contains them). Pre-Phase 1 checklist item: Seed PF-70 with NCQA MY 2025 ICD-10-CM lists tagged hedis_fuh_qualifying and hedis_fum_qualifying via a migration or seed file before denominator logic that queries pf_icd10_codes WHERE metadata_tags @> '["hedis_fuh_qualifying"]' or @> '["hedis_fum_qualifying"]' is released. See spec Pre-Phase 1 checklist.

​
Flag-Setting Logic (Application Layer)

Denominator evaluation (called at cl_aftercare_plans save): 
// Pseudocode — implement in service function
// encounterType uses actual pm_encounters.encounter_type values; FUH proxy = 'residential_daily', FUM proxy = 'crisis'
async function evaluateHedisDenominator(
  aftercarePlanId: string,
  encounterType: 'residential_daily' | 'crisis' | 'outpatient' | 'iop' | 'php' | 'group' | 'telehealth' | 'evaluation',
  principalDiagnosisCode: string,
  patientDob: Date,
  indexDate: Date
): Promise<{ fuhDenominator: boolean; fumDenominator: boolean }>
Numerator evaluation (called at cl_follow_up_contacts save): 
// Pseudocode
async function evaluateHedisNumerator(
  aftercarePlanId: string,
  followUpDate: Date,
  indexDate: Date,
  contactModality: 'in_person' | 'telehealth' | 'telephone' | string,
  measureType: 'fuh' | 'fum'
): Promise<{ met7Day: boolean; met30Day: boolean }>

​
Security Notes

  • All new columns on cl_aftercare_plans inherit existing RLS — no new policies needed
  • View uses security_invoker = true — caller’s RLS applies
  • 42 CFR Part 2: If the HEDIS export exposes SUD diagnosis-based flags to payers/AHCCCS, a patient authorization or QSOA is required before the export endpoint is enabled. Gate this in the export permission check.

​
References