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.
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
| Field | Value |
|---|
| Publisher | CE (ce_leads_service) |
| Subscribers | PM-01 (patient registration), PM-38 (appointment automation), Analytics |
| Delivery | At-least-once (FW-16) |
| Idempotency | correlation_id — subscribers must deduplicate |
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
| Field | Value |
|---|
| Publisher | CE (ce_leads_service) |
| Subscribers | RH-01 (admission), PM-39 (waitlist), Analytics |
| Delivery | At-least-once (FW-16) |
| Idempotency | correlation_id — subscribers must deduplicate |
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 Contact Field | PM Patient Field | Notes |
|---|
first_name | first_name | Direct mapping |
last_name | last_name | Direct mapping |
phone | phone | Direct mapping |
email | email | Direct mapping |
CE Lead → RH Resident (server-side mapping)
The handleLeadConvertedToResident subscriber reads ce_contacts and maps to the RH resident record:
| CE Contact Field | RH Resident Field | Notes |
|---|
first_name | first_name | Direct mapping |
last_name | last_name | Direct mapping |
site_id (from lead) | site_id | Direct mapping |
| Layer | Usage |
|---|
| FW-16 (Workflow Framework) | Event registration, publishing, subscriber management |
| PF-01 (Organizations) | organization_id for multi-tenant isolation |
| PF-30 (RBAC) | Permission keys (ce.lead-conversions.*) |
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
