From 9f1f93217e7e3448a97bea13dfc1a2aa43f2633b Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 18 May 2026 12:50:59 +0200 Subject: [PATCH] Propose interactive Fabric map workplan --- ...RAIL-FAB-WP-0008-interactive-fabric-map.md | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md diff --git a/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md new file mode 100644 index 0000000..1a33583 --- /dev/null +++ b/workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md @@ -0,0 +1,159 @@ +--- +id: RAIL-FAB-WP-0008 +type: workplan +title: "Interactive Fabric Map" +domain: railiance +repo: railiance-fabric +status: proposed +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. + +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. + +## 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 map should support: + +- force 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 +- 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 +- graceful handling of registered-only repos that do not yet have local + `fabric/` declarations + +## 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: + +- 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 + +## Tasks + +### T01 - Map UX And Information Architecture + +```task +id: RAIL-FAB-WP-0008-T01 +status: todo +priority: high +state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08" +``` + +Define map views, entity visual grammar, navigation behaviors, and orientation +affordances. + +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. + +### T02 - Layout-Ready Graph Projection + +```task +id: RAIL-FAB-WP-0008-T02 +status: todo +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. + +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. + +### T03 - Interactive Auto-Layout Map UI + +```task +id: RAIL-FAB-WP-0008-T03 +status: todo +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. + +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. + +### T04 - Operational Orientation Workflows + +```task +id: RAIL-FAB-WP-0008-T04 +status: todo +priority: medium +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. + +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. + +### T05 - Verification And Documentation + +```task +id: RAIL-FAB-WP-0008-T05 +status: todo +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. + +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. +- Document how to launch the map and how to refresh the underlying registry + data.