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