Encore OS — Documentation

Version: 1.1.1 Last Updated: 2026-05-31 Status: ✅ Reviewed (pre-implementation); column names reconciled to as-shipped schema 2026-05-31 (issue #548) Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns) Source: CL-PM-SPEC-REVIEW Finding 5.3, Pre-Implementation Review 2026-02-22

Overview

Telehealth workflows span CL and PM with overlapping data. This contract defines which core owns which data and how they integrate without direct cross-core dependencies.

Ownership Boundaries

Data	Owner	Spec	Rationale
Session platform/URL	PM-13	`pm_telehealth_sessions`	Operational/scheduling concern
Session status & modality	PM-13	`pm_telehealth_sessions.session_status`, `telehealth_modality`	Session lifecycle concern
Appointment telehealth flag	PM-03	`pm_appointments.is_telehealth`	Scheduling concern
Clinical documentation fields	CL-04	`cl_progress_notes.is_telehealth`, `telehealth_modality`, `patient_location`, `provider_location`	Clinical documentation concern
Modifier determination	PM-07	Charge capture logic	Billing concern
Place of Service code	PM-07	Charge capture logic	Billing concern

Integration Flow

PM-03: Appointment created with is_telehealth = true
  ↓
PM-13: Telehealth session created, platform link generated
  (pm_telehealth_sessions.appointment_id → pm_appointments.id)
  (session_status = 'scheduled', telehealth_modality set)
  ↓
PM-13: Session starts → session_status = 'active'
  → publishes telehealth_session_started event
  ↓
PM-03: Encounter created when appointment starts
  (pm_encounters.id created)
  ↓
PM-13: Session ends → session_status = 'completed'
  → publishes telehealth_session_completed event
  (payload includes telehealth_modality, patient_location, provider_location)
  ↓
CL-04: Clinician documents visit, captures telehealth clinical fields
  (cl_progress_notes with is_telehealth, modality, locations)
  ↓
CL-04: Note finalized → clinical_note_finalized event
  (includes is_telehealth, telehealth_modality in payload)
  ↓
PM-07: Charge capture applies telehealth modifiers
  (95 for synchronous audio/video, FQ for audio-only, GQ for store-forward)
  (POS = 10 for patient at home, 02 for telehealth)

Telehealth Fields by Core

PM-13: `pm_telehealth_sessions` (Operations)

Column names below mirror the live schema in src/integrations/supabase/types.ts (reconciled 2026-05-31, issue #548).

appointment_id   → pm_appointments(id)
encounter_id     → pm_encounters(id)     -- link to encounter
platform_name    TEXT                     -- 'zoom' | 'doxy' | 'teams' etc.
session_url      TEXT
session_status   TEXT                     -- 'scheduled' | 'waiting' | 'active' | 'completed' | 'cancelled' | 'failed' | 'no_show'
telehealth_modality telehealth_modality   -- enum: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring' (sole modality field)
patient_location TEXT                     -- State/location of patient
provider_location TEXT                    -- State/location of provider
scheduled_start  TIMESTAMPTZ              -- planned session window
scheduled_end    TIMESTAMPTZ
actual_start     TIMESTAMPTZ              -- actual session start (supersedes the draft patient/provider_joined_at)
actual_end       TIMESTAMPTZ              -- actual session end (supersedes the draft session_ended_at)
consent_obtained BOOLEAN                  -- consent flag (paired with consent_obtained_at)
duration_minutes INTEGER

CL-04: `cl_progress_notes` (Clinical Documentation)

is_telehealth       BOOLEAN DEFAULT false
telehealth_modality TEXT     -- 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring'
patient_location    TEXT     -- State/location of patient during session
provider_location   TEXT     -- State/location of provider during session
place_of_service    TEXT     -- Overrides default POS for telehealth

PM-07: Charge Capture Logic (Billing)

Modifier auto-application rules based on clinical_note_finalized event payload:

Telehealth Modality	Modifier	POS Code
`audio_video`	95	10 (home) or 02 (other)
`audio_only`	FQ (or 93 per payer)	10 or 02
`store_forward`	GQ	02

Events

PM-13 Events (New)

`telehealth_session_started`

Published when pm_telehealth_sessions.session_status transitions to 'active'.

payload: {
  session_id: string;
  appointment_id: string;
  encounter_id?: string;
  organization_id: string;
  telehealth_modality: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  platform_name: string;
}

`telehealth_session_completed`

Published when pm_telehealth_sessions.session_status transitions to 'completed'.

payload: {
  session_id: string;
  appointment_id: string;
  encounter_id?: string;
  organization_id: string;
  telehealth_modality: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  patient_location?: string;
  provider_location?: string;
  duration_minutes?: number;
}

Existing Event: `clinical_note_finalized` (CL-04 → PM-07)

The clinical_note_finalized event (defined in CL-PM-ENCOUNTER-TO-BILLING.md) includes telehealth fields:

payload: {
  // ... other fields
  is_telehealth: boolean;
  telehealth_modality?: 'audio_video' | 'audio_only' | 'store_forward' | 'remote_monitoring';
  patient_location?: string;
  provider_location?: string;
}

PM-07 uses these to determine modifiers and POS without querying CL tables directly.

`pm_appointments.telehealth_url` Deprecation

PM-03 Phase 1 stores a manual telehealth_url TEXT on pm_appointments. Once PM-13 is active for an organization:

Write path: Join links are generated into pm_telehealth_sessions.session_url via the edge function.
Read path: UI should prefer pm_telehealth_sessions.session_url when a linked session exists; fall back to pm_appointments.telehealth_url for appointments without a PM-13 session.
Migration path: No data migration needed. The telehealth_url column remains for orgs not using PM-13.
Sunset date: The telehealth_url column on pm_appointments will be deprecated once all organizations are migrated to PM-13. Target sunset: 2026-Q4. After sunset, the column will be dropped in a future migration.
Warning mechanism: Type accessors that expose pm_appointments.telehealth_url MUST include /** @deprecated Use pm_telehealth_sessions.session_url instead. Sunset: 2026-Q4. */ JSDoc annotations. Runtime access without a linked PM-13 session should emit a structured warning (deprecated_column_access: telehealth_url) to support migration tracking.

Event Registration

The following events should be registered in fw_workflow_events for automation support:

Event Name	Channel	Registration Status
`telehealth_session_started`	`cl_pm_events`	📝 Planned
`telehealth_session_completed`	`cl_pm_events`	📝 Planned

Clinical compliance layer (CL-24)

Scope: Per-patient telehealth consent (annual, audit-immutable), pre-session safety checklist, per-session compliance record (jurisdiction, modality, connectivity), daily expiry cron, and cl_telehealth_session_safety_completed signal back to PM-13. Contract: CL-24 Integration Contract Important: CL-24 does NOT publish modifier data. PM-07 continues to read is_telehealth, telehealth_modality, patient_location, and provider_location from CL-04’s clinical_note_finalized event — that pathway is unchanged by CL-24. CL-24 is a clinical compliance wrapper around the PM-13 vendor session, not a substitute for the CL-04 → PM-07 billing-data flow defined above. CL-24 surfaces in the PM-13 surface through @/platform/clinical/telehealth/ exports (e.g., TelehealthConsentBadge, useTelehealthSessionsByPmIds); PM-13 never imports from @/cores/cl/*.

Cross-Reference

Spec	Responsibility
PM-03	Flags appointments as telehealth
PM-13	Manages telehealth platform session, publishes session events
CL-04	Documents clinical telehealth fields
CL-24	Clinical compliance layer (consent + safety checklist + jurisdiction + connectivity); does not publish modifier data
PM-07	Applies telehealth billing modifiers from `clinical_note_finalized`
CL-PM-ENCOUNTER-TO-BILLING	Event carries telehealth data from CL-04 to PM-07

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

CL-PM Integration Contract: Telehealth

Overview

Ownership Boundaries

Integration Flow

Telehealth Fields by Core

PM-13: `pm_telehealth_sessions` (Operations)

CL-04: `cl_progress_notes` (Clinical Documentation)

PM-07: Charge Capture Logic (Billing)

Events

PM-13 Events (New)

`telehealth_session_started`

`telehealth_session_completed`

Existing Event: `clinical_note_finalized` (CL-04 → PM-07)

`pm_appointments.telehealth_url` Deprecation

Event Registration

Clinical compliance layer (CL-24)

Cross-Reference

​Overview

​Ownership Boundaries

​Integration Flow

​Telehealth Fields by Core

​PM-13: pm_telehealth_sessions (Operations)

​CL-04: cl_progress_notes (Clinical Documentation)

​PM-07: Charge Capture Logic (Billing)

​Events

​PM-13 Events (New)

​telehealth_session_started

​telehealth_session_completed

​Existing Event: clinical_note_finalized (CL-04 → PM-07)

​pm_appointments.telehealth_url Deprecation

​Event Registration

​Clinical compliance layer (CL-24)

​Cross-Reference

Overview

Ownership Boundaries

Integration Flow

Telehealth Fields by Core

PM-13: `pm_telehealth_sessions` (Operations)

CL-04: `cl_progress_notes` (Clinical Documentation)

PM-07: Charge Capture Logic (Billing)

Events

PM-13 Events (New)

`telehealth_session_started`

`telehealth_session_completed`

Existing Event: `clinical_note_finalized` (CL-04 → PM-07)

`pm_appointments.telehealth_url` Deprecation

Event Registration

Clinical compliance layer (CL-24)

Cross-Reference