Encore OS — Documentation

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

Table	Purpose
`pf_org_data_sync_events`	Tracks org data change propagation events
`pf_data_lineage`	Records data flow relationships between entities
`pf_data_lineage_archive`	Archived lineage records (3+ years old)
`pf_retention_log`	Logs retention job executions
`pf_org_hierarchies`	Placeholder 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

Hook	Purpose
`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

Component	Purpose
`ChangeImpactPreview`	Sheet showing affected modules before org changes
`PropagationStatus`	Table of sync events with retry capability
`LineageVisualization`	React Flow graph of data lineage

Permissions

Key	Description	Roles
`pf.org_data_sync.view`	View sync events	org_admin, staff
`pf.org_data_sync.retry`	Retry failed events	org_admin
`pf.data_lineage.view`	View data lineage	org_admin (CR-341: restrict to org_admin only; staff access removed — lineage data reveals organizational data flow topology)

Edge Functions

Function	Purpose
`org-data-sync-consumer`	Polls pending events, dispatches to module handlers
`org-data-sync-retry`	Resets 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

Path	Component	Permission
`/settings/sync-status`	`SyncStatusPage`	`pf.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)

Organization URL Routing — Integration Page Layouts & PF-32 Conditional Field Logic Integration

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Org Data Sync & Lineage Integration

Overview

Integration Pattern

Tables

Event Contract

Platform API

Import Path

Hooks

Components

Permissions

Edge Functions

Module Handler Interface

Routes

Deferred

​Overview

​Integration Pattern

​Tables

​Event Contract

​Platform API

​Import Path

​Hooks

​Components

​Permissions

​Edge Functions

​Module Handler Interface

​Routes

​Deferred

Overview

Integration Pattern

Tables

Event Contract

Platform API

Import Path

Hooks

Components

Permissions

Edge Functions

Module Handler Interface

Routes

Deferred