generated from coulomb/repo-seed
270 lines
11 KiB
Markdown
270 lines
11 KiB
Markdown
---
|
|
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.
|