[epic] Graph VISUALIZATION — design, performance & UX (Fable 5 audit, 2026-07-03)

[Santisoutoo]

Epic tracking the fixes from a design + performance + UX audit of the knowledge-graph visualization (the "Grafo" page, the law-detail graph tab, and the related-laws panel). Audit run 2026-07-03 by a dedicated Fable-5 agent against the real code.

Verdict

Structurally sound but not yet something to headline to users. The engineering hygiene is genuinely good (memoised simulation data, offscreen + reduced-motion pausing, lazy chunking, server-side 250-node cap), but what users actually SEE is a single-colour force blob with four decorative legend entries, five dead buttons, fabricated right-rail copy, and no hover feedback — and the advertised "global graph" view doesn't exist in the UI (useGlobalGraph has zero consumers).

Headline findings

• Monochrome hairball — communities computed and thrown away. The backend computes a community per node and carries it to meta.community, but the canvas never reads it — every live node renders one indigo (or grey if repealed). The 5-kind legend advertises article/reference/amendment kinds that only exist in mock data.
• Edge kinds have never rendered. projectEdge hard-codes kind: 'cites' (graph.ts:50-57) even for the subgraph endpoint where the backend does ship kind. The 4-colour edge palette + legend are decorative. The graph is directed but has no arrowheads — "A modifies B" vs "B modifies A" (legally critical) is invisible.
• Five dead controls on the Grafo page: the search input, "Filtros avanzados", "PNG" export, both zoom buttons, and "Pin" have no handlers. Inert aria-labelled buttons are worse than absent ones.
• Fabricated right-rail copy — every law node shows "Norma con 169 artículos y 1.248 referencias entrantes." (a constant string), while real metadata sits unused in node.meta.
• No hover affordance (no tooltip, no neighbour highlight, no cursor change) — the single highest-leverage polish, and cheap in this library.
• RelatedLaws shows arbitrary subgraph members, not related laws — it filters nodes of the depth-2 subgraph, not edges, so it lists 2-hop laws with no direct relation, in backend iteration order.
• The "global graph" is unshipped and would melt if wired as-is (per-request nx.pagerank + greedy_modularity over thousands of nodes, uncached). PageRank/communities must be precomputed at build time (the code already flags this).
• @xyflow/react is a dependency with zero imports — the "xyflow for detail" locked decision is no longer in code.

Backlog (→ split into the sprint issues below)

Full detail (file:line evidence + metrics) in memory/fable_graph_viewer_audit_2026-07-03.md.

Sprint A — correctness + quick wins (ship before showing the page):

• fix: satisfy new ruff rules and bump 4 CVE-flagged dependencies #1 fix(graph): surface typed edges end-to-end (backend kind on /graph + read it in projectEdge) [S]
• [Feature]: Empaquetado con Tauri 2 + PyInstaller sidecar #5 fix(graph): honest right rail — real metadata + true 1-hop neighbours in RelatedLaws [S]
• [Sprint 6.1] Tauri 2 wrapper + binarios sin firmar (Win/Mac/Linux) #7 feat(graph): deep-linkable seed (/graph?law=<id>) + context-preserving law-detail handoff [S]
• [epic] Frontend redesign & product polish — clean/acrylic design language #10 fix(graph): theme-reactive canvas + dim-vs-hide filter semantics [S]
• [editor] AI-assisted drafting on the RAG stack #12 chore(frontend): drop unused @xyflow/react dependency [S]

Sprint B — design:

• feat: autonomous agent loop (OpenCode worker + reviewer + Orca supervision) #2 feat(graph): colour nodes by community, encode kind by ring/shape, data-driven legend [M]
• [Epic]: Fase 6 — Producto: empaquetado y distribución #3 feat(graph): hover tooltip + neighbourhood highlight + directional arrows [M]
• [Feature]: Editor de documentos legales con citas tipadas y chat integrado #4 fix(graph): wire or remove the five dead controls (zoom, search, PNG, filters, pin) [M]

Sprint C — scale:

• [Feature]: Auto-update con Tauri Updater plugin #6 perf(graph): precompute PageRank + communities at build time + truncation metadata [M]
• [Sprint 6.2] Distribución vía package managers (winget + Homebrew + Flathub) #8 feat(graph): global corpus view with node budget + LOD [L] (depends on [Feature]: Auto-update con Tauri Updater plugin #6)
• [Sprint 6.3] Auto-update + provenance (firma free) #9 feat(graph): path-between-laws UI on /graph/path [M]
• [epic] Extensive automated test coverage — catch what silently broke #11 test(graph): unit + e2e coverage for the viz path [M]

Top 3 highest-leverage moves

1. Typed edges (fix: satisfy new ruff rules and bump 4 CVE-flagged dependencies #1) + community colouring (feat: autonomous agent loop (OpenCode worker + reviewer + Orca supervision) #2) — ~2 days, turns the visual from generic to legible legal cartography.
2. Hover + arrows + working controls ([Epic]: Fase 6 — Producto: empaquetado y distribución #3+[Feature]: Editor de documentos legales con citas tipadas y chat integrado #4) — makes it feel like a product, not a demo.
3. Backend precompute of PageRank/communities ([Feature]: Auto-update con Tauri Updater plugin #6) — the prerequisite for any real global view.

Ship Sprint A+B before showing the Grafo page in marketing material. Related-laws correctness overlaps the graph reference-inference epic VforVitorio#775.

Labels: epic, area: graph.

---

Upstream: VforVitorio#782