railiance-fabric/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, state_hub_workstream_id, created, updated

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

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

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

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

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

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

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.