diff --git a/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md index 1a33583..cdb68f6 100644 --- a/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md +++ b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md @@ -19,51 +19,116 @@ updated: "2026-05-18" ## Goal 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 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 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, and drill-down. +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 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 unresolved status - search across repo slugs, graph ids, names, capabilities, interfaces, and library names -- quick filters for active services, external interfaces, missing declarations, - unresolved dependencies, blast radius, and dependency path +- 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 -- 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 `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. -Likely implementation path: +Refined implementation path: -- add a map-oriented projection endpoint or CLI export that preserves existing - graph ids while adding visual facets -- serve a small local web UI from the registry service or a separate lightweight - static bundle -- use a proven browser graph/layout library instead of hand-rolling physics -- keep layout state client-side first; persist only after the workflows prove - useful +- 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 - Map UX And Information Architecture +### T01 - Repo-Scoping Transfer Review ```task id: RAIL-FAB-WP-0008-T01 @@ -72,18 +137,24 @@ priority: high state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08" ``` -Define map views, entity visual grammar, navigation behaviors, and orientation -affordances. +Review the repo-scoping graph implementation and turn RREG-WP-0010/RREG-WP-0011 +into concrete Fabric requirements and reusable-engine requirements. Acceptance notes: -- Decide initial visual grammar for repos, services, capabilities, interfaces, - dependencies, bindings, libraries, and registered-only repos. -- Decide default grouping and default filters for first load. -- Decide whether the first implementation uses a force-directed, layered, or - hybrid layout. +- 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 - Layout-Ready Graph Projection +### T02 - Manifest And Adapter Contract ```task id: RAIL-FAB-WP-0008-T02 @@ -92,16 +163,24 @@ priority: high state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168" ``` -Add or shape registry exports for map-friendly nodes, edges, groups, facets, and -stable identifiers. +Define the reusable graph explorer manifest, payload, filtering, and profile +contract that lets multiple repos mount the same visualization shell. Acceptance notes: -- Include registered repositories even when they have no graph snapshot yet. -- Include node type, domain, repo, lifecycle, unresolved flags, and edge type. -- Preserve stable ids so layout state and deep links do not churn. +- 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 - Interactive Auto-Layout Map UI +### T03 - Fabric Map Projection ```task id: RAIL-FAB-WP-0008-T03 @@ -110,36 +189,42 @@ priority: high state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3" ``` -Build a local interactive map with layout controls, filtering, search, zoom, -pan, and detail panels. +Add or shape Fabric registry exports for map-friendly nodes, edges, groups, +facets, unresolved gaps, and stable identifiers. Acceptance notes: -- The first screen is the actual map. -- Users can search, select, expand/collapse groups, and inspect details without - leaving the page. -- The map remains useful with the current sparse state where many repos are - registered-only. +- 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 - Operational Orientation Workflows +### T04 - Interactive Graph Explorer Shell ```task id: RAIL-FAB-WP-0008-T04 status: todo -priority: medium +priority: high state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0" ``` -Add workflows for blast-radius exploration, dependency paths, unresolved gaps, -repo grouping, and current selection sharing. +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: -- 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. +- 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 - Verification And Documentation +### T05 - Fabric Orientation Workflows ```task id: RAIL-FAB-WP-0008-T05 @@ -148,12 +233,37 @@ priority: medium state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67" ``` -Verify the map against seeded registry data, document usage, and capture -follow-on data quality gaps. +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: 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: - 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.