Integration Contract: Group Encounter Generation

​

Overview

​

Ownership Boundaries

​

Event Contracts

​

Consumed Events

• Publisher: CL-14
• Existing Subscriber: PM-07
• New Subscriber: CL-14-EN-01 (encounter generation handler)
• Purpose: Triggers creation of cl_group_encounter_generations records per present/partial attendee
• Idempotency: Insert-once by (organization_id, group_session_id, patient_id) using ON CONFLICT (organization_id, group_session_id, patient_id) DO NOTHING; replayed events are skipped and existing rows are not mutated.

​

Published Events

• Publisher: CL-14-EN-01
• Subscriber: PM-07
• Channel: cl_events
• Payload Schema:
  {
    session_id: string; // UUID
    approved_generations: Array<{
      generation_id: string; // UUID
      encounter_id: string; // UUID
      patient_id: string; // UUID
      proposed_cpt_code: string;
      duration_minutes: number;
      modifiers: string[];
    }>;
    organization_id: string; // UUID
  }
  
• Purpose: Triggers charge creation in PM-07 for approved encounter generations
• Trigger: Batch approval action in review UI (single or bulk)

​

Platform Integration Layer Usage

​

Data Flow

CL-14 group note submitted
  → cl_group_session_documented event (existing)
    → CL-14-EN-01 handler:
       1. For each present/partial attendee:
          a. Create pm_encounters record (encounter_type: 'group')
          b. Propose CPT code (PF-96 jurisdiction + group type)
          c. Insert cl_group_encounter_generations row (status: pending_review)
       2. Absent attendees: tracked but no encounter generated
    → Batch review UI (CL-14-EN-01)
       1. Supervisor/billing coordinator reviews generated encounters
       2. Approve → status: approved → publish cl_group_encounters_approved
       3. Reject → status: rejected (with reason); no charge created
    → PM-07 consumes cl_group_encounters_approved
       1. Creates charges per approved generation
       2. Final CPT/modifier/units determined by PM-07 fee schedule

​

Cross-Core References

​

Security & Compliance

• RLS: cl_group_encounter_generations has RLS with pf_has_org_access SECURITY DEFINER helper
• 42 CFR Part 2: SUD group encounters inherit Part 2 protections; consent verification before display in batch review
• PHI Minimization: Generation tracking stores patient_id reference only; no clinical content
• Permission Keys: cl.group-encounter-generation.view, .approve, .edit

​

Related Documents

• CL-14-EN-01 Spec
• CL-PM-GROUP-SESSIONS.md
• CL-PM-ENCOUNTER-TO-BILLING.md
• CROSS_CORE_INTEGRATIONS.md