RFC: graph-layers as the docs-graph renderer + LLM search surface

[charlieforward9]

Motivation

Closing #534 surfaced a better use of AI-assistance effort here: use the repo's own graph-layers module to turn the deck.gl-community docs into a graph that both LLMs and humans can navigate. Each node = a module / export / example; each edge = an import, doc cross-reference, or "see also". Rendering this as a force-directed graph reveals structural gaps (low-connection nodes = likely underdocumented or orphaned areas) and gives agents a high-signal index over the site.

This is the same fan-in pattern as the editable-layers RFC: every AI channel — text tool-calls, vision pointing via thor.gl, speech-to-intent — can query or highlight the same doc graph once the graph itself is the stable contract.

This RFC covers two deliverables landing on the website:

1. A graph view of the doc / module graph.
2. An LLM search surface that queries the graph rather than blob-grepping the docs.

Why now

graph-layers has had substantial investment recently — see backlog below — and building a canonical consumer (our own docs) forces the public surface to be usable and exercises the in-flight improvements end-to-end.

Renderer choice — graph-layers vs Cosmograph

Before committing to graph-layers as the docs-graph renderer, we should evaluate @rokotyan's cosmograph-org/cosmos side-by-side. Cosmos is a WebGL force-directed graph library tuned for very large graphs (100k+ nodes) with a GPU layout that is already production-tested.

Decision matrix we'd want answered:

Dimension	graph-layers	Cosmograph
Install — drops onto an existing deck.gl site	Native — one more @deck.gl-community/* package	Adjacent lib; needs a second canvas or iframe bridge
Maintenance — who owns bugs / releases	This repo	External (rokotyan-led)
Scale — demonstrated node counts	TBD, needs benchmark	100k+ nodes shipping
Layout quality on long-tail doc graph	D3 / GPU force, recent lifecycle work	Cosmos GPU force + quadtree
Interop — picking, transitions, other deck layers on top	Composable with any deck layer	Standalone canvas
Headless / SSR for build-time snapshots	deck.gl can render offscreen	Browser-only AFAIK

Pinging @rokotyan for input on whether Cosmograph is the better substrate here, and/or whether there are lessons from Cosmos that graph-layers should absorb. @ibgreen — this evaluation is also a forcing function for the upstream-path question below.

Scope

In scope

• Ingestion: extract nodes / edges from the monorepo (tsdoc exports, example imports, markdown cross-refs). Likely reuses / motivates Add GraphML loader for graph-layers #419 (GraphML loader).
• Rendering: force-directed view on the website. Primary candidate: graph-layers (GraphLayer + D3 / GPU force layout). Evaluate Cosmograph as alternative / fallback for very large graphs.
• LLM query: tool-call that takes a natural-language query and returns ranked graph paths (e.g. "editable-layers examples that use MapboxOverlay").
• "Low-connection" highlight mode so maintainers can spot orphaned docs / modules at a glance.

Out of scope

• General-purpose graph-editor UI.
• Non-docs graphs — graph-layers already covers those.

UX goal — installing, maintaining, and visualizing docs should be a breeze

Success criterion is not "we shipped a graph view." It is that the graph makes the docs cheaper to own:

• Install — one command regenerates the doc graph on every build; no separate service, no manual ingestion step.
• Maintain — adding a new module or example automatically shows up as a node; dead links and orphans surface in the viewer, not in a nightly report nobody reads.
• Visualize — every node has a shareable URL; graph state (filters, highlighted paths) is query-string serializable so LLM answers can link directly to "this view of the graph."

If any of those costs a contributor more than a few lines of code or config, the design is wrong.

Upstream path — how community graph layers land in core deck.gl

Open question @ibgreen should weigh in on: what is the promotion path from deck.gl-community/graph-layers into upstream deck.gl use cases? Today the community package is a soft parking lot; a canonical consumer like the docs graph raises the pressure on that question:

• Does a mature graph-layers eventually become a first-party @deck.gl/* module?
• Or does it stay community-owned and upstream ships examples that depend on it?
• What is the bar — API stability, test coverage, maintainer coverage — and how do the backlog PRs below map to that bar?

Clarifying this now affects how much we invest in graph-layers API polish vs. just shipping a docs-graph that works.

Open questions

1. Graph source of truth — generated at build time, committed, or both? Committed = diffable; generated = always-fresh.
2. Edge types — import, doc-reference, "see also", test-reference. One weighted graph or multiple overlays?
3. Layout stability — incremental updates need the streaming / lifecycle work in the PRs below to land first.
4. Renderer — graph-layers primary, or Cosmograph primary with graph-layers as deck-native overlay? Needs @rokotyan / @ibgreen input against the matrix above.

Backlog to address alongside

Tracker: #78 (graph-layers module)

Graph-layers open PRs that should be evaluated for merge / alignment before this RFC lands:

• Refine graph viewer inline data handling #422 — Refine graph viewer inline data handling
• Fix GraphLayer normalized graph data inputs #421 — Streamline loader data inputs
• Add GraphML loader for graph-layers #419 — GraphML loader for graph-layers (direct enabler)
• Ensure D3 force layout emits lifecycle updates #395 — Ensure D3 force layout emits lifecycle updates
• Add GraphLayout.setProps lifecycle and refactor layouts to use it #393 — GraphLayout.setProps lifecycle
• feat(graph-layers) Reorder layout APIs ahead of internal helpers #389 — Reorder layout APIs ahead of internal helpers
• Unify graph runtime adapters behind GraphInterface #385 — Unify graph runtime adapters behind GraphInterface
• Ensure GPUForceLayout start events fire reliably #383 — Ensure GPUForceLayout start events fire reliably
• Stream D3 force layout tick updates #380 — Improve D3 force layout streaming updates
• Add synced mini-map and collapsed chain breadcrumbs #355 — Synced mini-map and collapsed chain breadcrumbs
• Add GraphLayer layout redraw throttling #352 — Layout update throttling control
• Refine edge attachment helper geometry extraction #350 — Refine edge attachment helper geometry
• feat(graph-layers): edge attachment helper for GraphLayer #348 — Edge attachment helper for GraphLayer

Related

• Closed: feat: add @deck.gl-community/visgl-skills — AI agent skills for deck.gl #534 — visgl-skills
• Trackers: Tracker: graph-layers module #78 graph-layers, Tracker: layers module #80 layers
• External: cosmograph-org/cosmos

cc @rokotyan @ibgreen