Skip to main content
Spec: specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md
Status: ✅ Complete
Last Updated: 2026-03-28

​
Overview

CE-29 formalizes the lead-to-patient and lead-to-resident conversion pipeline as FW-16 event contracts. CE publishes conversion events; PM-01 and RH-01 consume them to create patient/resident records.

​
Integration Pattern

Pattern: Event-Based Integration (Pattern 2 — constitution §1.3) CE publishes events via FW-16 workflow framework. No direct core-to-core imports. Downstream cores (PM, RH) subscribe to events and create entities independently.

​
Event Contracts

​
ce_lead_converted_to_patient

Payload: See specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md § Event Contracts for full JSON schema. Key fields (IDs only — no PHI): organization_id, lead_id, contact_id, patient_id, correlation_id, converted_to_type, converted_by, converted_at

​
ce_lead_converted_to_resident

Payload: See spec for full JSON schema. Key fields (IDs only — no PHI): organization_id, site_id, lead_id, contact_id, resident_id, correlation_id, converted_to_type, converted_by, converted_at

​
Data Mapping

Note: Event payloads carry IDs only (no PHI). The PM/RH subscribers fetch contact data server-side using service role via ce_contacts join on contact_id. Data mapping is performed server-side in the event-consumer edge function.

​
CE Lead → PM Patient (server-side mapping)

The handleLeadConvertedToPatient subscriber in event-consumer reads the ce_contacts record for the lead’s contact_id and maps fields to pm_patients:

​
CE Lead → RH Resident (server-side mapping)

The handleLeadConvertedToResident subscriber reads ce_contacts and maps to the RH resident record:

​
Platform Integration Layer Dependencies

​
Subscriber Responsibilities

​
PM-01 (Patient Registration)

  • Receive ce_lead_converted_to_patient event
  • Check idempotency via correlation_id
  • Create pm_patients record with mapped fields
  • Set status to awaiting_intake_appointment
  • Preserve ce_lead_id FK for audit trail

​
RH-01 (Admission Wizard)

  • Receive ce_lead_converted_to_resident event
  • Check idempotency via correlation_id
  • Create rh_residents record with mapped fields
  • Trigger bed assignment workflow or waitlist

​
Security Considerations

  • PHI in payloads: Events carry PHI (name, DOB, health data). Encrypted in transit (TLS). No PHI in logs.
  • 42 CFR Part 2: If SUD data present, consent must be verified before conversion.
  • RLS: ce_lead_conversions table has org-scoped RLS via SECURITY DEFINER function (ce_can_access_lead_conversions). FORCE ROW LEVEL SECURITY enabled. Policies restricted TO authenticated.
  • Immutability: Audit table is INSERT-only; no UPDATE/DELETE policies.
  • rh_residents FK deferred: resident_id is plain UUID (no FK) until RH-01 creates rh_residents.

​
Migration Notes

​
CE-17 Alignment

CE-17 uses ce_lead_converted (generic event name). CE-29 introduces specific event names (ce_lead_converted_to_patient, ce_lead_converted_to_resident). Phase 1 of CE-29 includes a CE-17 review to align or migrate to the new event model. See spec Clarifications for details.

​
References

  • Spec: specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md
  • Plan: specs/ce/plans/CE-29-lead-to-patient-conversion-pipeline-PLAN.md
  • Tasks: specs/ce/tasks/CE-29-TASKS.md
  • CE-17: specs/ce/specs/CE-17-ce-rh-admission-handoff.md
  • Event Contracts: docs/architecture/integrations/EVENT_CONTRACTS.md
  • Cross-Core Matrix: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md