Skip to main content

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.

Version: 1.0
Status: ✅ Implemented
Last Updated: 2026-02-27

​
Overview

PF-18 provides real-time organizational data synchronization and data lineage tracking across all cores. When org entities (departments, sites) change, affected modules are notified via sync events and lineage is automatically captured.

​
Integration Pattern

Type: Event-Based + Platform Layer
Publisher: PF (via pg_notify on pf_org_data_sync_events INSERT)
Consumer: org-data-sync-consumer Edge Function
Channel: org_data_changes

​
Tables

TablePurpose
pf_org_data_sync_eventsTracks org data change propagation events
pf_data_lineageRecords data flow relationships between entities
pf_data_lineage_archiveArchived lineage records (3+ years old)
pf_retention_logLogs retention job executions
pf_org_hierarchiesPlaceholder for Phase 4 hierarchy features

​
Event Contract

Event: org_data_changed
Channel: org_data_changes (pg_notify) 
interface OrgDataChangedPayload {
  event_id: string;        // pf_org_data_sync_events.id
  organization_id: string;
  entity_type: string;     // 'department' | 'site'
  entity_id: string;
  event_type: string;      // 'department_renamed' | 'site_updated' | etc.
  change_type: string;     // 'create' | 'update' | 'delete'
  affected_modules: string[]; // ['hr', 'fa', 'rh']
}

​
Platform API

​
Import Path

import {
  useChangeImpact,
  useSyncEventsList,
  useRetrySyncEvent,
  useLineageBySource,
  useLineageByDestination,
  ChangeImpactPreview,
  PropagationStatus,
  LineageVisualization,
  exportLineageCsv,
  exportLineageJson,
} from '@/platform/org-data-sync';

​
Hooks

HookPurpose
useChangeImpact(orgId, entityType, entityId)Preview affected modules before committing changes
useSyncEventsList(orgId, limit?)List recent sync events with status
useRetrySyncEvent()Reset failed event to pending
useLineageBySource(orgId, entityType, entityId)Get downstream lineage graph
useLineageByDestination(orgId, entityType, entityId)Get upstream lineage graph

​
Components

ComponentPurpose
ChangeImpactPreviewSheet showing affected modules before org changes
PropagationStatusTable of sync events with retry capability
LineageVisualizationReact Flow graph of data lineage

​
Permissions

KeyDescriptionRoles
pf.org_data_sync.viewView sync eventsorg_admin, staff
pf.org_data_sync.retryRetry failed eventsorg_admin
pf.data_lineage.viewView data lineageorg_admin (CR-341: restrict to org_admin only; staff access removed — lineage data reveals organizational data flow topology)

​
Edge Functions

FunctionPurpose
org-data-sync-consumerPolls pending events, dispatches to module handlers
org-data-sync-retryResets failed event to pending (permission-gated)

​
Module Handler Interface

Cores implement handlers in the consumer edge function: 
type ModuleHandler = (
  supabase: ServiceClient,
  event: Record<string, unknown>,
) => Promise<{ processed: number }>;
Currently stub handlers for: hr, fa, rh. Cores implement real handlers as needed.

​
Routes

PathComponentPermission
/settings/sync-statusSyncStatusPagepf.org_data_sync.view

​
Deferred

  • Phase 4: Advanced hierarchy features (pf_org_hierarchies table created but not consumed)
  • Partitioning on pf_data_lineage (deferred until volume warrants)
  • hr_employees lineage trigger (deferred to avoid conflicts)