> ## 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.

# Lead-to-Patient Conversion Pipeline — Integration Documentation

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

**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                         |

**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`

| 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 |

**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 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 |

***

## Platform Integration Layer Dependencies

| 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`