coulomb/railiance-fabric
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine interactive Fabric map workplan

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 13:49:09 +02:00
parent 251637c1b4
commit ae4f567a2b
1 changed files with 158 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md
View File

@@ -19,51 +19,116 @@ updated: "2026-05-18"
## Goal ## Goal
Build a clever interactive auto-layouting map over the registered Fabric Build a clever interactive auto-layouting map over the registered Fabric
entities so humans and agents can orient inside the infrastructure graph. 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 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 useful for snapshots and docs, but it does not yet provide a navigable
orientation surface for the registered ecosystem. 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 ## Design Direction
The first map should be an operational tool, not a landing page. It should open The first Fabric map should be an operational tool, not a landing page. It
directly into the graph and make the current infrastructure legible through should open directly into the graph and make the current infrastructure legible
stable grouping, filtering, and drill-down. through stable grouping, filtering, drill-down, and saved perspectives.
The map should support: The map should support:
- force or layered auto-layout with stable seeded positions - force, cose, concentric, or layered auto-layout with stable seeded positions
- grouping by domain, repo, service, capability, interface, dependency, and - grouping by domain, repo, service, capability, interface, dependency, and
unresolved status unresolved status
- search across repo slugs, graph ids, names, capabilities, interfaces, and - search across repo slugs, graph ids, names, capabilities, interfaces, and
library names library names
- quick filters for active services, external interfaces, missing declarations, - quick filters for review state, active services, external interfaces, missing
unresolved dependencies, blast radius, and dependency path 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, - hover and selection detail panels with links back to registry endpoints,
State Hub repo ids, workplans, and source files where available State Hub repo ids, workplans, and source files where available
- shareable map state through URL query parameters or a copied state blob - 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 - graceful handling of registered-only repos that do not yet have local
`fabric/` declarations `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 ## Architecture Notes
Keep the registry as the data source. The UI should consume registry exports and Keep the registry as the data source. The UI should consume registry exports and
queries rather than reloading repo files directly. queries rather than reloading repo files directly.
Likely implementation path: Refined implementation path:
- add a map-oriented projection endpoint or CLI export that preserves existing - define a host-neutral graph manifest and payload contract that can represent
graph ids while adding visual facets both repo-scoping dependency graphs and Fabric ecosystem graphs
- serve a small local web UI from the registry service or a separate lightweight - add a Fabric map projection endpoint or CLI export that preserves existing
static bundle graph ids while adding visual facets expected by the engine
- use a proven browser graph/layout library instead of hand-rolling physics - prototype a small local web UI as a reusable graph explorer shell, likely with
- keep layout state client-side first; persist only after the workflows prove Cytoscape.js unless the transfer review finds a better fit for the
useful 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 ## Tasks
### T01 - Map UX And Information Architecture ### T01 - Repo-Scoping Transfer Review
```task ```task
id: RAIL-FAB-WP-0008-T01 id: RAIL-FAB-WP-0008-T01
@@ -72,18 +137,24 @@ priority: high
state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08" state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08"
``` ```
Define map views, entity visual grammar, navigation behaviors, and orientation Review the repo-scoping graph implementation and turn RREG-WP-0010/RREG-WP-0011
affordances. into concrete Fabric requirements and reusable-engine requirements.
Acceptance notes: Acceptance notes:
- Decide initial visual grammar for repos, services, capabilities, interfaces, - Identify which repo-scoping behaviors should be reused directly: Cytoscape
dependencies, bindings, libraries, and registered-only repos. payload shape, layered layout, show/blur/hide display states, filter rules,
- Decide default grouping and default filters for first load. manual overrides, view profiles, hover popups, focus depth, latest profile
- Decide whether the first implementation uses a force-directed, layered, or defaulting, review-state filtering, confidence sizing, and strength sizing.
hybrid layout. - 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 - Layout-Ready Graph Projection ### T02 - Manifest And Adapter Contract
```task ```task
id: RAIL-FAB-WP-0008-T02 id: RAIL-FAB-WP-0008-T02
@@ -92,16 +163,24 @@ priority: high
state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168" state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168"
``` ```
Add or shape registry exports for map-friendly nodes, edges, groups, facets, and Define the reusable graph explorer manifest, payload, filtering, and profile
stable identifiers. contract that lets multiple repos mount the same visualization shell.
Acceptance notes: Acceptance notes:
- Include registered repositories even when they have no graph snapshot yet. - Define required and optional graph payload fields, including `id`,
- Include node type, domain, repo, lifecycle, unresolved flags, and edge type. `stableKey`, `kind`, `layer`, label, description, source references,
- Preserve stable ids so layout state and deep links do not churn. 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 - Interactive Auto-Layout Map UI ### T03 - Fabric Map Projection
```task ```task
id: RAIL-FAB-WP-0008-T03 id: RAIL-FAB-WP-0008-T03
@@ -110,36 +189,42 @@ priority: high
state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3" state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3"
``` ```
Build a local interactive map with layout controls, filtering, search, zoom, Add or shape Fabric registry exports for map-friendly nodes, edges, groups,
pan, and detail panels. facets, unresolved gaps, and stable identifiers.
Acceptance notes: Acceptance notes:
- The first screen is the actual map. - Include registered repositories even when they have no graph snapshot yet.
- Users can search, select, expand/collapse groups, and inspect details without - Include node type, domain, repo, lifecycle, State Hub ids, unresolved flags,
leaving the page. declaration source links, and edge type.
- The map remains useful with the current sparse state where many repos are - Preserve stable ids so layout state, profiles, and deep links do not churn.
registered-only. - Export a manifest-backed graph payload that can be consumed by the reusable
shell without Fabric-specific UI branches.
### T04 - Operational Orientation Workflows ### T04 - Interactive Graph Explorer Shell
```task ```task
id: RAIL-FAB-WP-0008-T04 id: RAIL-FAB-WP-0008-T04
status: todo status: todo
priority: medium priority: high
state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0" state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
``` ```
Add workflows for blast-radius exploration, dependency paths, unresolved gaps, Build the manifest-driven interactive map shell with layout controls, filtering,
repo grouping, and current selection sharing. search, zoom, pan, hover popups, selection details, focus modes, and profile
controls.
Acceptance notes: Acceptance notes:
- Selecting an interface can show consumers and blast radius. - The first screen is the actual map.
- Selecting a service can show its dependency path and provider chain. - Users can search, select, filter, blur, hide, focus by depth, inspect details,
- Registered-only repos are visible as onboarding gaps rather than noise. 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 - Verification And Documentation ### T05 - Fabric Orientation Workflows
```task ```task
id: RAIL-FAB-WP-0008-T05 id: RAIL-FAB-WP-0008-T05
@@ -148,12 +233,37 @@ priority: medium
state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67" state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67"
``` ```
Verify the map against seeded registry data, document usage, and capture Add Fabric-specific workflows for blast-radius exploration, dependency paths,
follow-on data quality gaps. 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: todo
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: Acceptance notes:
- Verify against the local registry after `registry/local-repos.yaml` onboarding. - 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 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 - Document how to launch the map and how to refresh the underlying registry
data. data.