Integration Documentation

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.

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.

​

Status Legend

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

• All implemented integrations include “Last Verified” date
• Planned integrations include “Spec Reference” link
• Breaking changes include migration guide link

​

Integration Doc Naming (Canonical)

​

Bloat control for feature integration docs

• 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

• 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

​

IT Integration Contracts

• 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 schema standards
• Implemented events registry
• Planned events registry
• Event delivery mechanism
• Event testing patterns

​

Event delivery guide

​

API Contracts

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

​

External Integrations

• 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

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

​

Data Models

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

​

Source of Truth Precedence

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)

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

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

​

Quick Reference

​

When to Use Each Pattern

• 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

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

• 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

• 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

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

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:
   // ❌ WRONG
   import { BillingService } from '@/cores/fa/billing';
   
2. Shared Database Tables:
   -- ❌ WRONG: Table owned by multiple cores
   CREATE TABLE shared_resident_billing (...);
   
3. Hidden Dependencies:
   // ❌ WRONG: Implicit dependency
   function getResidentBalance(id: uuid) {
     return supabase.from('fa_transactions').select(...); // Hidden FA dependency
   }
   

​

✅ DO:

1. Use Platform Integration Layer:
   // ✅ CORRECT
   import { FormEmbed } from '@/platform/forms';
   
2. Publish Domain Events:
   // ✅ CORRECT
   await publishEvent('rh_resident_admitted', { ... });
   
3. Explicit API Contracts:
   // ✅ CORRECT
   const balance = await faApi.getResidentBalance(residentId);
   

​

Audit & Enforcement

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

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

​

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 - Code examples and patterns
• Constitution (current: see docs/VERSIONS.md) - Engineering guardrails
• AI Guide (current: see docs/VERSIONS.md) - AI contribution guidelines
• Architecture README - Architecture documentation overview

​

Cross-References

​

Integration Documentation Links

• Forms (PF-08) - Spec: FW-03
• Workforce - Spec: HR-01
• Data Lookup (PF-15) - Implementation: src/platform/data-lookup/
• Picklists (PF-15) - Spec: PF-15, Implementation: src/platform/picklists/
• Custom Fields (PF-16) - Implementation: src/platform/custom-fields/
• Field Configuration (PF-17) - Implementation: src/platform/field-config/
• Data Manager (PF-23/24/25/26) - Spec: PF-23, Spec: PF-24, Implementation: src/platform/data-manager/
• Notifications (PF-10) - Implementation: src/platform/notifications/
• Documents (PF-11) - Implementation: src/platform/documents/
• Reports (PF-12) - Implementation: src/platform/reports/
• AI (PF-27) - Spec: PF-27, Implementation: src/platform/ai/
• Page Layouts + Conditional Logic (PF-31/PF-32) - Spec: PF-31, Spec: PF-32

• FW-03 Form Submission Events - Spec: FW-03
• HR-02 Credential Events - Spec: HR-02, HR-04 Integration
• FA Financial Events - Spec: FA-03
• RH Compliance Events - Spec: RH-06

• RH-01 Bed Board & Census Integration - 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, RH-01.1

• IT-01 Asset Management - Spec: IT-01
• IT-02 Support Ticketing - Spec: IT-02
• IT-03 Vendor Management - Spec: IT-03
• IT-04 License Management - Spec: IT-04
• IT-05 Security Compliance - Spec: IT-05
• IT-06 Procurement - Spec: IT-06

• FA-20: Plaid Bank Integration - Spec: FA-20 📋

• FA-30: Ramp Corporate Cards & Spend - Spec: FA-30 📝

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

• FA-01 Episode Balance Query - Spec: RH-01, FA-01
• HR-01 Employee Lookup - Spec: RH-06, HR-01
• IT Asset Lookup - Spec: IT-01
• IT Vendor Lookup - Spec: IT-03

• Cross-Core Integration Matrix - Visual overview of all integrations

• Integration Examples - Real code examples for all patterns