feat(web): graph-lab Cosmograph PoC menu page#1791
Merged
Conversation
Per @earayu2 ask in #Graph可视化 (msg=4a8309e4): one menu page where
the team can flip between visualisation experiments without leaving
the production graph routes alone. The first two embedded modes are
both Cosmograph (`@cosmograph/react` 2.x): a topology renderer that
consumes the live `/api/v2/collections/{id}/graphs` payload, and a
semantic-map renderer that visualises a deterministic synthetic
fixture at 1k / 5k / 10k point scales for FPS benchmarking. The nav
also links out to the existing `/graph` and `/graph-showcase`
production pages so all four can be compared in adjacent tabs.
Why a PoC sibling instead of overwriting `graph-showcase`:
`graph-showcase/` already carries 745 LOC of an earlier
`react-force-graph-2d` exploration (see
`collection-graph-showcase.tsx`); replacing it would lose the prior
visual probe. PM ratified the new sibling path in DM (msg=30e30aab).
License caveat surfaced inline in the nav: `@cosmograph/react` is
CC-BY-NC-4.0 — explicitly fine for a PoC per @earayu2 (msg=26e5530d)
but flagged as a productionisation gate. The MIT-licensed
`@cosmos.gl/graph` engine is the intended swap target if the
visual direction sticks.
Files:
- `web/src/app/workspace/collections/[collectionId]/graph-lab/page.tsx`
Server component, breadcrumbs + container layout (mirror of
`graph-showcase/page.tsx`).
- `…/graph-lab/collection-graph-lab.tsx` Client shell, wires the nav
to one of two embedded renderers.
- `…/graph-lab/graph-lab-nav.tsx` Left rail with mode tabs +
external page links + license note.
- `…/graph-lab/cosmograph-topology.tsx` Live KG → Cosmograph Graph
mode. `dynamic({ ssr: false })` keeps the WebGL renderer out of the
server pass. Detail panel reuses cluster legend + selected-node
metadata.
- `…/graph-lab/cosmograph-semantic-map.tsx` Synthetic fixture →
Cosmograph embedding mode (`pointXBy`/`pointYBy` set, simulation
off). Scale toggle bench panel exposes generate-time + first-frame
latency for the 1k/5k/10k presets.
- `…/graph-lab/lab-modes.ts` Tiny shared module so the server-side
page.tsx stays import-light.
- `web/src/features/knowledge-graph/cosmograph-adapter.ts` Pure data
transform, `KnowledgeGraph → {points, links, clusterLabels}`. Two
entry points (`toTopologyDataset` for live data,
`buildSyntheticSemanticDataset` for deterministic fixture) so the
PoC can rebuild reproducibly under different scales.
§K.12 invariant cross-check
============================
Largely n/a (frontend exploratory PoC). Direct hits:
- #11 (read-only / not auto-action) — the lab page is read-only;
no merge/curate surface added.
- #12 (grep-zero LightRAG) — `rg -i lightrag web/src` returns zero
hits both before and after.
4-pattern pre-check matrix
==========================
- Pattern 1 v1 (existing graph routes): the production
`/graph` page (`collection-graph.tsx`) and the prior
`/graph-showcase` page are not modified; no imports moved or
renamed. `rg "from '\\..*collection-graph(-showcase)?'"` returns
only the original page bindings.
- Pattern 1 v2 (data-shape consumers): the new adapter consumes
`KnowledgeGraph`/`GraphNode`/`GraphEdge` from
`@/features/knowledge-graph/types` — same source the existing
graph page uses. No type duplication.
- Pattern 2 (response-shape change list): n/a, no API or schema
touched.
- Pattern 3 (additive helpers): the adapter and synthetic fixture
generator live in `features/knowledge-graph/`; both are pure
functions so the production graph page can adopt them later
without circular imports.
simple-stable directive 4-guardrail
===================================
- #1 不无限扩范围 — explicit PoC scope per @ziang acceptance
(msg=4db79b66). No backend changes; no `/api/v2/...` additions;
semantic mode uses front-end fixture data only.
- #2 尽快上线 — single-PR ship, ~0.5 day work envelope.
- #3 简单稳定 — production routes (`/graph`, `/graph-showcase`)
are byte-identical before/after this commit; PoC lives in its
own directory.
- #4 私有化部署免维护 — no operator config introduced. The
Cosmograph dependency is bundled with the rest of the web app;
productionisation will need a license decision (called out in
the nav UI itself so reviewers see it).
Test plan
=========
- `next dev --turbopack` reaches "Ready in 1476ms" cleanly post-add
(verified locally; SSR pass does not load `@cosmograph/react`).
- `yarn tsc --noEmit` reports zero errors in the new files
(`graph-lab/**`, `cosmograph-adapter.ts`). Five pre-existing
errors remain in `graph/collection-graph*.tsx` from PR #1789
and are out of scope.
- Manual smoke deferred to reviewer-side; the bench panel logs
generate-time + first-frame latency for the three scale presets
on render so a screenshot at each scale is enough to satisfy the
PoC acceptance items.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per @earayu2 ask in #Graph可视化 (msg=4a8309e4): one menu page where the team can flip between visualisation experiments without leaving the production graph routes alone. Two embedded Cosmograph modes — topology (live KG) and semantic map (synthetic 1k/5k/10k fixture) — plus external-page links to
/graphand/graph-showcasefor side-by-side comparison.Why a sibling and not overwriting
graph-showcase/:graph-showcase/already carries 745 LOC of an earlierreact-force-graph-2dexploration; replacing it would lose the prior probe. PM ratified the new sibling path in DM (msg=30e30aab).License caveat:
@cosmograph/reactis CC-BY-NC-4.0. @earayu2 explicitly fine for PoC (msg=26e5530d), called out in the nav UI as a productionisation gate. The MIT-licensed@cosmos.gl/graphengine is the swap target if the visual sticks.Files
graph-lab/page.tsx— server breadcrumbs + containergraph-lab/collection-graph-lab.tsx— client shell, nav ↔ renderer wiringgraph-lab/graph-lab-nav.tsx— left rail, mode tabs + external links + license notegraph-lab/cosmograph-topology.tsx— live KG → Cosmograph Graph mode (dynamic({ ssr: false }))graph-lab/cosmograph-semantic-map.tsx— synthetic fixture → embedding mode + scale toggle + bench panelgraph-lab/lab-modes.ts— shared types sopage.tsxstays import-lightfeatures/knowledge-graph/cosmograph-adapter.ts— pure data transform (toTopologyDataset/buildSyntheticSemanticDataset)§K.12 invariant cross-check
rg -i lightrag web/srcreturns zero hits before and after.4-pattern pre-check matrix
/graphand/graph-showcaseare unchanged; no imports moved/renamed.KnowledgeGraph/GraphNode/GraphEdgefrom@/features/knowledge-graph/types— same source the production graph uses. No type duplication.simple-stable directive 4-guardrail
/graphand/graph-showcasebyte-identical pre/post.Acceptance items (per @ziang msg=4db79b66)
graph-lab/route,graph/andgraph-showcase/untouched/api/v2/collections/{id}/graphsreact-force-graph-2d— deferred to reviewer-side; bench numbers will be visible in the panel as soon as the page loadsTest plan
next dev --turbopackreaches "Ready in 1476ms" cleanly post-add (SSR pass does not load@cosmograph/react)yarn tsc --noEmit→ zero errors in the new files. Five pre-existing errors remain ingraph/collection-graph*.tsx(from PR Wave 11: dynamic graph entity types #1789 dynamic-entity-types) and are out of scope.cd web && yarn dev, navigate to/workspace/collections/<id>/graph-lab, flip both modes, screenshot bench panel at each scale.🤖 Generated with Claude Code