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

# Integration Documentation

> Version: 2.1.0 Last Updated: 2026-03-23 Constitution Reference: Section 1.3 (Integration Patterns)

**Version:** 2.1.0\
**Last Updated:** 2026-03-23\
**Constitution Reference:** Section 1.3 (Integration Patterns)

> **Note:** This document consolidates content from the previous `INTEGRATION_CONTRACTS.md` (archived 2025-01-22). For detailed event and API contracts, see the specific contract files listed below.

This directory holds cross-core integration docs for the Encore Health OS Platform. Integrations should be documented here before implementation.

***

## Status Legend

All integration documentation uses consistent status indicators:

* ✅ **Implemented** - Fully implemented, tested, and production-ready
* 🟡 **In Progress** - Partially implemented, actively being developed
* 📝 **Planned** - Specified in specs but not yet implemented
* ❌ **Deprecated** - No longer recommended, will be removed in future version
* 🔄 **Breaking Change** - Recent breaking change, migration guide available

**Last Verified Dates:**

* All implemented integrations include "Last Verified" date
* Planned integrations include "Spec Reference" link
* Breaking changes include migration guide link

***

## Integration Doc Naming (Canonical)

| Use Case                       | Pattern                                               | Example                                                                                              |
| ------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Feature-specific (single core) | `{CORE}-##-{feature-kebab-case}-INTEGRATION.md`       | `CL-01-patient-chart-clinical-summary-INTEGRATION.md`, `HR-10-performance-management-INTEGRATION.md` |
| Cross-core (two cores)         | `{CORE1}-{CORE2}-{feature-kebab-case}-INTEGRATION.md` | `CL-PM-ENCOUNTER-TO-BILLING.md`, `RH-HR-INTEGRATION.md`                                              |
| Core-wide contract bundle      | `{CORE}_INTEGRATION_CONTRACTS.md`                     | `IT_INTEGRATION_CONTRACTS.md`, `HR_ATS_CONTRACTS.md`                                                 |

Use these patterns when creating new integration docs or when `validate-spec` / `generate-tasks` references integration doc paths. See `specs/_templates/INTEGRATION_CONTRACT_TEMPLATE.md` for the template.

**Maintenance and crosswalk:** [INTEGRATIONS\_CROSSWALK.md](./INTEGRATIONS_CROSSWALK.md) (spec links, dedupe guidance, known gaps).

### Bloat control for feature integration docs

For `{CORE}-##-*-INTEGRATION.md` files:

* Keep them **delta-focused** (feature-specific integration details only).
* Do not duplicate platform-wide rules that already live in `PLATFORM_INTEGRATION_LAYERS.md`, `EVENT_CONTRACTS.md`, or `API_CONTRACTS.md`.
* Prefer links to canonical contract docs over repeated boilerplate sections.

***

## Documentation Structure

### [Platform Integration Layers](./PLATFORM_INTEGRATION_LAYERS.md)

Shared utilities in `/src/platform/` that provide cross-core capabilities without violating architectural boundaries.

**Includes:**

* Forms Integration (PF-08)
* Workforce Integration
* Data Lookup (PF-15)
* Custom Fields (PF-16)
* Field Configuration (PF-17)
* Notifications (PF-10)
* Documents (PF-11)
* Reports (PF-12)
* **AI Integration (PF-27)**

### [LO Integration Contracts](./LO-INTEGRATION-OVERVIEW.md)

Leadership OS entry point: `lo_events`, goals/event specs (LO-16), links to `EVENT_CONTRACTS.md` LO sections.

### [IT Integration Contracts](./IT_INTEGRATION_CONTRACTS.md)

IT module event contracts, API contracts, and platform layer usage.

**Includes:**

* Asset lifecycle events (purchased, assigned, maintenance, disposed)
* License management events (created, renewed, expiring, compliance)
* Support ticketing events (created, status changed, SLA breached)
* Security events (incident, vulnerability, patch overdue)
* Procurement events (submitted, approved, received)
* API contracts for asset/vendor lookup

### [Event Contracts](./EVENT_CONTRACTS.md)

Asynchronous event-based integration patterns using PostgreSQL `pg_notify` and edge functions.

**Includes:**

* Event schema standards
* Implemented events registry
* Planned events registry
* Event delivery mechanism
* Event testing patterns

### [Event delivery guide](./EVENT_DELIVERY.md)

How to choose **table-driven FW automation** vs **HTTP event-consumer** vs **realtime** vs **outbound webhooks** (R-FW-12). Complements EVENT\_CONTRACTS.md.

### [API Contracts](./API_CONTRACTS.md)

Synchronous request-response APIs for direct data queries between cores.

**Includes:**

* API contract standards
* Implemented APIs
* Planned APIs
* Authentication and rate limiting
* Error handling patterns

### [External Integrations](./EXTERNAL_INTEGRATIONS.md)

Catalog of external (out-of-platform) integrations: clearinghouse, payer ePA, PDMP, HIE, EPCS, lab. Status 📝 Planned until implemented.

**Includes:**

* Clearinghouse (X12 837/835/270-271/276-277)
* Payer FHIR ePA (Da Vinci CRD/DTR/PAS)
* Arizona CSPMP (PDMP), Contexture (HIE), EPCS/Surescripts, RTPB, Lab/LIS

### [Cross-Core Integrations](./CROSS_CORE_INTEGRATIONS.md)

Integration matrix showing "who talks to whom" across all cores.

**Includes:**

* Integration matrix table
* Integration by core (publisher/consumer)
* Dependency graph
* Quick reference guide

### [Data Models](./DATA_MODELS.md)

Core data models and their integration points.

**Includes:**

* LO Core data model
* Integration points per core
* RLS security functions
* Key design decisions

***

## Source of Truth Precedence

For event names and schemas, the order of precedence is:

1. **Database/Registry:** `fw_workflow_events` table (definitive registry)
2. **TypeScript Types:** `KnownEventName` in `src/platform/events/types.ts` (must match registry)
3. **Documentation:** `EVENT_CONTRACTS.md` (narrative and payload schemas)
4. **Matrix:** `CROSS_CORE_INTEGRATIONS.md` (cross-references)

For API contracts:

1. **Implementation:** Edge functions and RPC functions (definitive)
2. **Documentation:** `API_CONTRACTS.md` (schemas and usage)
3. **Feature Docs:** `{CORE}-##-*-INTEGRATION.md` (detailed contracts)

***

## Integration Patterns Overview

The platform supports three integration patterns (Constitution Section 1.3):

1. **Pattern 1: Platform Integration Layer** - Shared utilities in `/src/platform/`
2. **Pattern 2: Event-Based Integration** - Async workflows via domain events
3. **Pattern 3: API Contracts** - Synchronous request-response with versioned schemas

**Prohibited:** Direct imports between cores (e.g., `import { x } from '@/cores/fa/...'` inside RH)

**Cross-Core FK Exception:** By default, cross-core references use UUID columns with no database FK. A scoped exception allows CL tables to reference `pm_encounters.id` via FK with `ON DELETE RESTRICT`. See [ADR-002](../decisions/ADR-002-cl-pm-cross-core-foreign-keys.md) and constitution §1.2, §5.2.7.

***

## Quick Reference

### When to Use Each Pattern

**Use Platform Integration Layer when:**

* Multiple cores need the same functionality
* You need reusable UI components or hooks
* The functionality is domain-agnostic
* Examples: Forms, Workforce, Data Lookup, Custom Fields

**Use Event-Based Integration when:**

* You need loose coupling between cores
* Workflows are asynchronous
* You want audit trails of state changes
* Examples: Resident admission → Billing account creation

**Use API Contracts when:**

* You need synchronous request-response
* Real-time data queries are required
* Event-driven patterns are not suitable
* Examples: Episode balance queries, Employee lookups

***

## Integration Checklist

Before implementing a new integration:

* [ ] Integration pattern chosen (Pattern 1, 2, or 3)
* [ ] Contract documented in appropriate file
* [ ] Schema defined (TypeScript types or JSON Schema)
* [ ] Versioning strategy defined
* [ ] RLS policies verified for tenant isolation
* [ ] Integration tests written
* [ ] Documentation updated
* [ ] Breaking changes approved (if applicable)

***

## Versioning Strategy

### Breaking Changes

Breaking changes to integration contracts MUST:

1. Be documented with version bump
2. Include migration guide for consumers
3. Maintain backward compatibility for 90 days minimum
4. Require explicit approval from technical owner

### Version Format

* **Platform Integration Layer:** Semantic versioning (e.g., v1.0.0 → v2.0.0)
* **Event Schemas:** Version in payload metadata (e.g., `event_version: '1.0'`)
* **API Contracts:** Version in URL path (e.g., `/api/v1/fa/resident-balance`)

***

## Testing Requirements

All integrations MUST have:

1. **Unit Tests:** Mock integration points
2. **Integration Tests:** Test actual event/API flow
3. **RLS Tests:** Verify tenant isolation
4. **E2E Tests:** Test complete cross-core workflows

***

## Anti-Patterns

### ❌ DO NOT:

1. **Direct Core Imports:**
   ```typescript theme={null}
   // ❌ WRONG
   import { BillingService } from '@/cores/fa/billing';
   ```

2. **Shared Database Tables:**
   ```sql theme={null}
   -- ❌ WRONG: Table owned by multiple cores
   CREATE TABLE shared_resident_billing (...);
   ```

3. **Hidden Dependencies:**
   ```typescript theme={null}
   // ❌ WRONG: Implicit dependency
   function getResidentBalance(id: uuid) {
     return supabase.from('fa_transactions').select(...); // Hidden FA dependency
   }
   ```

### ✅ DO:

1. **Use Platform Integration Layer:**
   ```typescript theme={null}
   // ✅ CORRECT
   import { FormEmbed } from '@/platform/forms';
   ```

2. **Publish Domain Events:**
   ```typescript theme={null}
   // ✅ CORRECT
   await publishEvent('rh_resident_admitted', { ... });
   ```

3. **Explicit API Contracts:**
   ```typescript theme={null}
   // ✅ CORRECT
   const balance = await faApi.getResidentBalance(residentId);
   ```

***

## Audit & Enforcement

Use `npm run audit:integration-contracts` to verify that every spec under `specs/{core}/specs/` is referenced in at least one canonical integration contract surface (or explicitly allowlisted as intra-core only).

```bash theme={null}
npm run audit:integration-contracts          # exit 1 on uncovered specs
npm run audit:integration-contracts:warn     # warn-only (used by validate:governance)
npm run audit:integration-contracts:report   # write reports/integration-contracts-gaps.json
```

**Allowlist:** `docs/architecture/integrations/.intra-core-only.json`. Each entry MUST include `id`, `rationale`, `owner`, and `added` (ISO date). The allowlist is reviewed quarterly by the Architecture team; default disposition is to add a contract row, not allowlist.

**Resolution per gap:** choose ONE of:

1. Add a row to `EVENT_CONTRACTS.md`, `API_CONTRACTS.md`, `PLATFORM_INTEGRATION_LAYERS.md`, or `CROSS_CORE_INTEGRATIONS.md`.
2. Append to a core bundle doc (`IT_INTEGRATION_CONTRACTS.md`, `FM_INTEGRATION_CONTRACTS.md`, `LO-INTEGRATION-OVERVIEW.md`, `HR_ATS_CONTRACTS.md`).
3. Create a feature-specific `{SPEC-ID}-{slug}-INTEGRATION.md`.
4. Add an entry to `.intra-core-only.json` with rationale (intra-core only with no cross-core surface).

CI calls the hard-fail variant via `npm run validate:governance` (promoted from warn-only on 2026-04-17 once the Q2 closure waves brought open gaps to 0; historical record archived at [`docs/archive/integrations/_GAP_TRIAGE_2026Q2.md`](../../archive/integrations/_GAP_TRIAGE_2026Q2.md)).

***

## Maintenance Guidelines

### Review Cycle

* **Quarterly:** Review all integration documentation for accuracy and re-run `npm run audit:integration-contracts`; fold any new gaps into next-sprint planning.
* **After each release:** Verify implemented integrations match documentation
* **Before breaking changes:** Update documentation and notify consumers

### Update Triggers

* New integration added
* Spec change affecting integration
* Breaking change to existing integration
* Implementation status change (Planned → Implemented)

### Ownership

* **Platform Integration Layers:** Platform Foundation team
* **Event Contracts:** Core teams (publisher owns documentation)
* **API Contracts:** Core teams (provider owns documentation)
* **Cross-Core Matrix:** Architecture team

### Quality Checklist

* [ ] Status indicators accurate (✅ Implemented / 📝 Planned)
* [ ] Code examples use real, working code
* [ ] All required fields documented
* [ ] Links to related specs and implementation code
* [ ] Last verified date included
* [ ] Breaking changes documented

***

## Related Documentation

* [Integration Examples](../patterns/INTEGRATION_EXAMPLES.md) - Code examples and patterns
* [Constitution](../../../constitution.md) (current: see docs/VERSIONS.md) - Engineering guardrails
* [AI Guide](../../../AI_GUIDE.md) (current: see docs/VERSIONS.md) - AI contribution guidelines
* [Architecture README](../index.md) - Architecture documentation overview

***

## Cross-References

### Integration Documentation Links

**Platform Integration Layers:**

* [Forms (PF-08)](./PLATFORM_INTEGRATION_LAYERS.md#pf-08-forms-integration-layer) - [Spec: FW-03](../../../specs/fw/archive/FW-03-automation-engine.md)
* [Workforce](./PLATFORM_INTEGRATION_LAYERS.md#pf-14-platform-workforce-integration-layer) - [Spec: HR-01](../../../specs/hr/specs/HR-01-employee-directory.md)
* [Data Lookup (PF-15)](./PLATFORM_INTEGRATION_LAYERS.md#pf-15-data-lookup-integration-layer) - [Implementation: `src/platform/data-lookup/`](../../../src/platform/data-lookup/)
* [Picklists (PF-15)](./PLATFORM_INTEGRATION_LAYERS.md#pf-15-picklist-system) - [Spec: PF-15](../../../specs/pf/specs/PF-15-picklist-system.md), [Implementation: `src/platform/picklists/`](../../../src/platform/picklists/)
* [Custom Fields (PF-16)](./PLATFORM_INTEGRATION_LAYERS.md#pf-16-custom-fields-integration-layer) - [Implementation: `src/platform/custom-fields/`](../../../src/platform/custom-fields/)
* [Field Configuration (PF-17)](./PLATFORM_INTEGRATION_LAYERS.md#pf-17-field-configuration-integration-layer) - [Implementation: `src/platform/field-config/`](../../../src/platform/field-config/)
* [Data Manager (PF-23/24/25/26)](./PLATFORM_INTEGRATION_LAYERS.md#pf-23-data-manager-integration-layer) - [Spec: PF-23](../../../specs/pf/specs/PF-23-data-manager-object-browser.md), [Spec: PF-24](../../../specs/pf/specs/PF-24-custom-objects.md), [Implementation: `src/platform/data-manager/`](../../../src/platform/data-manager/)
* [Notifications (PF-10)](./PLATFORM_INTEGRATION_LAYERS.md#pf-10-notifications-integration-layer) - [Implementation: `src/platform/notifications/`](../../../src/platform/notifications/)
* [Documents (PF-11)](./PLATFORM_INTEGRATION_LAYERS.md#pf-11-documents-integration-layer) - [Implementation: `src/platform/documents/`](../../../src/platform/documents/)
* [Reports (PF-12)](./PLATFORM_INTEGRATION_LAYERS.md#pf-12-reports-integration-layer) - [Implementation: `src/platform/reports/`](../../../src/platform/reports/)
* [AI (PF-27)](./PLATFORM_INTEGRATION_LAYERS.md#pf-27-platform-ai-integration-layer) - [Spec: PF-27](../../../specs/pf/specs/PF-27-platform-ai.md), [Implementation: `src/platform/ai/`](../../../src/platform/ai/)
* [Page Layouts + Conditional Logic (PF-31/PF-32)](./PF31_PF32_INTEGRATION.md) - [Spec: PF-31](../../../specs/pf/specs/PF-31-page-layouts.md), [Spec: PF-32](../../../specs/pf/specs/PF-32-conditional-field-logic.md)

**Event Contracts:**

* [FW-03 Form Submission Events](./EVENT_CONTRACTS.md#fw-03-form-submission-events) - [Spec: FW-03](../../../specs/fw/archive/FW-03-automation-engine.md)
* [HR-02 Credential Events](./EVENT_CONTRACTS.md#hr-02-credential-management-events) - [Spec: HR-02](../../../specs/hr/specs/HR-02-credentialing-compliance.md), [HR-04 Integration](../../../specs/hr/specs/HR-04-scheduling-capacity.md)
* [FA Financial Events](./EVENT_CONTRACTS.md#fa-02-vendor-bill-approved-events) - [Spec: FA-03](../../../specs/fa/specs/FA-03-accounts-payable.md)
* [RH Compliance Events](./EVENT_CONTRACTS.md#rh-06-compliance-events) - [Spec: RH-06](../../../specs/rh/specs/RH-06-compliance-staff-operations.md)

**RH Integration Contracts:**

* [RH-01 Bed Board & Census Integration](./bed-board-census-integration.md) - Bed board, `facility_type` (recovery\_housing | psychiatric\_residential | inpatient\_unit), census data for HR/PM, event payloads (`resident_admitted`, `resident_discharged`, `bed_assigned`, `bed_released`, `invoice_creation_requested`), CL current-residence API - [Spec: RH-01](../../../specs/rh/specs/RH-01-census-beds-episodes.md), [RH-01.1](../../../specs/rh/specs/RH-01.1-bed-board-facility-types.md)

**IT Integration Contracts:**

* [IT-01 Asset Management](./IT_INTEGRATION_CONTRACTS.md#it-01-asset-purchased-event) - [Spec: IT-01](../../../specs/it/specs/IT-01-it-asset-management.md)
* [IT-02 Support Ticketing](./IT_INTEGRATION_CONTRACTS.md#it-02-ticket-created-event) - [Spec: IT-02](../../../specs/it/specs/IT-02-it-support-ticketing.md)
* [IT-03 Vendor Management](./IT_INTEGRATION_CONTRACTS.md#it-03-contract-expiring-event) - [Spec: IT-03](../../../specs/it/specs/IT-03-it-vendor-management.md)
* [IT-04 License Management](./IT_INTEGRATION_CONTRACTS.md#it-04-license-created-event) - [Spec: IT-04](../../../specs/it/specs/IT-04-software-license-management.md)
* [IT-05 Security Compliance](./IT_INTEGRATION_CONTRACTS.md#it-05-security-incident-created-event) - [Spec: IT-05](../../../specs/it/specs/IT-05-it-security-compliance.md)
* [IT-06 Procurement](./IT_INTEGRATION_CONTRACTS.md#it-06-purchase-request-submitted-event) - [Spec: IT-06](../../../specs/it/specs/IT-06-it-procurement.md)

**FA Bank Feed Integrations:**

* [FA-20: Plaid Bank Integration](./plaid-integration.md) - [Spec: FA-20](../../../specs/fa/specs/FA-20-plaid-bank-integration.md) 📋

**FA Spend / Card Integrations:**

* [FA-30: Ramp Corporate Cards & Spend](./ramp-integration.md) - [Spec: FA-30](../../../specs/fa/specs/FA-30-ramp-corporate-cards-spend-integration.md) 📝

**HR External Integrations:**

* HR-20: Checkr Background Check Integration — superseded by HR-09-P5.2; see [Spec: HR-20](../../../specs/hr/specs/HR-20-checkr-background-check-integration.md) 📋 (archived: `docs/archive/architecture/integrations/HR-20-checkr-background-check-INTEGRATION.md`)

**API Contracts:**

* [FA-01 Episode Balance Query](./API_CONTRACTS.md#fa-01-episode-balance-query) - [Spec: RH-01](../../../specs/rh/specs/RH-01-census-beds-episodes.md), [FA-01](../../../specs/fa/specs/FA-01-chart-of-accounts.md)
* [HR-01 Employee Lookup](./API_CONTRACTS.md#hr-01-employee-lookup) - [Spec: RH-06](../../../specs/rh/specs/RH-06-compliance-staff-operations.md), [HR-01](../../../specs/hr/specs/HR-01-employee-directory.md)
* [IT Asset Lookup](./IT_INTEGRATION_CONTRACTS.md#it-01-asset-lookup-api) - [Spec: IT-01](../../../specs/it/specs/IT-01-it-asset-management.md)
* [IT Vendor Lookup](./IT_INTEGRATION_CONTRACTS.md#it-03-vendor-lookup-api) - [Spec: IT-03](../../../specs/it/specs/IT-03-it-vendor-management.md)

**Integration Matrix:**

* [Cross-Core Integration Matrix](./CROSS_CORE_INTEGRATIONS.md) - Visual overview of all integrations

**Code Examples:**

* [Integration Examples](../patterns/INTEGRATION_EXAMPLES.md) - Real code examples for all patterns

***

**Next Review:** 2026-04-22 (Quarterly)