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

PM-07 associates charges with individual encounters, but there is no platform-level “episode of care” grouping. For VBP contracts, utilization review, and FA cost analysis, organizations need to group encounters into episodes (e.g. “residential admission Jan 15 – Feb 28, 2026” or “IOP episode March 2026”). CL holds episode-relevant data (admission/discharge in CL-29, program enrollment in CL-27) but PM and FA cannot query by episode. This contract defines the cl_episodes_of_care data model and platform API getEpisodeContext() so PM and FA can attribute encounters and claims to episodes. Regulatory driver: AHCCCS VBP episode-based payment models; SAMHSA episode analytics; HEDIS follow-up measures (FUH uses index hospitalization as episode anchor).

​
Integration Type

  • Platform layer + data model: CL owns episode definition and table; platform exposes read API for PM and FA.
  • No events required for basic use: PM/FA call getEpisodeContext(patientId, date) or getEpisodesForChart(chartId) when needed. Optional: emit event when episode is closed for analytics.

​
Data Model (CL-Owned)

​
Table: cl_episodes_of_care

Episodes of care per chart (e.g. residential stay, IOP episode, outpatient episode).
  • id UUID PRIMARY KEY
  • organization_id UUID NOT NULL
  • site_id UUID (optional)
  • chart_id UUID NOT NULL REFERENCES cl_patient_charts(id) ON DELETE RESTRICT
  • episode_type TEXT NOT NULL (e.g. ‘residential’, ‘iop’, ‘php’, ‘outpatient’)
  • episode_start DATE NOT NULL
  • episode_end DATE (null if ongoing)
  • primary_diagnosis TEXT or ICD code (optional)
  • disposition TEXT (optional)
  • program_id or program name (optional; link to CL-27 program)
  • custom_fields JSONB DEFAULT ''
  • created_at, updated_at, created_by, updated_by
  • RLS: Enable ROW LEVEL SECURITY on cl_episodes_of_care. Policies: (1) organization_isolation — restrict rows to auth.user_organization_id() or equivalent so users see only their org’s episodes; (2) chart_access — require that the related cl_patient_charts row exists and has the same organization_id (enforces chart-level access). All UPDATE policies MUST use WITH CHECK. Reference existing CL RLS patterns for cl_patient_charts.
Indexes: organization_id, chart_id, episode_start, episode_end.

​
Platform Integration Layer

​
API: getEpisodeContext

Provider: CL via Platform Integration Layer
Consumers: PM, FA
Status: 📝 Planned

​
Purpose

Given a patient/chart and date (or encounter), return the episode(s) that contain that date so PM can tag encounters with episode_id and FA can attribute cost/claims to episodes.

​
Contract

  • Location: @/platform/clinical or @/platform/types + platform function — see PLATFORM_INTEGRATION_LAYERS.md.
  • Single-episode lookup: getEpisodeContext(organizationId, chartId, date): Promise<EpisodeOfCare | null> — returns the single episode that contains the given date for the chart, or null if none. Purpose: PM/FA need to tag an encounter with its episode.
  • Multi-episode query: getEpisodesForChart(organizationId, chartId, options?: { start?, end? }): Promise<EpisodeOfCare[]> — returns all episodes for the chart, optionally filtered by date range. Purpose: list episodes for a patient or date range.
  • Return: Episode id, episode_type, episode_start, episode_end, primary_diagnosis, disposition (no PHI beyond what caller already has access to for that chart).
  • Security: Organization and chart scoped; caller must have access to chart; use SECURITY DEFINER RPC or platform layer that enforces RLS.

​
Usage (PM/FA)

  • PM: When creating or displaying encounter, call getEpisodeContext(chartId, encounterDate) and store episode_id on encounter (or in custom_fields) for billing and reporting.
  • FA: When aggregating cost or claims by episode, join to episode via encounter’s episode_id or getEpisodeContext for date range.

​
Implementation Notes

  • CL: Create migration for cl_episodes_of_care; populate from CL-29 discharge/aftercare and CL-27 program enrollment where applicable; or allow manual episode creation. Expose getEpisodeContext via platform layer.
  • PM: Add episode_id (or equivalent) to encounter where possible; call platform API to resolve episode for encounter date.
  • FA: Use episode_id on encounters for episode-based reporting and VBP attribution.

​
Testing Requirements

  • cl_episodes_of_care RLS: org and chart isolation
  • getEpisodeContext(chartId, date) returns correct episode when date falls within episode range; null when no episode
  • PM can attach episode_id to encounter; FA can aggregate by episode

​
References