Network Analysis — plain-language explainer

Network Analysis turns "who works with whom" into measurable structure — who connects teams, who brokers across silos, and which clusters the org actually splits into.

A People Analytics Toolbox component. Built to the portfolio Explainer Standard v1.0. Status note up front: this is a scout / scaffold slice, not a live spoke. What exists today is a feasibility memo and a contract sketch (src/spokes/network-analysis/, contract 0.0.1) — there is no database, no API route, no MCP module, and no registry registration yet. Everything in this explainer that describes runnable behavior is therefore marked (TBD / not yet built). A mostly-(TBD) explainer is the honest output for an under-built slice; the sections below describe the designed shape, grounded only in the contract types and scout memo that genuinely exist.

1. What is it?

Network Analysis is the toolbox's Organizational Network Analysis component: it owns the representation of relationship graphs (who is tied to whom, in what kind of network) and the graph analytics over them — centrality, brokerage-role labeling, and community detection — with versioned outputs.

The job it does, in one line: once edges exist between people, it answers structural questions a roster of names can't — who is central, who bridges otherwise-disconnected groups, and what the org's real communities are.

What it is not: it is not a survey collection engine. The scout memo is explicit that preference-modeler and reincarnation remain the name-elicitation and network-instrument engines; this component is the analytics layer that runs after edges have been contributed.

Visual — Tier B (in-repo contract reference). The five things it models are the five contract types in src/spokes/network-analysis/contracts/types.ts: Network (a relationship graph with a kind and a capturedAt), Edge (a directed-or-undirected tie with optional weight), CentralityResult (one metric value per principal), BrokerageRole (a Gould–Fernandez-style label), and Community (a detected cluster of principals with a modularity score).

2. What problem does it solve — and why is it different?

The pain it removes: org charts tell you the formal structure (who reports to whom), but the work actually flows through an informal structure — the collaboration, advice, and communication ties that no HRIS field records. Without measuring that structure, you can't see the single broker whose departure would sever two teams, or the silo that a reorg quietly created.

The difference, stated as a shift:

  • FROM a reporting tree plus intuition about "who really knows everyone."
  • TO computed structure — centrality scores, brokerage roles, and detected communities — over an explicit, provenance-stamped edge list.

How it differs from the obvious substitutes:

  • vs. doing it by hand / in a generic BI tool — betweenness centrality and Louvain community detection are graph algorithms, not spreadsheet aggregations; BI dashboards sum and group, they don't traverse a graph. The scout recommends graphology (MIT) as the graph-algorithm engine precisely because these computations don't reduce to a pivot table.
  • vs. a standalone ONA vendor — the design folds ONA into the same edge-and-attribute discipline as the rest of the toolbox: nodes are principals that already carry segmentation-studio attributes, and no analyst-facing subgraph is emitted until data-anonymizer certifies it, because network data re-identifies people faster than aggregate metrics. (Design intent per SCOUT.md; the enforcement code is (TBD / not yet built).)

Visual — Tier B (FROM→TO typographic block). The shift above is the visual; a rendered comparison block is a follow-up.

3. How does it work?

Inputs → method → outputs, as designed in the scout (the runtime is not yet built):

  • Input — edges. The default and only in-scope source for v0 is survey-elicited edges: name-elicitation / alter-roster items run through preference-modeler, or network-survey instruments delivered via reincarnation, normalized into Edge rows. The scout is deliberately explicit that silent metadata harvest (email graph, calendar co-attendance, Slack DMs) is out of scope by default — that path is a separate consent-and-compliance workstream, never a silent side channel.
  • Method — graph analytics. Load the edge list into a graphology Graph / DirectedGraph, then compute:
    1. Centrality — degree / in-degree / out-degree / betweenness / closeness / eigenvector / PageRank (the seven values of CentralityMetricSchema). Pure-TypeScript at modest scale; the scout's rule of thumb is roughly under 10k nodes per serverless batch before a batch job or external graph engine is needed.
    2. Community detection — Louvain first (graphology-communities-louvain, MIT), with Leiden and label propagation held as contract enums for alternative or research runs.
    3. Brokerage — Gould–Fernandez role counts (coordinator / gatekeeper / representative / consultant / liaison) over the directed graph.
  • Output — versioned results. CentralityResult rows (networkId, principalId, metric, value, computedAt), Community records (members + modularity + detectedBy), and brokerage labels — each gated by the privacy floor before any analyst sees a subgraph.

Differentiation beat: the practitioner's real question isn't "what's this person's PageRank" — it's "who can't we afford to lose, and where are the bridges between silos?" Brokerage labels and betweenness answer that directly: a high-betweenness, gatekeeper-labeled principal is a structural single point of failure, named.

The science backing: centrality measures and Gould–Fernandez brokerage are established social-network-analysis methods; Louvain/Leiden are standard modularity-maximizing community-detection algorithms. The component implements known graph science, not a novel scoring scheme.

Visual — Tier D (TBD). A live API capture would be the right visual here, but no API route exists yet — (TBD — a real POST /api/spokes/network-analysis/centrality capture, once the spoke is lifted).

4. What does it enable?

Concrete uses a practitioner would recognize (all contingent on the lift; designed, not yet runnable):

  • Find the structural single points of failure — high-betweenness, gatekeeper-labeled people whose exit would disconnect groups; a retention-risk lens the org chart can't produce.
  • Diagnose silos — community detection reveals the clusters the org actually splits into, which you can then compare against the formal reporting tree or business-unit segmentation.
  • Measure integration after a reorg or M&A — re-run on a later survey wave and watch whether two formerly separate communities have actually merged.
  • Spot informal influencers — eigenvector / PageRank surfaces the people others rely on regardless of title.
  • Characterize communities by attribute — join detected communities to segmentation-studio attributes to ask whether a cluster is, say, all one function or genuinely cross-functional.
  • Track a network panel over time — quarterly immutable snapshots (one of the scout's open design questions) would let centrality and community structure be trended across waves.

Visual — Tier D (TBD). (TBD — a community-map / ego-network illustration, once real results exist to render).

5. How it fits in the toolbox

Data flow, as designed (SCOUT.md dependency table):

  • Consumes — survey-elicited edges from preference-modeler (name-elicitation / alter rosters) and reincarnation (network-survey instruments), ingested at the API boundary, never by cross-importing those spokes' core/. Node attributes come from segmentation-studio via contracts/types only.
  • Gated by — data-anonymizer. The scout sets a k-anonymity floor of k ≥ 5 for any reported community, ego-network export, or subgraph; the component must not emit analyst-facing bundles until the anonymizer (or an equivalent gate) certifies the slice. Redaction is delegated, never hand-rolled here.
  • Emits — the Network / Edge / CentralityResult / Community / BrokerageRole contract (contracts/types.ts, version 0.0.1). Consumers will vendor a copy once the spoke is published; today there are no registry consumers.

Visual — Tier B (typographic data-flow). preference-modeler · reincarnation (edges) → Network Analysis (centrality · brokerage · communities) → data-anonymizer (k≥5 gate) → analyst-facing output, with segmentation-studio attributes joined in for community characterization.

6. Commercialization / packaging

Network Analysis is designed as a service component, not a standalone product — the analytics layer a network-survey or collaboration-diagnostic offering would compose, sitting behind a buyer-facing surface rather than being sold on its own.

  • Data-license posture: the default data source is respondent-contributed survey edges under a defined instrument — no third-party data license is involved in the v0 design. The privacy floor (k ≥ 5, anonymizer-gated) is a product constraint, not a licensing one.
  • Anything about pricing tiers or packaged offerings is (TBD / not yet built) — the spoke isn't live, so none is earned and none is stated.

Visual — Tier D (TBD — product-tier placement diagram, once the spoke ships).

7. The vision

Make the informal organization measurable and honest: surface who actually connects the work and where the silos are, computed from explicitly contributed ties, and never shown until the privacy floor is met.

The designed direction (open questions the lift, PAT-D4-B, must resolve, per SCOUT.md): directed-vs-undirected edge storage; network history as quarterly immutable snapshots vs. continuous updates; when centrality recomputes (wave-close vs. on-demand vs. scheduled); edge weighting (frequency vs. recency-decay vs. unweighted); and whether brokerage roles are materialized per run or computed on read. These are explicitly listed as open for the operator / lift, not decided.

8. Current status

Grounded in the real code state (contract 0.0.1, src/spokes/network-analysis/):

  • Shipped (scout only): the feasibility memo SCOUT.md, the README.md role definition, and the contract sketch contracts/types.ts (the Network / Edge / CentralityResult / BrokerageRole / Community Zod schemas + CONTRACT_VERSION = "0.0.1"). Session report: docs/session-reports/2026-05-21-pat-d4-network-analysis-scout.md.
  • Not yet built (TBD, all of it gated on the PAT-D4-B full lift): the network_analysis Postgres schema and Drizzle migration; any API route under /api/spokes/network-analysis/*; the graphology-backed core/ graph implementation; the MCP module and tool registration; the /health route and health-aggregate entry; and registry registration with a status flip. The spoke does not appear in src/lib/contracts/registry.ts and must pass the full spoke-onboarding checklist (check:spokes --scaffold) before being counted as live.

Visual — Tier B (in-repo status reference). The honest signal is the folder itself: src/spokes/network-analysis/ contains only README.md, SCOUT.md, and contracts/types.ts — no db/, api/, core/, mcp/, or tests/ directories exist.

Load-bearing worked example (clearly-labeled illustrative scenario)

This is an illustrative scenario, not real output — there is no running code to produce real values. It is grounded strictly in the real contract shapes in contracts/types.ts; every field name and enum value below is from that file. No metric value here is a measurement.

Scenario. A 40-person engineering org runs a name-elicitation survey through preference-modeler ("Who do you go to for technical advice?"). The responses normalize into Edge rows on one Network:

  • Network: { networkId: "net-eng-q2", name: "Eng advice network — Q2", kind: "collaboration", capturedAt: "2026-04-01T00:00:00Z" }
  • An Edge (directed advice tie, weighted by nomination frequency): { networkId: "net-eng-q2", fromPrincipalId: "p-118", toPrincipalId: "p-204", directed: true, weight: 3, edgeType: "advice", observedAt: "2026-04-01T00:00:00Z" }

Network Analysis would then (once built) compute and store, for one person:

  • CentralityResult: { networkId: "net-eng-q2", principalId: "p-204", metric: "betweenness", value: <computed>, computedAt: <ts> } — flagging p-204 as the bridge between two advice clusters, with a BrokerageRole of "gatekeeper".

And Louvain community detection would emit:

  • Community: { communityId: "c-1", networkId: "net-eng-q2", members: ["p-118", "p-204", ...], modularity: <computed>, detectedBy: "louvain" }

What a practitioner does with it: before that result is shown, data-anonymizer checks each community against the k ≥ 5 floor; a community of three would be suppressed. The analyst then sees that p-204 is the high-betweenness gatekeeper linking two otherwise-disconnected advice clusters — a named retention-and-resilience risk that the reporting tree never surfaced.

The <computed> placeholders are deliberate: no centrality value, modularity score, or brokerage count in this document is a real measurement, because the engine that would produce them is not yet built.