Population Health & Care Gap Management — Integration Documentation

Spec: specs/cl/specs/CL-35-population-health-care-gap-management.md Status: Phase 2/3 ✅ Complete (2026-04-01) — Phase 2 schema parity gap closed 2026-05-11: closure_type + risk_score_at_identification deployed on cl_care_gaps; 4 pop_health_* settings columns deployed on cl_module_settings; UI wired (CloseGapDialog Select, GapDetailSheet display incl. system auto-close branch); RLS test stubs and deriveCareGapCloseStatus unit tests added. Last Updated: 2026-05-11

---

​

Integration Overview

CL-35 is a consumer of existing CL data sources (CL-02, CL-03, CL-07, CL-10, CL-15, CL-22, CL-26, CL-29) and a producer of new population health data (risk scores, care gaps, quality measure periods). It integrates cross-core with FA (Finance) via event contract for VBP payment adjustment and with FW (Workflow) via care gap closure events.

---

​

Platform Foundation Dependencies

---

​

CL-Internal Data Sources (Read-Only)

---

​

Event Contracts

​

Events Published

1. cl_quality_measure_period_calculated

• Publisher: CL-35 (Phase 3)
• Subscribers: FA (Finance — VBP payment adjustment)
• Payload Schema:
  {
    organization_id: string;        // UUID
    measure_id: string;             // e.g. 'AMM', 'FUH'
    measure_type: 'HEDIS' | 'MA_STARS';
    period_start: string;           // ISO date
    period_end: string;             // ISO date
    denominator_count: number;
    numerator_count: number;
    rate: number;                   // 0.0000–1.0000
    calculated_at: string;          // ISO timestamp
  }
  
• Integration doc: CL-FA-VBP-QUALITY-DATA-PIPELINE.md

2. cl_care_gap_closed (Phase 2)

• Publisher: CL-35
• Subscribers: FW (Workflow — event automation)
• Channel: cl_events
• Integration doc: CL-FW-EVENT-AUTOMATION-INTEGRATION.md

​

Events Consumed

None — CL-35 reads data via direct queries to CL-internal tables, not events.

---

​

API Contracts

No external APIs exposed. Internal edge functions:

• cl-risk-stratification-cron: Batch risk score calculation (Phase 2)
• cl-care-gap-rules: Batch gap rule evaluation (Phase 1)
• cl-hedis-measure-calculation: HEDIS period calculation (Phase 3)
• Population dashboard aggregate queries (Phase 3)

---

​

Platform Integration Layer Usage

---

​

Security Considerations

• All data access RLS-gated via cl_has_org_access(organization_id, auth.uid())
• Population dashboard aggregates enforce small-cell suppression (n < 5 → "<5")
• No PHI in event payloads (quality measure periods are aggregate counts)
• Edge function logs must not contain patient identifiers

---

​

References

• CL-35 Spec
• CL-FA-VBP-QUALITY-DATA-PIPELINE.md
• CL-FW-EVENT-AUTOMATION-INTEGRATION.md
• CROSS_CORE_INTEGRATIONS.md