Spoke

org-graph

Typed org snapshots — temporal edges, dominant-dept inference, substring ELT bridging, QA + rollups.

Character

You live where dotted-line matrices, finance allocations, and HRIS managerial fields collide—yet leadership still trusts hand-drawn org charts for headcount narratives.

Problem

External. Finance reorganisations invalidate reporting lines silently while HR decks stale-date mid-quarter without anyone noticing.

Internal. You brute-force lookups in spreadsheets because Postgres lacks deterministic traversal helpers tuned to workforce grain.

Philosophical. Enterprises are graphs; pretending they're flat employee rows guarantees distorted stories.

Guide

Persist tenant org_snapshots rebuilt transactionally—typed edges (reports_to, finance overlays, bespoke hierarchies) honour effective intervals. Traverse ancestors, derive dominant departments, QA cycles, snapshot diffs, and leader KPI rollups—all mirrored over MCP POST verbs with PAT-148 consulting lineage noted in README. org-graph makes org truth queryable APIs instead of folklore.

Abstract

Background.Planning, compliance, and MEI overlays require reproducible hierarchies—not pivot charts from last Thursday's inbox export.

Methodology. Graph builds purge prior snapshot rows deterministically before inserting fresh traversable structures; traversal APIs honour operator overrides where configured; QA + snapshot diff tooling highlights structural regressions ahead of stakeholder readouts.

Scope. Graph substrate only—not performance appraisal scoring nor compensation optimisation.

Contribution. Explicit Zod envelopes + MCP + service-key gated rebuilds constrain AI explorers to auditable artefacts instead of scraped CSV folklore.

Evidence / Provenance. PAT-148 README cites consulting workbook lineage (Apps Script artefacts maintained external to repo).

Plan

01
Rebuild snapshots
Invoke graph/build after HRIS delta loads; Postgres stores fresh nodes plus edges keyed by tenant ids.
02
Query ancestry
Resolve manager chains plus finance overlays powering routing investigations, compliance scope, escalation paths.
03
QA before storytelling
Run consistency scanners and snapshot diff routes to catch orphaned nodes or contradictory edges before KPI rollups.
04
Emit leader metrics
Feed rollup/leaders payloads into MEI overlays, calibration narratives, restructuring retrospectives.

Call to Action

Direct. Smoke graph build payloads from PAT-148 README scaffolding.

Transitional. Digest decision memo detailing edge taxonomy + substring ELT bridging heuristics.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

Try it now

Copy this curl. Paste in any terminal. Public read — no auth needed.

org-graph.health

GET

Schema heartbeat verifying Postgres reachability before POST graph builders.

curl -sS "https://people-analytics-toolbox.vercel.app/api/spokes/org-graph/health"

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// Vendor canonical types:
// src/spokes/org-graph/contracts/types.ts

Source path: src/spokes/org-graph/contracts/types.ts · GitHub

Try in Dev Console Read the explainer Registry drill-down on /operator Back to all spokes

Failure

Restructuring math double-counts matrix workers while finance insists their tree is authoritative—trust evaporates ahead of filings.

Success

Effective-dated traversals with QA artefacts—every stakeholder references the immutable snapshot identifiers you regenerated this morning.