Version: 2.3.1Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Last Updated: 2026-03-29
Constitution Reference: Section 1.3 (Integration Patterns - Pattern 1)
📌 For latest layer status, seePlatform Integration Layer provides shared capabilities that multiple cores need without violating architectural boundaries. All cores import fromsrc/platform/AGENTS.md— This document provides detailed integration patterns;src/platform/AGENTS.mdhas the authoritative implementation status.
/src/platform/ instead of directly from other cores.
Quick Reference
| Layer | Location | Purpose | Status |
|---|---|---|---|
| PF-08 | @/platform/forms | Form integration | ✅ Complete |
| PF-15 | @/platform/data-lookup | Data lookup | ✅ Complete |
| PF-16 | @/platform/custom-fields | Custom fields | ✅ Complete |
| PF-17 | @/platform/field-config | Field configuration | ✅ Complete |
| PF-56 | @/platform/upload | File uploads | ✅ Complete |
| - | @/platform/csv | CSV parsing for bulk imports | ✅ Complete |
| CE-03 | @/platform/telephony | Telephony/calls | ✅ Complete |
| - | @/platform/workforce | Workforce integration | ✅ Complete |
| - | @/platform/workflow | Workflow canvas | ✅ Complete (GR-11) |
| PF-73 | @/platform/workflow | Swim lane diagrams (canvas, CRUD, export, GR-11/GR-01 generation) | ✅ Complete (Phase 1); Phase 2 📝 Planned |
| PF-65 | @/platform/gusto | Gusto Embedded Payroll (SDK + proxy) | ✅ Complete |
| PF-66 | @/platform/realtime | Realtime subscriptions, broadcast, presence | ✅ Complete |
| PF-37 | @/platform/gestures | Mobile gesture system (swipe-to-dismiss, swipe-actions, pull-to-refresh, edge-swipe, pinch-to-zoom, multi-touch, custom gestures); useGestureIntegration ties preferences/haptics/analytics into all hooks; SwipeableCardShell, SwipeableSheet shared primitives. The navigation primitive @/platform/navigation/components/BottomTabBar is exported by the navigation module, not gestures. See Mobile Gesture Guide v2.0.0 and PF-37 Phase 2/3 Integration. | ✅ Complete (Phase 1+2+3) |
| PF-67 | @/platform/messaging | Internal real-time messaging, record threads | 📝 Planned |
| PF-70 | @/platform/codes | Medical terminology & code libraries (ICD-10-CM, CPT, HCPCS, modifiers, validation) | 📝 Planned |
| PF-43 | @/platform/quota | Tenant-scoped resource quotas (storage, API, users, workflows); useResourceQuota hook, pf_check_resource_quota; see PF-43 Integration | 📝 Planned |
| PF-51 | @/platform/cache | Caching (query results, config, reference data); tenant-scoped keys | ✅ Complete |
| CL (EHR/PM) | @/platform/clinical | CL Consent Service ✅; Patient Context, Billing Adapter, Document Export 📝 | 🟡 In Progress |
| CL/PM | @/platform/scheduling | Encounter/appointment context for CL-04, CL-14, CL-24 | 📝 Planned (contract in README) |
| CL/PM | @/platform/types | Shared EncounterContext, ChargeContext, DiagnosisReference, etc. | ✅ Implemented |
| PF-84 | @/platform/calendar | Business calendar service (hooks, business day utils, CalendarPicker, holiday templates/CSV import) | ✅ Complete (Phase 1) |
| PF-85 | @/cores/fw/pages/AutomationObservabilityPage.tsx | Automation observability dashboard (real-time metrics, SLA compliance, alert thresholds) | ⚠️ Architectural Debt: Currently in FW core; should be moved to @/platform/automation-observability per spec. See PF-85 Integration. |
| PF-86 | @/platform/email-signatures | Organization/user email signatures (HTML/text, variable substitution, compliance disclaimers) | ✅ Complete |
| PF-96 | @/platform/jurisdiction | Jurisdiction profile system (state Medicaid compliance rules); useJurisdictionProfile() hook, useClinicalRules(), useBillingRules(), useComplianceRules() convenience hooks; pf_resolve_jurisdiction_profile() RPC | 📝 Planned |
Overview
Platform Integration Layers follow Pattern 1 from the architecture constitution. They provide:- Reusable UI components
- Shared hooks and utilities
- Cross-core data access without direct dependencies
- Stable API contracts
import { x } from '@/cores/fa/...' inside RH)
Cross-Core FK Exception: By default, cross-core table references use UUID columns with no database FK. For the CL-PM encounter entity only, a scoped exception allows a database FK from CL tables to pm_encounters.id with ON DELETE RESTRICT. See ADR-002 and constitution §1.2, §5.2.7.
Status Legend
- ✅ Complete - Fully implemented and production-ready
- 🟡 In Progress - Partially implemented
- 📝 Planned - Specified but not yet implemented
- ❌ Deprecated - No longer recommended
PF-08: Forms Integration Layer
Location:/src/platform/forms/Status: ✅ Complete
Implemented: 2025-11-23
Version: v1.1.0 (added form ownership)
Last Verified: 2025-12-03 Public API:
- Forms have
owning_corecolumn to indicate domain ownership useFormListacceptsowningCore?: CoreCodefilterFormSelectoracceptsowningCore?: CoreCodeprop- Module-specific pages use
ModuleFormsPagewith core filter
- RH (Recovery Housing): Resident intake forms (
/rh/forms) - HR (Workforce): Onboarding forms (
/hr/forms) - GR (Governance): Policy acknowledgment forms (planned)
- FA (Finance): Payment forms (planned)
- Current: v1.1.0
- v1.1.0 Changes: Added
owning_core,ModuleFormsPage, core filtering - Breaking changes require version bump and migration guide
FW-32: External Form Portal Integration
Location:/src/cores/fw/components/portal/, /src/cores/fw/pages/, /supabase/functions/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-30 Overview: External form portal system enabling public form access for unauthenticated users with spam protection, rate limiting, email verification, branding customization, and consent management. Public API:
| Route | Component | Auth | Purpose |
|---|---|---|---|
/p/:accessToken | PublicFormPage | None | Public form access |
/p/verify/:token | PortalVerifyPage | None | Email verification |
| Function | Purpose | JWT Required |
|---|---|---|
portal-get-config | Fetch form and portal config by token | No |
portal-form-submit | Process public submissions | No |
portal-verify-email | Verify email tokens | No |
| Bucket | Purpose | Access |
|---|---|---|
portal-logos | Organization portal logos | Public read, authenticated write |
- reCAPTCHA v3 / hCaptcha integration
- IP-based rate limiting (SHA-256 hashed)
- Honeypot spam detection
- Email verification with expiring tokens
- Consent checkbox requirement
- FW (Forms): Public form submissions
- RH: Resident intake applications
- HR: Job applications, public surveys
- Backward compatibility maintained for 90 days minimum
/src/platform/forms/README.md and Constitution Section 1.4
Platform Workforce Integration Layer
Location:/src/platform/workforce/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
- RH (Recovery Housing): Assign staff to resident cases
- FA (Finance): Select employees for expense approval
- GR (Governance): Verify staff credentials for compliance
- HR-04 (Scheduling): Validate credentials before shift assignment
@/platform/workforce as the canonical module — see CL-HR-PROVIDER-PRODUCTIVITY-INTEGRATION.md. When implemented, getProviderProductivity() will live here so the layer hosts multiple workforce metrics (employee lookup, credential check, productivity aggregates).
CL-40 / CL-19 — Peer supporter identity (no CL→HR DB FK): cl_peer_encounters.peer_supporter_id holds hr_employees.id as a logical reference only (constitution default: no cross-core FK outside ADR-002). Platform: expose validation through @/platform/workforce (employee lookup + credential checks) when creating or editing peer encounters; CL must not import HR core modules. Database: migrations SHOULD define cl_peer_supporter_valid_for_org(p_organization_id UUID, p_peer_supporter_id UUID) RETURNS BOOLEAN (SECURITY DEFINER, SET search_path = public) and use it in cl_peer_encounters INSERT/UPDATE with both USING (for UPDATE reads) and WITH CHECK (for INSERT/UPDATE writes) so tenant and employment invariants hold without a foreign key to hr_employees. See CL-40-clinical-intake-INTEGRATION.md.
Documentation: See /src/platform/workforce/README.md
PF-15: Data Lookup Integration Layer
Location:/src/platform/data-lookup/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
hr_departments- Department lookuphr_positions- Position lookuppf_sites- Site lookuphr_employees- Employee lookup (with special handler)
- FW (Forms & Workflow): Dynamic form field lookups
- HR (Workforce): Department/position selectors
- RH (Recovery Housing): Site and staff selectors
- All cores: Generic table lookups for dropdowns
/src/platform/data-lookup/README.md
PF-16: Custom Fields Integration Layer
Location:/src/platform/custom-fields/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
hr_employees,hr_positions,hr_departmentsrh_residents,rh_beds,rh_facilitiesfa_invoices,fa_accounts,fa_vendorsfw_forms,fw_form_submissionspf_documents
- All cores: Extend entity schemas without code changes
- HR: Employee badge numbers, external IDs
- RH: Resident metadata, case IDs
- FA: Invoice metadata, external references
/src/platform/custom-fields/README.md
PF-17: Field Configuration Integration Layer
Location:/src/platform/field-config/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
- Field visibility control
- Role-based permissions
- Conditional logic
- Section grouping
- Multi-column layouts
- View contexts (create_form, edit_form, detail_view, list_view)
- All cores: Configure field layouts without code changes
- HR: Customize employee forms per organization
- RH: Configure resident forms
- FA: Configure invoice/vendor forms
/src/platform/field-config/README.md
PF-56: File Upload Integration Layer
Location:/src/platform/upload/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2026-01-09 Public API:
- Tenant isolation (all paths include
organizationId) - File type and size validation from
pf_module_settings - Progress tracking with debouncing
- Cancellation support via AbortController
- Image processing (resize, compress, thumbnail)
- WebP support detection with JPEG fallback
- GIF handling preserves animation
- PF (Platform): Document uploads, avatar uploads
- FW (Forms): Form submission attachments, portal logos
- HR (Workforce): Employee documents, credentials
- FA (Finance): Invoice attachments, receipts
- RH (Recovery Housing): Resident documents
/src/platform/upload/README.md
CSV / Bulk Import Utilities
Location:/src/platform/csv/Status: ✅ Complete
Constitution Reference: §5.10 (Bulk Import & Data Migration Standards) Shared CSV parsing and formatting for all bulk import flows (HR employee/credential/oversight, CE contacts, Platform custom objects, FA template lines, etc.). Cores MUST use this module instead of implementing local
parseCsvLine/parseCsv.
Public API:
parseCsvLine(line: string): string[]— Parse a single CSV line (quoted fields, escaped quotes)parseCsv(csvText: string): ParseCsvResult— Parse full CSV (headers, rows, errors)formatCsvValue(value: string): string— Escape value for CSV output (template generation)BULK_IMPORT_CHUNK_SIZE— Standard batch size (50) for client-side chunked imports
/src/platform/csv/README.md, docs/guides/use-cases/bulk-import-migration.md
FW-17 → PF-17: Condition Builder Field Discovery
Location:/src/cores/fw/hooks/useConditionAttributes.tsStatus: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-06 Pattern: FW-17 Advanced Condition Builder integrates with PF-17 Field Configuration
Integration Point:
useConditionAttributes hook
How It Works:
useConditionAttributesfetches field configs from PF-17’spf_entity_field_configstablemapFieldConfigToAttribute()converts PF-17 format to FW-17EntityAttributeformat- Standard fields from
STANDARD_FIELDSare merged as fallback - Custom fields, picklists, and visibility are respected
- Event payload fields (from FW-16) are optionally included
src/cores/fw/hooks/useConditionAttributes.ts- Main hooksrc/cores/fw/utils/mapFieldConfigToAttribute.ts- Type mapping utilities
- FW-17: Advanced Condition Builder attribute browser
- FW-16: Event-based trigger condition configuration
FW-18: Workflow Variables Integration Layer
Location:/src/cores/fw/components/variables/, /src/cores/fw/hooks/, /supabase/functions/_shared/expressionEvaluator.tsStatus: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-06 Public API:
- FW-17 (Condition Builder): Expression evaluation for condition values
- Automation Executor: Variable initialization, SetVariable execution, template resolution
- Action Config Components: VariablePicker integration for EmailActionConfig, WebhookActionConfig, RecordActionConfig
- Initialization: Variables loaded from
fw_workflow_definitions.variables - SetVariable Node: Evaluates expression/literal and stores in context
- Template Resolution:
{{variable}}placeholders resolved in action configs - Persistence: Final variable state saved to
fw_automation_logs.execution_result.variables
- Workflow variable definitions (VariablePanel)
- Expression templates with live preview (ExpressionInput)
- FW-19 Data Query: Variable storage for query results
FW-16: Event Publishing Integration Layer
Location:/src/platform/events/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-07 Overview: FW-16 provides event-based workflow triggers, allowing cores to publish domain events that trigger workflows. Public API:
fw_workflow_events- Global event registry (11 seed events)fw_domain_events- Organization-scoped event log
- HR: Publish employee lifecycle events (hired, terminated)
- RH: Publish resident lifecycle events (admitted, discharged, phase advanced)
- FA: Publish financial events (invoice created, paid, budget approved)
- FW: Publish form submission events
- FW-16: Event-based workflow triggers
- FW-17: Event payload fields as condition attributes
/src/platform/events/README.md
FW-33: Form Signature Integration Layer
Location:/src/cores/fw/components/fields/SignatureField.tsxStatus: 📝 Planned
Version: 1.0.0
Spec Reference: FW-33 Form Signature Capture Overview: FW-33 integrates platform signatures (PF-33) into the form builder as a field type. Forms can include signature fields that leverage the existing
SignatureCanvas and useSignature infrastructure.
Integration Pattern:
- FW-33 does NOT create its own signature storage
- Uses
pf_signaturesvia Platform Signature Layer (PF-33) - Creates
fw_form_submission_signaturesjunction table to link submissions to signatures
SignatureCanvasfrom@/platform/signaturesuseSignaturefrom@/platform/signaturesuseSignatureRequestsfrom@/platform/signatures
generate-signed-pdf- Creates PDF with embedded signatures
- Publishes
fw_form_signature_capturedevent - Publishes
fw_signed_document_generatedevent
- HR: Employee acknowledgment forms, policy signatures
- RH: Resident consent forms, admission agreements
- GR: Policy compliance forms, attestations
FW-29: Workflow Notifications & Alerts
Location:/src/cores/fw/components/notifications/, /src/cores/fw/hooks/, /supabase/functions/workflow-notification-trigger/, /supabase/functions/process-alert-escalations/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-07 Overview: FW-29 provides workflow-level notifications and alerts, integrating with PF-10 Notifications for delivery. Public API:
- Notifications are created in
pf_notificationstable via edge function - Uses existing notification delivery infrastructure
- Respects user notification preferences
workflow-notification-trigger: Called on execution status change, evaluates alert rulesprocess-alert-escalations: Scheduled function (every 5 minutes) for escalation processing
fw_workflow_notification_rules: Notification rules per workflowfw_workflow_alert_rules: Alert condition rulesfw_workflow_alerts: Active and historical alertsfw_workflow_notification_preferences: User preferences
- Workflow Editor: Notifications tab for configuring rules
- Alerts Dashboard: Centralized view of active alerts
- Settings: User notification preferences
FW-19: Data Query Integration
Location:/src/cores/fw/hooks/, /supabase/functions/workflow-query-action/, /supabase/functions/workflow-api-action/Status: 📝 Planned
Version: 1.0.0
Spec: FW-19-data-query-integration.md Overview: FW-19 extends the workflow system with database query capabilities and enhanced API integration. Relationship to PF-15 (Data Lookup):
- FW-19 Query Action extends PF-15’s
lookupTables.tswhitelist pattern - Uses same organization-scoped query approach
- Adds
fw_query_whitelisttable for org-specific extensions beyond default tables - Query results stored in FW-18 workflow variables
workflow-query-action- Execute parameterized queriesworkflow-api-action- Execute external API calls with auth
fw_api_connections- Stores SFTP/API connection configsfw_query_whitelist- Organization-specific table whitelist
- Query Action uses PF-15 Data Lookup pattern for table validation
- Results stored in FW-18 workflow variables
- API connections stored securely with credential references to vault
- Query Data action node in workflow builder
- Enhanced API action with auth methods
- Connection management for reusable configs
- Whitelist management for org-specific tables
specs/fw/FW-19-data-query-integration.md
FW-24: Workflow Testing & Sandbox
Location:/src/cores/fw/hooks/, /src/cores/fw/components/testing/, /supabase/functions/sandbox-execute/, /supabase/functions/test-cases-run/Status: 📝 Planned
Version: 1.0.0
Spec: FW-24-workflow-testing-sandbox.md Overview: FW-24 provides isolated sandbox environment for workflow testing with test data management, automated test cases, and coverage reporting. Public API (Planned):
sandbox-execute: Execute workflow in isolated sandboxtest-datasets-import: Import test data from CSV/JSONtest-cases-run: Execute test cases with assertions
- PF-01 (Organizations): Tenant scoping for all test data
- PF-02 (RBAC): Permission checks (workflow edit for testing)
- FW-06: Workflow structure for sandbox execution
- FW-16: Mock event triggers for testing
- FW-18: Variable testing and validation
fw_test_datasets- Test data storagefw_test_scenarios- Scenario definitionsfw_test_cases- Automated test casesfw_sandbox_executions- Execution historyfw_test_coverage- Coverage metrics
- Sandbox workflow execution
- Test data import (CSV/JSON)
- Automated test case execution
- Coverage visualization dashboard
FW-22: Workflow Execution Monitoring & Debugging
Location:/src/cores/fw/components/monitoring/, /src/cores/fw/hooks/, /supabase/functions/workflow-debug-control/Status: 📝 Planned
Version: 1.0.0
Spec: FW-22-workflow-execution-monitoring.md Overview: FW-22 provides comprehensive workflow execution monitoring, debugging, and profiling capabilities. Public API (Planned):
- PF-01 (Organizations): Tenant scoping for all monitoring data
- PF-02 (RBAC): Permission checks for debug mode (org_admin, workflow owner)
- PF-10 (Notifications): Failed execution alerts via notification system
- Realtime enabled for
fw_workflow_executionsfor live dashboard updates - Real-time monitoring of execution status changes
- Sub-second latency for active execution display
workflow-debug-control: Debug session management (start/pause/resume/step)- See API Contracts for full API spec
fw_execution_logs: Searchable execution logs with contextfw_debug_sessions: Debug session state and step history
- FW-06: Advanced Workflow Builder - Debug mode integration
- FW-07: Workflow Versioning - Compare executions across versions
- FW-18: Workflow Variables - Variable inspection during debugging
PF-27: Platform AI Integration Layer
Location:/src/platform/ai/Status: 🟡 Phase 1 Complete
Version: 1.0.0
Last Verified: 2025-12-06
Spec: PF-27-platform-ai.md Public API:
ai-assistant- Streaming AI chat with module-specific system prompts (OpenRouter)ai-document-analyze- Document analysis with structured output (OpenRouter, GPT-4o)generate-report-narrative- Report narrative generation (OpenRouter, GPT-4o)
- Primary: OpenRouter (migrated from Lovable AI Gateway in PF-59)
- Models: Model selection based on module context:
- GR, HR → Claude 3.5 Sonnet (compliance/policy)
- FA, FW, RH, PF → GPT-4o (general/analysis)
- LO, FM → GPT-4o Mini (fast tasks)
- All cores can import via
@/platform/ai - Module context enables specialized AI behavior per core
- Shared aiPromptBuilder creates consistent prompts
- Model selection automatic based on
moduleContext.module
- FW (Forms & Workflow): FW-30 Workflow optimization ✅ Planned (uses
useAIStructuredOutputfor suggestion generation) - LO (Leadership): Meeting summaries, issue suggestions (planned)
- FA (Finance): Transaction categorization (planned)
- PF (Platform): Report generation (planned)
- Never send PHI/PII to external AI
- Edge functions handle OPENROUTER_API_KEY securely (via Supabase secrets)
- Rate limiting with 429/402 error handling (exponential backoff)
- Module context provides audit trail
- API keys never exposed to client
- Status: 📝 Planned
- Version: v1.1.0 (extends PF-27)
- Spec: PF-62-ai-skills-system.md
- New Hooks:
useAISkills,useAISkill,useAISkillChat,useCreateAISkill,useUpdateSkillOverride,useModuleDefaultSkill - New Components:
AISkillsPage,AISkillsList,SkillConfigurationDialog - Features:
- Specialized AI skills (Policy Writer, Risk Analyzer, Compliance Advisor, etc.)
- Organization-specific skill customization
- Module default skills
- Skill-aware AI chat with merged prompts and RAG configuration
- Dependencies: PF-59 (AI Provider Migration), PF-60 (RAG Infrastructure), PF-27 (Platform AI)
specs/pf/PF-27-platform-ai.md- Original Platform AI specificationspecs/pf/PF-59-ai-provider-migration.md- OpenRouter migration (PF-59)specs/pf/PF-60-rag-infrastructure.md- RAG Infrastructure (PF-60)specs/pf/PF-62-ai-skills-system.md- AI Skills System (PF-62)docs/architecture/analysis/AI_INTEGRATION_STRATEGY_2026.md- Feature roadmap
src/platform/ai/README.md and specs/pf/PF-27-platform-ai.md
Last Updated: 2026-01-28 (PF-59 migration, PF-62 planned)
PF-10: Notifications Integration Layer
Location:/src/platform/notifications/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
- Real-time notification delivery
- Multi-channel support (in_app, email, sms)
- User preferences management
- Unread count tracking
- Notification center UI
- All cores: Send notifications to users
- FW: Form submission notifications
- HR: Credential expiration alerts
- FA: Payment and budget alerts
- RH: Resident admission/discharge notifications
/src/platform/notifications/ (README pending)
PF-11: Documents Integration Layer
Location:/src/platform/documents/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
- Document upload and storage
- Version management
- Permission-based access control
- Full-text search
- Preview support (images, PDFs, text)
- Category and tag organization
- All cores: Store and manage documents
- HR: Employee documents, credentials
- RH: Resident agreements, intake forms
- FA: Vendor contracts, invoices
- GR: Policy documents, training materials
/src/platform/documents/ (README pending)
PF-12: Reports Integration Layer
Location:/src/platform/reports/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-03 Public API:
- Report definition management
- Parameterized report execution
- Multiple output formats (JSON, CSV, PDF)
- Report scheduling
- Execution history
- Organization and public reports
- All cores: Generate and schedule reports
- HR: Employee reports, credential reports
- FA: Financial statements, budget reports
- RH: Census reports, attendance reports
- GR: Compliance reports, training reports
/src/platform/reports/ (README pending)
Versioning Strategy
Breaking Changes
Breaking changes to platform integration layers MUST:- Be documented with version bump
- Include migration guide for consumers
- Maintain backward compatibility for 90 days minimum
- Require explicit approval from technical owner
Version Format
- Semantic versioning: v1.0.0 → v2.0.0 for breaking changes
- Minor version: v1.0.0 → v1.1.0 for new features (backward compatible)
- Patch version: v1.0.0 → v1.0.1 for bug fixes
Integration Checklist
Before creating a new platform integration layer:- Multiple cores need the functionality
- Functionality is domain-agnostic
- Public API defined and documented
- Versioning strategy defined
- Consumer cores identified
- Usage examples provided
- README created in
/src/platform/{layer}/ - Added to this document
PF-27: Platform AI Integration Layer
Location:/src/platform/ai/Status: ✅ Phase 3 Complete
Version: v1.0.0
Last Verified: 2025-12-08 Public API:
- Streaming chat via Lovable AI Gateway
- Module-aware context for specialized behavior
- Structured output with Zod validation
- PHI detection security layer
- Conversation persistence
- Prompt feedback system (thumbs up/down)
- Usage analytics per organization
- All cores via
@/platform/ai(seedocs/architecture/analysis/AI_INTEGRATION_STRATEGY_2026.mdfor roadmap; not yet authored) - PF-12 Reports: AI-generated report narratives (complete)
- LO: Meeting summaries (planned)
- FA: Transaction categorization (planned)
- FW-30: Workflow optimization (planned)
specs/pf/PF-27-platform-ai.md- Full specificationdocs/architecture/analysis/AI_INTEGRATION_STRATEGY_2026.md- Feature roadmapspecs/pf/PF-28-ai-shared-widgets.md- Reusable AI widgets
/src/platform/ai/README.md
PF-28: AI Widgets Integration Layer
Location:/src/platform/ai/widgets/Status: 📝 Planned
Version: v0.1.0 (Draft)
Last Verified: 2025-12-08 Planned Widgets:
- PF-27 (Platform AI) - All hooks and utilities
- PF-11 (Documents) - For AIDocumentAnalyzer integration
- All cores: Composable AI-powered UI components
- HR: Credential classification widget
- FA: Transaction categorization widget
- GR: Policy summarization widget
specs/pf/PF-28-ai-shared-widgets.md
PF-29: Tasks Integration Layer
Location:/src/platform/tasks/Status: ✅ Complete
Implemented: 2025-12-17
Version: v1.0.0 Overview: PF-29 provides a unified task system enabling cross-module task management. Tasks can be linked to any source entity (goals, meetings, issues, etc.) through polymorphic source linking. Public API:
goal- LO-03 Goalsrock- LO-02 Rocksissue- LO-07 Issuesheadline- LO-05 Headlinesmeeting- LO-06 Meetingslo_todo- Legacy LO-04 Todos (migrated)form- FW Form submissionsresident- RH Residentsemployee- HR Employeeswork_order- FM Work orders
- LO (Leadership OS): Goals, Meetings, Issues, Rocks integration
- RH (Recovery Housing): Resident-linked tasks (planned)
- HR (Workforce): Employee-linked tasks (planned)
- FA (Finance): Financial task tracking (planned)
- FM (Facilities): Work order tasks (planned)
pf_tasks- Main task table with polymorphic source linkingpf_task_comments- Task comments/discussion
/tasks- My Tasks unified view/tasks/:taskId- Task detail page
/src/platform/tasks/README.md
PF-37: Gestures Integration Layer
Location:/src/platform/gestures/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2025-12-24 Public API:
- Swipe-to-Dismiss: Sheets, dialogs, modals, toasts
- Swipe-to-Reveal Actions: List items, notifications, tasks
- Pull-to-Refresh: List pages, tables, dashboards
- Edge Swipe Navigation: Back navigation on detail pages
- PF (Platform): MobileMenuSheet, TaskList
- FW (Workflow): ApprovalInbox
- All cores: List items, refreshable lists
- All gestures have keyboard alternatives (ESC, Delete, Enter)
- WCAG 2.5.1 (Pointer Gestures) compliant
- WCAG 2.5.2 (Pointer Cancellation) compliant
/src/platform/gestures/README.md and /docs/development/mobile-gesture-guide.md
PF-41: Wizards Integration Layer
Location:/src/platform/wizards/Status: 🟡 In Progress (Phase 1 Complete)
Implemented: 2025-12-31
Version: v1.0.0 (Phase 1 - Hooks only) Public API:
- System templates (
is_template=true): Platform defaults, read-only via UI - Org templates (
is_template=false): Customized per organization useActiveWizardresolves preference: org template > system template
| Permission | Description |
|---|---|
pf.wizards.admin | Full administrative access |
pf.wizards.create | Create new templates |
pf.wizards.edit | Edit existing templates |
pf.wizards.view | View templates (read-only) |
pf.wizards.clone | Clone templates |
- HR (Workforce): Employee onboarding wizards
- RH (Recovery Housing): Resident admission wizards
- FA (Finance): Setup wizards
- All cores: Module-specific configuration wizards
/src/platform/wizards/README.md
PF-51: Caching Layer Integration Layer
Location:/src/platform/cache/Status: ✅ Complete — 2026-03-05
Spec: PF-51
Integration Doc: PF-51 Integration Purpose: Centralized, tenant-scoped caching for query results, configuration, and reference data. Cache keys use format
org-{orgId}:{namespace}:{key}; all cores consume via @/platform/cache. No database tables; in-memory only for Phase 1.
Public API (planned):
cacheService:get,set,delete,clear,invalidate(pattern)useCachedQuery: TanStack Query–backed cached query hook
PF-54: Formatting Utilities Integration Layer
Location:/src/platform/formatting/Status: 📝 Planned
Spec: PF-54
Last Verified: 2026-01-07 Public API:
- Currency:
formatCurrency(amount, options?)- Locale-aware currency formatting - Date:
formatDate(date, format?, locale?)- Date formatting with custom formats - DateTime:
formatDateTime(date, format?, locale?)- Date and time formatting - Time:
formatTime(date, format?, locale?)- Time-only formatting - Number:
formatNumber(value, options?)- Locale-aware number formatting - Percentage:
formatPercent(value, decimals?, locale?)- Percentage formatting - Phone:
formatPhone(phone, format?)- Phone number formatting (US/international)
- Currency code:
pf_module_settings.formatting_currency_code(default: ‘USD’) - Date format:
pf_module_settings.formatting_date_format(default: ‘MM/DD/YYYY’) - Locale:
pf_module_settings.formatting_locale(default: ‘en-US’) - Number decimals:
pf_module_settings.formatting_number_decimals(default: 2)
- All cores (HR, FA, RH, GR, FM, FW, LO, IT) will use formatting utilities
- Replaces duplicate formatting implementations across 8+ locations
- Phase 1: Create centralized utilities
- Phase 2: Add organization preferences
- Phase 3: Create formatting components
- Phase 4: Migrate existing code (remove duplicates)
PF-56: File Upload Framework Integration Layer
Location:/src/platform/upload/Status: 📝 Planned
Version: 1.0.0 (planned)
Last Verified: 2026-01-08 Overview: Centralized file upload framework providing consistent upload functionality across all modules. Eliminates duplication across 4+ locations and ensures tenant isolation, file validation, progress tracking, and error handling. Public API:
- Tenant Isolation: All uploads scoped by
organizationIdin path - File Validation: Type and size validation (configurable per organization)
- Progress Tracking: Real-time upload progress (0-100%, speed calculation)
- Error Handling: Structured error codes, retry logic (3 attempts for network errors)
- Image Processing: Resize, compression, thumbnail generation (optional)
- Upload Cancellation: Support for AbortSignal
pf-avatars- User profile avatars (public)pf-documents- General documents (private)fw-submission-attachments- Form submission files (private)
max_upload_size_mb- Maximum file upload size (default: 25MB, range: 1-100MB)allowed_file_types- Array of allowed MIME types (default: common types)
- FW (Forms & Workflow): Form attachment uploads
- HR (Workforce): Employee document/credential uploads
- PF (Platform): Avatar and logo uploads
- FA (Finance): Invoice/receipt uploads
- RH (Recovery Housing): Resident document uploads
- Phase 1: Create centralized upload service
- Phase 2: Create upload components and hooks
- Phase 3: Add image processing (optional)
- Phase 4: Migrate existing upload code (remove duplicates)
- Path-based organization isolation enforced
- Storage bucket RLS policies from PF-11
- File validation before upload
- File name sanitization (prevents path traversal)
PF-57: Search/Filter/Sort/Pagination Framework
Location:/src/platform/search/, /src/platform/filter/, /src/platform/sort/, /src/platform/pagination/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2026-01-08 Public API:
- All cores (HR, FA, RH, GR, FM, FW, LO, IT)
/src/platform/search/README.md, /src/platform/filter/README.md, /src/platform/sort/README.md, /src/platform/pagination/README.md
PF-58: Data Table Integration Layer
Location:/src/platform/table-v2/Status: ✅ Complete (Phase 2-3-4 Expansion — 2026-03-06)
Version: 2.0.0
Last Verified: 2026-03-06 Consumer Cores: IT, FA, HR, PF, RH, GR, LO, FW, FM Migration Summary:
- 25 tables migrated across all cores (100% complete)
- All previously exempted tables now migrated (RawDataTable, ScorecardTable)
- Uses
FilterGroupfrom@/platform/filterfor filter configuration - Uses
SortConfigfrom@/platform/sortfor sort configuration - Uses
applyFilterGroupfor client-side filtering inuseDataTable - Uses
escapeILikePatternfrom@/platform/searchfor filter input security
- Temporary
BulkAction<T>interface defined intypes.ts - Will be replaced with
@/platform/bulk-operationswhen PF-47 is complete - See TODO comment in
types.tsfor migration steps
- Generic
<DataTable<T>>with full TypeScript support - Column types: text, number, date, currency, boolean, custom
- Row selection (single/multi) with “select all”
- Pagination with page size selector
- Column sorting (single/multi with Shift+click)
- Global search and per-column filters
- Bulk actions with confirmation dialogs
- Loading skeletons and empty states
- Mobile responsive with hideOnMobile support
- XSS protection via DOMPurify sanitization
- Inline cell editing (text, number, currency, boolean, date, select)
- Column resizing with localStorage persistence
- Sticky columns for horizontal scrolling
- Virtual scrolling for 10,000+ rows (planned)
- Column visibility toggling with localStorage persistence
- Drag-and-drop column reordering via @dnd-kit
- “Show All” / “Hide All” quick actions
- CSV export (built-in, no external dependency)
- Excel export with styled headers (via exceljs)
- Progress tracking for large exports
- Row grouping by column values
- Aggregate calculations (count, sum, average, min, max)
- Nested group support up to 3 levels
- Expand/collapse group controls with localStorage persistence
- All cores: Replace custom table implementations
- HR: Employee lists, applicant tracking tables
- FA: Account lists, transaction tables, vendor lists
- RH: Resident lists, census tables
/src/platform/table/README.md
PF-23/24/25/26: Data Manager Integration Layer
Location:/src/platform/data-manager/Status: ✅ Complete
Version: 1.0.0
Last Verified: 2026-01-08 Specs:
- PF-23: Data Manager - Object Browser
- PF-24: Custom Objects
- PF-25: Raw Data Editor
- PF-26: Object Permissions
- Object discovery and metadata management
- Custom object creation and management
- Raw data browsing and inline editing
- CSV import/export for bulk operations
- Object-level and field-level permissions
- Category management and favorites
- All cores: Browse objects, manage metadata
- HR: Clinical licenses, training classes
- FA: Custom financial entities (planned)
- RH: Incident tracking, program outcomes (planned)
/src/platform/data-manager/README.md and Data Management Architecture
CE-03: Platform Telephony Integration Layer
Location:/src/platform/telephony/
Status: ✅ Complete
Implemented: v1.1.0 (Click-to-Call & Screen Pop via CE-03-E1)
Last Verified: 2026-01-27
Spec: CE-03, CE-03-E1
Purpose: Provides unified telephony capabilities (call management, RingCentral integration) for all cores needing phone communication features.
Public API:
- Call Management (CE-03): Call log viewing, disposition workflow, recording playback
- Click-to-Call (CE-03-E1): One-click dialing via RingCentral RingOut API
- Screen Pop (CE-03-E1): Real-time caller ID notification via Supabase Realtime
ringcentral-webhook- Receives RingCentral telephony eventsringcentral-setup- Manages subscription lifecycleringcentral-recording-proxy- Secure recording accessringcentral-ringout- Initiates click-to-call (CE-03-E1)
ce_calls- Call records with dispositionce_ringcentral_extensions- User extension mappingce_ringcentral_subscriptions- Webhook subscriptionsce_ringout_sessions- RingOut tracking (CE-03-E1)
- CE: Primary consumer for CRM call features
- RH: Contact calls with residents/guardians (via CE contacts)
- HR: Employee phone contacts (potential future use)
- RingCentral API (JWT authentication)
- Supabase Realtime (screen pop)
Workflow Canvas Integration Layer
Location:/src/platform/workflow/Status: ✅ Complete (GR-11 Implementation)
Created By: GR-11 (Procedures Management)
Version: 1.0.0
Spec Reference: GR-11 Procedures Management Purpose: Exposes @xyflow/react workflow canvas capabilities for cross-core visual workflow editing. Public API:
- Node Type Registration: Define module-specific node types extending base types
- Edge Styling: Use semantic colors for edge connections
- Canvas Controls: Always include MiniMap, Controls, Background for usability
- Mobile Handling: Canvas is read-only on mobile (<768px)
- ❌ Direct @xyflow/react imports in cores - use platform layer
- ❌ Storing raw React Flow nodes in database - convert to serializable format
- ❌ Complex drag-drop on mobile - display read-only view instead
| Dependency | Version | Purpose |
|---|---|---|
| @xyflow/react | ^12.10.0 | Core workflow canvas |
| @xyflow/background | - | Canvas background patterns |
| @xyflow/controls | - | Zoom/pan controls |
| @xyflow/minimap | - | Navigation minimap |
- React Flow integration (@xyflow/react) with custom node types
- Zoom, pan, and fit-to-view controls
- Mini-map for navigation in large workflows
- Grid snap with configurable increments
- Auto-save on changes
- Custom node types for procedure steps (Action, Decision, Reference, Verification, System)
- GR: Visual procedure editor (GR-11) - ✅ Implemented
- FW: Advanced workflow builder (FW-06) - Original implementation
- Future: Other cores needing visual workflow capabilities
- Wraps @xyflow/react workflow canvas functionality
- Provides stable API for cross-core consumption
- GR-11 creates procedure-specific node types on top of base canvas
/src/platform/workflow/README.md for complete implementation details.
Common Usage Patterns:
- Import
useWorkflowCanvashook andWorkflowCanvascomponent - Initialize with starting nodes and edges
- Use hook to get state and handlers (
nodes,edges,onNodesChange,onEdgesChange,onConnect) - Pass state and handlers to
WorkflowCanvascomponent - Provide custom
nodeTypesfor domain-specific node rendering - Use
fitViewor other viewport controls for navigation
- FW-06 (Forms & Workflow): Source of truth for workflow canvas implementation
- Original workflow canvas implementation in
/src/cores/fw/ - Platform layer wraps and exposes FW-06 functionality
- FW-06 maintains the core workflow engine logic
- Original workflow canvas implementation in
- Platform Foundation: Base infrastructure for cross-core capabilities
- @xyflow/react: React Flow library for node-based graph visualization
- Provides core canvas, node, and edge rendering
- Handles zoom, pan, and viewport management
- Manages node/edge state and interactions
- React: Required for component rendering and hooks
- GR-11 (Procedures Management): Primary consumer
- Uses canvas for visual procedure editor
- Creates procedure-specific node types (Action, Decision, Reference, Verification, System)
- FW-06 (Forms & Workflow): Original implementation and source of truth
- Advanced workflow builder uses platform layer
- Maintains workflow engine and execution logic
/src/platform/workflow/README.md (to be created during GR-11 implementation) for complete implementation details, API reference, and advanced usage patterns.
PF-73: Swim Lane Diagram Builder
Location:/src/platform/workflow/ (extends Workflow Canvas layer)Status: ✅ Complete (Phase 1) — Phase 2 📝 Planned Spec Reference: PF-73 Workflow Builder with Swim Lane Visualization
Integration Doc: PF-73-workflow-builder-swim-lane-INTEGRATION.md Purpose: Extends the workflow layer with swim lane diagram capabilities: horizontal/vertical lanes, node-in-lane placement, manual builder UI, diagram CRUD in
pf_swim_lane_diagrams, generation from GR-11 procedures and GR-01 policies (with optional PF-27 AI), and PDF/image export. Consumed by GR, FW, HR for process documentation—visualization only (no workflow execution; FW-06 remains the execution engine).
Public API (when implemented):
- Components:
SwimLaneCanvas(lane-aware canvas) - Hooks:
useSwimLaneDiagramList,useSwimLaneDiagram,useSwimLaneDiagramMutation - Types:
LaneDefinition,SwimLaneDiagramState(lanes, nodes, edges, viewport)
pf.swim-lane-diagrams.view, .create, .update, .delete, .export.
Documentation: See PF-73 Integration Doc for contracts, RLS, and settings.
PF-65: Gusto Embedded Payroll Integration Layer
Location:/src/platform/gusto/ (to be created)Status: 📝 Planned
Spec: PF-65 Gusto Embedded Payroll Integration
Integration Doc: PF-65-gusto-embedded-payroll-INTEGRATION.md Purpose: Platform layer for the Gusto Embedded React SDK. Provides
GustoProvider, hooks (useGustoConfig, useGustoConnectionStatus), and re-exports of SDK components (e.g. EmployeeOnboardingFlow, EmployeeList). All SDK requests go through a Supabase Edge Function proxy that adds OAuth2 and x-gusto-client-ip; no Gusto credentials in the frontend.
Features:
- Backend proxy (Supabase Edge Function) for OAuth token injection and request forwarding
- OAuth and token management via PF-35 (access/refresh tokens server-side only)
x-gusto-client-ipinjection from trusted proxy headers- SDK re-exports from
@gusto/embedded-react-sdk(GustoProvider, EmployeeOnboardingFlow, EmployeeList) - Event handling via
componentEventsandonEventfor analytics/sync
- Never import the SDK directly – Always use
@/platform/gusto; direct@gusto/embedded-react-sdkimports bypass the proxy and OAuth. - Never send OAuth tokens to the frontend – Tokens are resolved server-side in the proxy only; client only receives proxy baseUrl and companyId.
- Never set
x-gusto-client-ipfrom the client – The header must be set by the Edge Function from trusted proxy headers (X-Forwarded-For / X-Real-IP) only. - Never bypass the proxy – All Gusto API traffic must go through the gusto-proxy Edge Function so tokens and client IP are injected server-side.
- HR (primary) – Workforce routes such as
/hr/payroll/gusto(Gusto employees list) and/hr/me/onboarding(Employee Onboarding). Permissions:hr.gusto.view,hr.gusto.configure.
- PF-01 (Organizations) – Org context and
organization_idresolution for proxy and connection status. - PF-35 (Integration Hub) – OAuth flow, credential storage (
pf_integrations), and company mapping for Gusto Embedded. - PF-04 (Audit Logging) – Audit entries for connect/disconnect and token refresh failures (no token values in logs).
- @gusto/embedded-react-sdk – Gusto Embedded React SDK; provides
GustoApiProvider,Employee,Company,componentEvents. All usage must go through the platform layer so requests are proxied with OAuth andx-gusto-client-ip.
/src/platform/gusto/README.md for implementation details and API reference. See PF-65-gusto-embedded-payroll-INTEGRATION.md for the integration contract, proxy behavior, and security guidance.
Planned Platform Layers (CL/PM EHR & Practice Management)
Source: EHR_PM_PLANNING_BUNDLE.mdStatus: 🟡 In Progress — Consent Service ✅; Patient Context, Billing Adapter, Document Export, Scheduling layer contracts defined in
src/platform/clinical/README.md and src/platform/scheduling/README.md. Shared types in @/platform/types (clinical-billing). Clinical medication integrations (e.g. CL–RH Residential MAR) use @/platform/clinical as the canonical layer so medication-related APIs remain colocated with clinical data; see CL-RH-RESIDENTIAL-MAR-INTEGRATION.md.
CL Consent Service
Location:@/platform/clinical
Status: ✅ Implemented (useConsentCheck)
Spec Reference: CL-11 – Consent Management & 42 CFR Part 2
Purpose: Centralized consent evaluation for 42 CFR Part 2, TPO, SUD counseling notes, and legal-proceedings consent. Policy decision point (PDP) for UI/API/export gating and disclosure logging. Consumer cores: CL, PM, FW.
Public API (proposed):
- Interface:
ConsentServiceAPIevaluateConsent(request: ConsentCheckRequest): Promise<ConsentCheckResponse>— Returns{ allowed, obligations?, denial_reason?, audit_id? }; key fields:patient_id,purpose_of_use,resource_type?,organization_id,user_id?.
- Return shape:
ConsentCheckResponse:allowed: boolean,obligations?: string[],denial_reason?: string,audit_id?: string.
CL Billing Adapter
Location:@/platform/clinicalStatus: 📝 Planned
Spec Reference: PM-07 – Charge Capture & Fee Schedules, CL-04 – Progress Notes & Session Documentation Purpose: Map encounters and progress notes to billable events without direct CL→PM imports. Exposes encounter context (e.g. encounter type, duration) for charge capture. Consumer cores: PM, CL (read-only context). Public API (proposed):
- Interface:
BillingAdapterAPImapEncounterToCharge(encounterId: string, options?: { organization_id: string }): Promise<ChargeCaptureContext>— Returns encounter type, date, provider, duration, and suggested service codes for charge capture.
- Return shape:
ChargeCaptureContext:encounter_id: string,encounter_type?: string,service_date: string,provider_id?: string,duration_minutes?: number,suggested_codes?: { cpt?: string; modifier?: string }[].
CL Document Export (EHI)
Location:@/platform/clinicalStatus: 📝 Planned
Spec Reference: CL-16 – FHIR Interoperability & Data Exchange Purpose: FHIR R4 / USCDI v3 export and C-CDA generation for patient access and third-party apps. Supports “full EHI access” and information blocking compliance. Consumer cores: CL, PM-12, external FHIR clients. Public API (proposed):
- Interface:
DocumentExportAPIexportEHI(patientId: string, options: { organization_id: string; format?: 'fhir' | 'ccda'; _since?: string }): Promise<ExportResult>— Returns URL or FHIR Bundle for downloaded EHI.
- Return shape:
ExportResult:url?: string,bundle?: object,format: string,size_bytes?: number.
Clinical Summary / Chart Context
Location:@/platform/clinicalStatus: 📝 Planned
Spec Reference: CL-01 – Patient Chart & Clinical Summary, PM-07 – Charge Capture & Fee Schedules Purpose: Read-only chart/encounter context for PM (e.g. encounter type, date, provider for billing). No direct PM→CL imports; access via platform layer only. Public API (proposed):
- Interface:
ChartContextAPIgetChartContext(patientId: string, encounterId?: string, options?: { organization_id: string }): Promise<ChartContext>— Read-only summary and encounter context for billing/display.
- Return shape:
ChartContext:patient_id: string,encounter_id?: string,encounter_type?: string,service_date?: string,provider_id?: string,summary_snapshot?: object(diagnoses, meds, allergies per CL-01).
PF-70: Medical Terminology & Code Libraries
Location:/src/platform/codes/Status: 📝 Planned
Spec Reference: PF-70-medical-terminology-code-libraries.md
Integration Doc: PF-70-medical-terminology-code-libraries-INTEGRATION.md Purpose: Centralized platform layer for ICD-10-CM, CPT, HCPCS, modifiers, and crosswalk data. Provides type-ahead search, behavioral health filtering, effective-date-aware validation, modifier-code combination validation, and optional payer-specific rules. Consumed by CL and PM cores via
@/platform/codes — never via direct Supabase queries.
Consumers: CL-01, CL-04, CL-06 (NDC, future), CL-08 (ICD-10-CM, CPT, HCPCS; LOINC deferred), CL-18, CL-19, PM-07, PM-08
Public API (planned):
useCodeSearch / searchCodes:
| Param | Type | Required | Description |
|---|---|---|---|
codeSet | 'ICD10CM' | 'CPT' | 'HCPCS' | 'LOINC' | Yes | Code set to search |
query | string | Yes | Min 2 chars; matches code or description prefix |
effectiveDate | string (ISO date) | No | Default: today |
bhOnly | boolean | No | Filter to is_behavioral_health = true codes only |
organizationId | string | Yes | Tenant isolation |
validateCode:
| Param | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Code to validate |
codeSet | string | Yes | ICD10CM, CPT, HCPCS |
modifiers | string[] | No | Modifiers to validate |
serviceDate | string | Yes | Effective date validation |
payerId | string | No | Payer-specific rule lookup |
organizationId | string | Yes | Tenant isolation |
pf_code_sets— Code set registry (ICD10CM 2025, CPT 2025, etc.) with effective datespf_icd10_codes— ICD-10-CM codes withis_behavioral_health,is_sdohflagspf_cpt_codes— CPT codes withis_behavioral_health,categorypf_hcpcs_codes— HCPCS Level II codes withis_behavioral_health,categorypf_code_modifiers— Modifier definitions and valid code-modifier combinations (org-scoped)pf_code_crosswalks— Platform-managed CPT→revenue code mappingspf_payer_code_rules— Org-specific payer code overrides (payer_id is a bare UUID, no FK to pm_payers)pf_code_favorites— Per-user/org favoritespf_code_recent— Per-user/org recently used
pf.codes.read (all clinician/billing users), pf.codes.admin (code set management)
RLS Pattern: Platform-managed code sets use organization_id IS NULL and are readable by all authenticated users via pf_can_read_code_set(p_code_set_id UUID) SECURITY DEFINER helper. Org-scoped tables (pf_code_modifiers, pf_payer_code_rules) use standard pf_has_org_access(organization_id, auth.uid()).
Notes:
- LOINC is reserved as a
codeSetparam but returns{ loinc_unavailable: true }until a future phase adds the LOINC table. CL-08 is partially blocked on LOINC for lab monitoring CDS rules. pf_payer_code_rules.payer_idis an unenforced UUID annotation (no FK topm_payers) to preserve PF→PM boundary isolation.
PF-84: Business Calendar Service
Location:/src/platform/calendar/Status: ✅ Complete (Phase 1)
Implemented: 2026-03-18
Version: 1.0.0
Spec Reference: PF-84-business-calendar-service.md
Integration Doc: PF-84-business-calendar-service-INTEGRATION.md Public API:
- All cores can use business calendar logic via
@/platform/calendar - PF-83 (SLA Management) uses calendar for deadline calculations
- FW-16 (Date-Relative Triggers) integrates with calendar for business-day-aware triggers
- Wraps FW-35 calendar tables (
fw_business_calendars,fw_calendar_holidays) via platform layer - Provides shared Edge Function utility (
_shared/business-calendar.ts) for server-side calculations - Includes 6 holiday templates (US Federal 2026/2027, CA/NY/TX/FL 2026) at
src/platform/calendar/templates/ - CSV import support for bulk holiday management
- Edge utility uses 5-minute cache to reduce database reads
PF-85: Automation Observability Dashboard
Location:@/cores/fw/pages/AutomationObservabilityPage.tsx (⚠️ Architectural Debt: Should be moved to @/platform/automation-observability)Status: ✅ Complete (Phase 1)
Implemented: 2026-03-18
Version: 1.0.0
Spec Reference: PF-85-automation-observability-dashboard.md
Integration Doc: PF-85-automation-observability-dashboard-INTEGRATION.md ⚠️ Architectural Note: This feature is currently implemented in the FW core (
src/cores/fw/pages/AutomationObservabilityPage.tsx, src/cores/fw/hooks/, src/cores/fw/components/) but is owned by Platform Foundation per spec. The hooks and components should be moved to @/platform/automation-observability to comply with platform layer boundaries. This is documented architectural debt.
Public API (Current Implementation):
- Platform admins and operators use the dashboard at
/settings/automation/observability - Integrates with PF-82 (Business Process Registry), PF-83 (SLA Management), FW-22 (Execution Monitoring), FW-47 (Dead Letter Queue)
- Aggregates metrics from multiple subsystems: workflow executions, DLQ, SLA instances, process health
- Real-time counters with 30-second auto-refresh
- Trend charts for execution volume, success rate, average duration, DLQ depth
- Configurable alert thresholds stored in
pf_module_settings.custom_fields.observability_alert_thresholds - Permissions:
platform.automation.observability.view,platform.automation.observability.manage - DLQ metrics currently stubbed to 0 (FW-47 not yet implemented)
PF-96: Jurisdiction Profile Integration Layer
Location:@/platform/jurisdiction/
Status: 📝 Planned
Spec Reference: PF-96-medicaid-state-compliance-configuration.md
Integration Doc: PF-96-medicaid-state-compliance-configuration-INTEGRATION.md
Plan: PF-96-medicaid-state-compliance-configuration-PLAN.md
Purpose: Provides state-specific Medicaid compliance rules via a four-tier jurisdiction profile system (Federal Baseline → State Profile → Org Overrides → Site Overrides). Enables multi-state deployment without code changes by externalizing AHCCCS-specific rules to configuration.
Public API:
| Core | Spec | What It Reads | Usage |
|---|---|---|---|
| CL | CL-02 (Assessments) | clinical.assessment_required_elements, clinical.assessment_completion_hours | useClinicalRules() hook |
| CL | CL-04 (Progress Notes) | clinical.documentation_timeliness_hours, clinical.required_note_elements | useClinicalRules() hook |
| CL | CL-11 (Consent) | clinical.minor_consent_age, clinical.sud_confidentiality_standard | useClinicalRules() hook |
| CL | CL-40 (Intake) | clinical.intake_assessment_type | useClinicalRules() hook / edge function helper |
| PM | PM-07 (Charge Capture) | billing.min_billable_minutes, billing.modifier_conventions | useBillingRules() hook |
| PM | PM-08 (Claims) | billing.filing_deadline_days | useBillingRules() hook |
| PM | PM-10 (Prior Auth) | billing.bhrf_urgent_pa_exempt_days | useBillingRules() hook |
| PM | PM-18 (Scrub Rules) | billing.modifier_conventions | getJurisdictionProfile() edge fn |
| PM | PM-41 (Compliance Reports) | billing.compliance_window_hours | getJurisdictionProfile() edge fn |
| PF | PF-91 (Compliance Dashboard) | All rule packs | useJurisdictionProfile() hook |
- Resolution: Database RPC
pf_resolve_jurisdiction_profile(org_id, site_id?)merges federal baseline → state → org → site - Cache: Client-side with 5min staleTime, 10min gcTime
- Invalidation:
pf_jurisdiction_profile_changedevent (see EVENT_CONTRACTS.md) - Fallback: Profile resolution falls back to federal baseline if org profile unavailable
- State Medicaid profile seed data (Arizona AHCCCS, California Medi-Cal, Texas Medicaid, etc.)
- Organization-level and site-level profile assignment with override capability
- Federal baseline enforcement (HIPAA, 42 CFR Part 2, CMS-0057-F cannot be weakened)
- Admin UI for profile selection and override management
pf_jurisdiction_profiles— State profiles (shared reference data)pf_org_jurisdiction_config— Org-level assignment + overridespf_site_jurisdiction_config— Site-level overrides for multi-state orgs
pf.jurisdiction.view— View jurisdiction profile and rules (all org members)pf.jurisdiction.admin— Manage jurisdiction assignment and overrides (org admins)pf.jurisdiction.profiles.manage— Create/edit state profiles (platform admins only)
- Profile versions use semver format; updates apply to all orgs using that profile
- Array fields (e.g.,
assessment_required_elements) replaced entirely on override (not appended) - JSONB merge at rule-pack level (clinical, billing, compliance packs merged separately)
- Generic column aliases:
medicaid_member_id↔ahcccs_member_id,state_system_id↔ahcccs_cis_id
Related Documentation
- Integration Examples - Code examples
- Event Contracts - Event-based integration
- API Contracts - API-based integration
- Constitution - Engineering guardrails
docs/architecture/analysis/AI_INTEGRATION_STRATEGY_2026.md- AI feature roadmap (not yet authored)- Mobile Gesture Guide - Gesture patterns
PF-63: Entra ID Deep Integrations Layer
Location:/src/platform/integrations/Status: ✅ Complete
Version: 1.0.0
Implemented: 2026-02-21 Public API:
| Component | Purpose | Props |
|---|---|---|
PresenceBadge | Colored dot showing Teams availability | presence, size, showTooltip |
OOOBadge | ”OOO” badge indicator | isOOO, endDate (message redacted for PHI) |
SharePointDocumentBrowser | File/folder browser with upload, download, search | siteId, defaultFolder, className |
- All hooks filter by
organization_id - Mutation hooks include
created_by/updated_byaudit fields - OOO message content redacted to prevent PHI exposure
- Edge functions enforce
verifyOrgAccess()for cross-tenant isolation
- HR: Employee detail pages (presence badge, OOO status)
- PF: Organization settings (notification config, SharePoint browser)
- All cores: Can embed presence indicators on employee references
Next Review: 2026-03-24 (Quarterly)