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

# Org Data Sync & Lineage Integration

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

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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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)