generated from coulomb/repo-seed
Archive closed workplans to workplans/archived/ (ADR-001)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0009
|
||||
type: workplan
|
||||
title: "Graph Explorer UI Refinement"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 9
|
||||
created: "2026-05-18"
|
||||
updated: "2026-05-19"
|
||||
state_hub_workstream_id: "1d797e74-bb26-4107-9221-db1248c2cb0e"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0009 - Graph Explorer UI Refinement
|
||||
|
||||
## Goal
|
||||
|
||||
Refine the interactive Fabric graph explorer user interface before extracting
|
||||
it into a shared `graph-explorer-engine` repository. The shell is still local
|
||||
to `railiance-fabric`, so this is the right moment to improve the interaction
|
||||
model, visual hierarchy, orientation workflows, and large-graph ergonomics
|
||||
while the engine boundary is still flexible.
|
||||
|
||||
This workplan intentionally comes before extraction. The goal is to learn from
|
||||
using the Fabric map against the current local registry, then turn the refined
|
||||
UI into a stronger reusable engine candidate.
|
||||
|
||||
## Design Direction
|
||||
|
||||
The explorer should feel like an operational map, not a demo page. It should
|
||||
make the registered infrastructure legible at a glance, then let a user narrow
|
||||
into services, interfaces, dependencies, onboarding gaps, and saved operational
|
||||
views without losing context.
|
||||
|
||||
Refinement should focus on:
|
||||
|
||||
- a calmer, denser toolbar that still exposes the important controls
|
||||
- clearer information architecture for the graph, selection details,
|
||||
orientation hints, saved views, node visibility, and edge visibility
|
||||
- map-first behavior where the graph remains the dominant surface
|
||||
- useful empty, loading, and error states
|
||||
- visual encodings that make repo/service/interface/dependency/binding node types
|
||||
distinguishable without becoming noisy
|
||||
- explicit node-type and edge-type controls that support multi-selection
|
||||
- a filtering model that separates hiding from removing entities from layout
|
||||
- contextual controls that explain which attributes and modifiers apply to
|
||||
which node and edge types
|
||||
- floating map navigation controls and selection anchors that do not depend on
|
||||
changing node borders
|
||||
- better onboarding-gap and unresolved-dependency workflows
|
||||
- URL and browser-local saved views that are understandable to a human user
|
||||
- responsive behavior that remains usable on laptop and narrow screens
|
||||
- bubble-help explanations, keyboard, focus, contrast, and screen-reader basics
|
||||
- explicit seams for a later repo-scoping adapter and shared engine extraction
|
||||
|
||||
## Extraction Guardrail
|
||||
|
||||
Do not extract during this workplan. Extraction should wait until:
|
||||
|
||||
- the Fabric UI refinement has produced a clearer shell contract
|
||||
- the repo-scoping adapter parity work has proven a second real host
|
||||
- any UI assumptions that are Fabric-specific have been moved behind manifest
|
||||
fields, payload metadata, or host-provided mode definitions
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Baseline UI Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a8cfcf75-d03d-4c2f-8d9a-72ea3607775b"
|
||||
```
|
||||
|
||||
Run the current graph explorer against the local registry and capture concrete
|
||||
UI friction before changing the implementation.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Start the local registry and open `/ui/graph-explorer`.
|
||||
- Review desktop and narrow viewport behavior.
|
||||
- Exercise search, filters, mode switching, selection, focus, manual
|
||||
overrides, saved views, copied state URLs, and reset behavior.
|
||||
- Capture a concise refinement backlog in repo docs or the workplan.
|
||||
- Identify which issues block real use and which can wait for extraction.
|
||||
- Confirm where the current UI still says `Layer`, where global controls like
|
||||
Review and Unresolved are ambiguous, and which terms need bubble help.
|
||||
|
||||
Closeout note, 2026-05-19: this task is intentionally dropped as a remaining
|
||||
Codex-side blocker. The in-app browser visual review is unreliable in the
|
||||
desktop sandbox, and it is not required for the actual local service review.
|
||||
The explorer runs locally at `http://127.0.0.1:8765/ui/graph-explorer`, so
|
||||
visual review should happen in a normal browser while Codex continues to use
|
||||
tests, generated JavaScript compilation, and live HTTP checks.
|
||||
|
||||
### T02 - Node And Edge Control Architecture
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c"
|
||||
```
|
||||
|
||||
Refine terminology, toolbar structure, side panel placement, map controls,
|
||||
saved-view controls, legend, hidden-summary surface, and orientation hints so
|
||||
the graph remains central and the controls are easier to scan.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Replace user-facing `Layer` wording with `Nodes`, `Node type`, or
|
||||
`Node types`. Internal manifest fields may keep `layer` until extraction if
|
||||
that avoids churn.
|
||||
- Replace the single node layer selector with a multi-select node type control.
|
||||
- Add a multi-select edge type control for showing and hiding relationships by
|
||||
edge type.
|
||||
- Move pan, zoom, fit, focus, and reset navigation controls into a floating map
|
||||
menu.
|
||||
- Reduce visual clutter in the toolbar without hiding core workflows.
|
||||
- Give selection details, orientation workflows, saved views, and legend
|
||||
predictable places.
|
||||
- Make hidden/blurred overrides and active filters easy to understand.
|
||||
- Keep the first screen as the working map, not documentation.
|
||||
|
||||
### T03 - Graph Readability, Layout Semantics, And Selection Anchors
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade"
|
||||
```
|
||||
|
||||
Improve graph readability through better node-type styling, labels, edge
|
||||
treatment, selection affordances, unresolved/onboarding markers, layout
|
||||
defaults, and repo-local layout affinity.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Node type colors are distinguishable and not dominated by one hue family.
|
||||
- Node and edge labels do not overwhelm dense views.
|
||||
- Selected, hovered, hidden, blurred, unresolved, and registered-only states are
|
||||
visually distinct.
|
||||
- Selection is represented by an arrow or anchor pointing to the focused entity
|
||||
rather than by relying on border changes.
|
||||
- A selected entity can be hidden and unhidden without losing the selection
|
||||
anchor; the anchor changes only when focus changes.
|
||||
- Repo-local nodes stay closer together than cross-repo relationships, while
|
||||
servers and deployments bind tightly to their runtime/deployment entities and
|
||||
more loosely to service repos.
|
||||
- Default layout gives a useful first impression with the current registry data.
|
||||
|
||||
### T04 - Filter Rule Builder And Visibility Semantics
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93"
|
||||
```
|
||||
|
||||
Design and implement an optional filtering panel that can express detailed
|
||||
node and edge rules without turning type-specific attributes into unexplained
|
||||
global controls.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Users can create a list of rules that target nodes or edges by type and by
|
||||
supported attributes.
|
||||
- Type-specific concepts such as Review and Unresolved appear only when they
|
||||
apply to the selected node or edge types, either as contextual controls or
|
||||
rule templates.
|
||||
- Rules can apply modifiers such as show, hide, blur, highlight, or remove.
|
||||
- Node and edge filtering supports two explicit result modes: hide while
|
||||
preserving the current layout, or remove from layout and redraw the graph.
|
||||
- The active rule list is inspectable, editable, reorderable, and resettable.
|
||||
|
||||
### T05 - Bubble Help, Accessibility, Responsiveness, And Failure States
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "67a9cbc9-ebaa-4cb1-bec9-46bf250faf41"
|
||||
```
|
||||
|
||||
Harden the graph explorer UI for basic accessibility, responsive use, and
|
||||
failure handling before it becomes a candidate shared engine. Explain the
|
||||
domain terms directly where users encounter them.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add bubble-help explanations to graph terms and controls, including Nodes,
|
||||
Node types, Edge types, Layout, Review, Unresolved, Hide, Remove, Blur,
|
||||
Focus, Fit, and saved views.
|
||||
- Bubble help must explain what the control changes, whether it affects layout,
|
||||
and why a term might not apply to every node or edge type.
|
||||
- Controls have useful labels, focus order, and keyboard-accessible behavior.
|
||||
- Text fits on narrow and desktop viewports.
|
||||
- Loading, empty graph, fetch failure, and missing Cytoscape states are
|
||||
understandable.
|
||||
- Tests cover the static UI wiring for new states and controls.
|
||||
|
||||
### T06 - Repo-Scoping Adapter Readiness Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "934ea4d9-0d36-414d-9ed7-10f39410da8d"
|
||||
```
|
||||
|
||||
Review the refined UI against the repo-scoping parity checklist before creating
|
||||
the adapter workplan.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Identify remaining Fabric-specific assumptions in the UI shell.
|
||||
- Confirm which controls should be manifest-driven before extraction.
|
||||
- Confirm that user-facing node and edge terminology can be supplied through
|
||||
manifest labels or host-provided vocabulary without leaking Fabric internals.
|
||||
- Confirm that the rule-panel data model can support repo-scoping manifests as
|
||||
well as Fabric ecosystem manifests.
|
||||
- Update `docs/graph-explorer-operations.md` or contract docs with any refined
|
||||
engine boundary.
|
||||
- Recommend whether the next workplan should be repo-scoping adapter parity or
|
||||
one more Fabric-side UI hardening pass.
|
||||
|
||||
### T07 - Orientation Workflow Polish
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6cf1fb8b-9d50-4550-942a-69bc29d14eaa"
|
||||
```
|
||||
|
||||
Make the Fabric-specific orientation workflows easier to use for service
|
||||
dependencies, interface consumers, onboarding gaps, unresolved dependencies,
|
||||
and saved operational contexts after the node, edge, and rule controls are in
|
||||
place.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Selecting a service shows a readable dependency/provider chain.
|
||||
- Selecting an interface shows consumers and impact context.
|
||||
- Registered-only repos are visible as actionable onboarding gaps.
|
||||
- Saved local views have understandable names, status, and sharing behavior.
|
||||
- Orientation workflows reuse the same hide/remove, node type, edge type, and
|
||||
selection anchor semantics as the rest of the map.
|
||||
Reference in New Issue
Block a user