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

# Platform Integration Hooks — Integration Documentation

> Spec: CL-39-platform-integration-layer-implementation.md Status: ✅ Complete Last Updated: 2026-03-29

**Spec:** [CL-39-platform-integration-layer-implementation.md](../../../specs/cl/specs/CL-39-platform-integration-layer-implementation.md)
**Status:** ✅ Complete
**Last Updated:** 2026-03-29

***

## Overview

CL-39 implements **5 core platform hooks** that provide cross-core data access without direct CL↔PM imports per constitution §1.3. **[CL-41](../../../specs/cl/specs/CL-41-payer-billing-suggestion-overrides.md)** adds **billing override composition** (`useBillingOverrides`, `applyBillingOverrides`, `useBillingWithOverrides`) that reads `pm_billing_suggestion_rules` and layers on top of `useBillingAdapter`—listed in the table below for a single integration view (6 hook rows total: five CL-39 + CL-41 composition).

| Hook                                              | Location                | Pattern                             | Consumers                             |
| ------------------------------------------------- | ----------------------- | ----------------------------------- | ------------------------------------- |
| `usePatientContext(chartId)`                      | `@/platform/clinical`   | React Query (read)                  | PM-10, PM-12, CL-16, CL-13            |
| `useEncounterContext(encounterId)`                | `@/platform/scheduling` | React Query (read)                  | CL-04, CL-14, PM-07, PM-14            |
| `useBillingAdapter(input)`                        | `@/platform/clinical`   | React Query (pure logic)            | CL-04, CL-14, CL-13, PM-07            |
| `useBillingOverrides` / `useBillingWithOverrides` | `@/platform/clinical`   | React Query (read PM rules) + merge | CL-41; CL-04, CL-14 when wired        |
| `useDocumentExport()`                             | `@/platform/clinical`   | React Mutation                      | CL-16, CL-20, PM (claims attachments) |
| `useExportStatus(exportId)`                       | `@/platform/clinical`   | React Query (polling)               | CL-16, CL-20                          |

***

## Platform Layer Usage

* **`@/platform/clinical`** — Barrel export from `src/platform/clinical/index.ts`
* **`@/platform/scheduling`** — Barrel export from `src/platform/scheduling/index.ts`
* **`@/platform/types`** — Shared types: `PatientContext`, `EncounterContextHookRow`, `BillingInput`, `BillingSuggestion`, `DocumentExportRequest`, `DocumentExportResult`

***

## Integration Points

### Data Sources (Read)

| Hook                  | Tables                                                                  | Access Pattern                                                   |
| --------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `usePatientContext`   | `cl_patient_charts`, `cl_problems`, `cl_risk_screenings`, `cl_consents` | Supabase RLS; parallel selects by `chart_id` + `organization_id` |
| `useEncounterContext` | `pm_encounters`, `pm_appointments`, `pf_profiles`                       | Supabase nested `.select()` join; FK per ADR-002                 |
| `useDocumentExport`   | `cl_data_exchange_log` (write)                                          | Wraps CL-20 export backend; writes audit row                     |
| `useExportStatus`     | `cl_data_exchange_log` (read)                                           | Single row by `id`                                               |

### Dependencies

| Dependency              | Role                                                     |
| ----------------------- | -------------------------------------------------------- |
| CL-11 `useConsentCheck` | Consent gate for all exports                             |
| CL-20 export backend    | Document generation logic wrapped by `useDocumentExport` |
| ADR-002                 | FK exception for `pm_encounters.id` references from CL   |

***

## Event Contracts

No new events published or consumed. CL-39 hooks are synchronous React Query hooks.

***

## API Contracts

No edge functions or REST APIs. All hooks are client-side React Query integrations.

***

## Security

* All DB-backed hooks enforce RLS via Supabase client (no service-role keys from browser)
* PHI (demographics, diagnoses, risk level) accessed only through `usePatientContext`; never logged as raw field values
* Export signed URLs: 15-minute TTL (`EXPORT_URL_TTL_MINUTES`)
* Error sanitization: `sanitizeErrorMessage` on all error paths
* Consent gate: `useConsentCheck` (CL-11) enforced before any export

***

## Contract Validation Checklist

* [ ] All CL-39 hooks (and CL-41 override hooks where in scope) exported from barrel files
* [ ] Shared types in `@/platform/types` (no duplication in cores)
* [ ] `npm run check-architecture` passes (0 cross-core violations)
* [ ] RLS cross-org isolation verified (`npm run test:rls`)
* [ ] Billing adapter unit tests cover all CPT mapping scenarios
* [ ] Export audit log written to `cl_data_exchange_log`

***

## References

* [CL-39 Spec](../../../specs/cl/specs/CL-39-platform-integration-layer-implementation.md)
* [CL-39 Plan](../../../specs/cl/plans/CL-39-platform-integration-layer-implementation-PLAN.md)
* [ADR-002](../decisions/ADR-002-cl-pm-cross-core-foreign-keys.md)
* [CL-PM Event Wiring](./CL-PM-EVENT-WIRING-INTEGRATION.md)
* [Platform Integration Layers](./PLATFORM_INTEGRATION_LAYERS.md)