---
id: RAIL-FAB-WP-0008
type: workplan
title: "Interactive Fabric Map"
domain: railiance
repo: railiance-fabric
status: finished
owner: codex
topic_slug: railiance
planning_priority: high
planning_order: 8
state_hub_workstream_id: "0018ee65-dd90-4162-8837-c72d71f0dc9e"
created: "2026-05-18"
updated: "2026-05-18"
---

# RAIL-FAB-WP-0008 - Interactive Fabric Map

## Goal

Build a clever interactive auto-layouting map over the registered Fabric
entities so humans and agents can orient inside the infrastructure graph, while
keeping the visualization layer reusable enough to serve other graph-producing
repos.

The current repo has static graph exports through JSON and Mermaid. That is
useful for snapshots and docs, but it does not yet provide a navigable
orientation surface for the registered ecosystem.

Repo-scoping has already implemented the first serious local graph explorer
shape through RREG-WP-0010 and RREG-WP-0011. Fabric should reuse those lessons
instead of building a parallel one-off map.

Reference implementation inputs:

- `repo-scoping/docs/adr-dependency-graph-visualization-framework.md` selects
  Cytoscape.js for graph-native pan, zoom, selection, styling, filtering, and
  path exploration.
- `repo-scoping/docs/dependency-visualization-exploration.md` defines the
  layered graph model, display states, filter rules, manual overrides, and view
  profiles.
- `repo-scoping/src/repo_scoping/core/service.py` exposes Cytoscape-compatible
  graph payloads with stable keys, metadata-rich nodes and edges, deterministic
  show/blur/hide visibility evaluation, profile application, hidden element
  recovery data, and visual sizing hints.
- `repo-scoping/src/repo_scoping/web_ui/views.py` provides the current
  interactive shell: profile controls, filter controls, manual overrides,
  focus-by-depth, hover popups, selection details, and a layered preset layout.
- `repo-scoping/tests/test_web_api.py` verifies the graph endpoint, ad hoc
  filters, profile CRUD and duplicate behavior, latest-profile defaulting, and
  UI wiring.

## Design Direction

The first Fabric map should be an operational tool, not a landing page. It
should open directly into the graph and make the current infrastructure legible
through stable grouping, filtering, drill-down, and saved perspectives.

The map should support:

- force, cose, concentric, or layered auto-layout with stable seeded positions
- grouping by domain, repo, service, capability, interface, dependency, and
  unresolved status
- search across repo slugs, graph ids, names, capabilities, interfaces, and
  library names
- quick filters for review state, active services, external interfaces, missing
  declarations, unresolved dependencies, blast radius, and dependency path
- display states of `show`, `blur`, and `hide`, with deterministic rule
  precedence and manual overrides
- hover and selection detail panels with links back to registry endpoints,
  State Hub repo ids, workplans, and source files where available
- saved view profiles with filter rules, manual overrides, timestamps,
  duplicate/delete behavior, latest-profile defaulting, URL `profile_id`
  loading, and orphaned override reporting
- shareable map state through URL query parameters, profile ids, or a copied
  state blob
- graceful handling of registered-only repos that do not yet have local
  `fabric/` declarations

The reusable engine should be manifest-driven. Fabric and repo-scoping should be
able to wire the same interaction shell to different graph-producing services by
providing a manifest that describes:

- graph and profile endpoint URLs
- node and edge identity fields
- layer ordering and grouping fields
- visual encodings for kind, layer, review state, lifecycle, confidence,
  strength, freshness, and unresolved status
- filterable fields and supported rule actions
- detail-panel fields and deep links
- available modes such as full graph, impact, selected path, neighborhood focus,
  and onboarding gaps
- profile persistence capabilities for each host application

## Architecture Notes

Keep the registry as the data source. The UI should consume registry exports and
queries rather than reloading repo files directly.

Refined implementation path:

- define a host-neutral graph manifest and payload contract that can represent
  both repo-scoping dependency graphs and Fabric ecosystem graphs
- add a Fabric map projection endpoint or CLI export that preserves existing
  graph ids while adding visual facets expected by the engine
- prototype a small local web UI as a reusable graph explorer shell, likely with
  Cytoscape.js unless the transfer review finds a better fit for the
  cross-repo contract
- wire Fabric through an adapter manifest rather than hard-coding Fabric fields
  throughout the UI
- verify that a repo-scoping adapter could consume the same shell with minimal
  glue, using RREG-WP-0010 and RREG-WP-0011 behavior as the parity target
- decide whether the graph explorer should be extracted into a separate
  repository after the manifest contract and first two adapters stabilize

Candidate extraction shape:

- working name: `graph-explorer-engine`
- reusable package: static graph explorer assets plus TypeScript or JSON schema
  definitions for manifests, payloads, rules, profiles, and visual facets
- host adapters: Fabric registry adapter and repo-scoping dependency graph
  adapter
- host responsibilities: authentication, storage, graph projection, profile
  persistence, and deep-link targets
- engine responsibilities: layout, filtering, display-state evaluation if not
  provided by host, hover and selection UI, profile control surface, focus
  modes, and shareable state

## Tasks

### T01 - Repo-Scoping Transfer Review

```task
id: RAIL-FAB-WP-0008-T01
status: done
priority: high
state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08"
```

Review the repo-scoping graph implementation and turn RREG-WP-0010/RREG-WP-0011
into concrete Fabric requirements and reusable-engine requirements.

Acceptance notes:

- Identify which repo-scoping behaviors should be reused directly: Cytoscape
  payload shape, layered layout, show/blur/hide display states, filter rules,
  manual overrides, view profiles, hover popups, focus depth, latest profile
  defaulting, review-state filtering, confidence sizing, and strength sizing.
- Identify repo-scoping-specific pieces that should remain adapter logic:
  fact/evidence/feature/capability/ability/scope layers, impact analysis, and
  candidate-vs-accepted semantics.
- Decide the first Fabric visual grammar for repos, services, capabilities,
  interfaces, dependencies, bindings, libraries, State Hub links, unresolved
  gaps, and registered-only repos.
- Capture a short extraction recommendation before implementation starts.

### T02 - Manifest And Adapter Contract

```task
id: RAIL-FAB-WP-0008-T02
status: done
priority: high
state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168"
```

Define the reusable graph explorer manifest, payload, filtering, and profile
contract that lets multiple repos mount the same visualization shell.

Acceptance notes:

- Define required and optional graph payload fields, including `id`,
  `stableKey`, `kind`, `layer`, label, description, source references,
  review/lifecycle state, confidence, freshness, unresolved state, ownership,
  visual size, edge type, edge strength, same-layer hints, and deep links.
- Define a manifest schema for endpoints, layer order, grouping fields, style
  tokens, detail fields, search fields, filterable fields, graph modes, profile
  capabilities, and shareable state support.
- Decide whether display-state evaluation lives in the host service, the engine,
  or both with a clear precedence rule.
- Include compatibility notes for repo-scoping's existing graph API so an
  adapter can be added without forcing a repo-scoping rewrite.

### T03 - Fabric Map Projection

```task
id: RAIL-FAB-WP-0008-T03
status: done
priority: high
state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3"
```

Add or shape Fabric registry exports for map-friendly nodes, edges, groups,
facets, unresolved gaps, and stable identifiers.

Acceptance notes:

- Include registered repositories even when they have no graph snapshot yet.
- Include node type, domain, repo, lifecycle, State Hub ids, unresolved flags,
  declaration source links, and edge type.
- Preserve stable ids so layout state, profiles, and deep links do not churn.
- Export a manifest-backed graph payload that can be consumed by the reusable
  shell without Fabric-specific UI branches.

### T04 - Interactive Graph Explorer Shell

```task
id: RAIL-FAB-WP-0008-T04
status: done
priority: high
state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
```

Build the manifest-driven interactive map shell with layout controls, filtering,
search, zoom, pan, hover popups, selection details, focus modes, and profile
controls.

Acceptance notes:

- The first screen is the actual map.
- Users can search, select, filter, blur, hide, focus by depth, inspect details,
  and recover hidden or over-filtered elements without leaving the page.
- The shell supports profile create/update/duplicate/delete where the host
  manifest declares persistence support.
- The map remains useful with the current sparse state where many repos are
  registered-only.

### T05 - Fabric Orientation Workflows

```task
id: RAIL-FAB-WP-0008-T05
status: done
priority: medium
state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67"
```

Add Fabric-specific workflows for blast-radius exploration, dependency paths,
unresolved gaps, repo grouping, onboarding gaps, and shareable context.

Acceptance notes:

- Selecting an interface can show consumers and blast radius.
- Selecting a service can show its dependency path and provider chain.
- Registered-only repos are visible as onboarding gaps rather than noise.
- Saved views can separate current operational context from backlog or
  onboarding cleanup.

### T06 - Extraction Decision, Verification, And Documentation

```task
id: RAIL-FAB-WP-0008-T06
status: done
priority: medium
state_hub_task_id: "d5567337-efe7-4fe6-8379-9e5505e25f6f"
```

Decide whether to extract the graph explorer into a separate repository, verify
the Fabric implementation against seeded registry data, and document launch,
refresh, manifest, and adapter usage.

Acceptance notes:

- Verify against the local registry after `registry/local-repos.yaml` onboarding.
- Include at least one automated projection/API test and one UI smoke test.
- Include an adapter parity checklist for repo-scoping against
  RREG-WP-0010/RREG-WP-0011 behavior.
- If extraction is recommended, propose the new repo name, source boundaries,
  package/public API, manifest schema ownership, and migration steps.
- Document how to launch the map and how to refresh the underlying registry
  data.