Entity Graph: server-side BFS + enhanced visualization

[damienriehl]

Summary

Port the Entity Graph implementation from folio-mapper to ontokit-web as a full-stack feature: a server-side BFS graph building endpoint on the API side, and enhanced React Flow visualization components on the frontend.

This replaces the current client-side graph building (Phase 6A) with a faster, more scalable server-driven approach while preserving ontokit's ontology-agnostic node type system.

Motivation

The current graph visualization builds the graph client-side by iteratively fetching individual class details — limited to ~100 nodes and slow for deep hierarchies. folio-mapper's implementation uses server-side BFS traversal that returns a complete subgraph in one response (up to 200 nodes with truncation detection), handles seeAlso cross-links properly, and supports progressive node expansion.

Proposed Changes

Backend (ontokit-api)

• New endpoint: GET /api/v1/projects/{id}/ontology/graph/{iri} — server-side BFS traversal
• Configurable: ancestors_depth, descendants_depth, max_nodes, include_see_also
• Returns: nodes + edges + truncation flag + total concept count
• BFS upward (ancestors to root), downward (descendants), and lateral (seeAlso cross-links)

Frontend (ontokit-web)

• Replace buildGraphData.ts (client-side builder) with API-backed data fetching
• Port EntityGraphModal — full-screen overlay with close/Esc support
• Port ConceptNode — adapted with ontokit's node types (focus, class, root, individual, property, external, unexplored)
• Port HierarchyEdge — subClassOf (solid) + seeAlso (dashed purple) + equivalentClass + disjointWith
• Port useELKLayout — ELK layered algorithm with TB/LR direction toggle
• Keep both inline graph (detail panel toggle) AND full-screen modal (expand button)

Coloring (ontology-agnostic)

• Branch root / ultimate ancestor nodes: red accent
• Other ancestor nodes: dark gray accent
• Focus node: blue accent
• seeAlso edges: purple dashed
• subClassOf edges: solid gray
• No hardcoded ontology-specific colors — lineage determines color

Reference Implementation

• folio-mapper frontend: packages/ui/src/components/mapping/graph/ (EntityGraph, ConceptNode, HierarchyEdge, useELKLayout)
• folio-mapper backend: backend/app/services/folio_service.py lines 861-1024 (build_entity_graph())
• folio-mapper types: packages/core/src/folio/graph-types.ts

Testing Plan

• Backend: BFS traversal returns correct ancestor/descendant/seeAlso subgraph
• Backend: Truncation flag set when node count exceeds max_nodes
• Frontend: Graph renders with correct node types and lineage-based colors
• Frontend: Inline graph toggle works in both standard and developer layouts
• Frontend: Full-screen modal opens/closes correctly
• Frontend: Progressive node expansion (click unexplored → fetch 1-hop neighbors)
• Frontend: Direction toggle (TB ⟷ LR) relayouts correctly
• E2E: Works with FOLIO ontology and at least one non-FOLIO ontology

🤖 Generated with Claude Code

[damienriehl]

PR #88 implements this: server-side BFS graph endpoint + enhanced React Flow visualization, replacing the client-side graph builder. All 103 tests pass. Visual verification done on both developer and standard layouts.

[damienriehl]

Implementation complete — merged on FOLIO, pending CatholicOS review

Frontend PR: #88 | Backend PR: CatholicOS/ontokit-api#37

What shipped

• Server-side BFS entity graph replacing client-side builder
• OWL restriction seeAlso parsing (FOLIO uses owl:someValuesFrom restrictions, not direct triples)
• Multi-root visualization: primary root (red) + seeAlso branch roots (dark gray), all aligned at top
• ELK layered layout with non-hierarchical seeAlso edges, root pinning, spline routing
• EntityGraphModal (full-screen), inline Graph tab (developer mode), Graph button (standard mode)
• Progressive node expansion, direction toggle (TB/LR), Show Descendants

Verification

Production-verified at https://ontokit.openlegalstandard.org — "Motion to Dismiss" shows 20 nodes, 26 edges, 3 roots (Document / Artifact, Service, Status), matching Mapper and Enrich exactly.

Status

• ✅ Merged on alea-institute (FOLIO) — both web and API
• ⏳ CatholicOS PRs awaiting review (branch protection requires approving review)

[damienriehl]

Branch cleanup — rebased onto latest main

The original entity-graph-migration branch had accumulated 170 commits mixing entity graph + LLM helper work. Separated into clean branches:

• entity-graph-clean — 2 commits on top of latest catholicos/main: the graph migration code (16 files) + planning docs
• llm-helper — renamed from entity-graph-migration, continues LLM helper work independently

What's on entity-graph-clean

• Replace buildGraphData.ts + elkLayout.ts with server-side BFS via graphApi.getEntityGraph()
• New: lib/api/graph.ts, lib/graph/useELKLayout.ts, lib/graph/utils.ts, components/graph/EntityGraphModal.tsx
• Rewritten: useGraphData.ts (single API call + progressive expansion)
• Updated: OntologyGraph, OntologyNode, OntologyEdge, both layout components
• Planning context: .planning/features/entity-graph-port/ (CONTEXT, HANDOFF, PLAN)

Verification

• ✅ Type-check: 0 errors
• ✅ Tests: 103/103 pass
• ✅ Based on latest catholicos/main (commit a1f496d)

Next steps

• PR Port entity graph to server-side BFS endpoint #88 will be superseded by a new PR from entity-graph-clean (cleaner diff, current base)
• Backend PR Add server-side BFS entity graph endpoint ontokit-api#37 still applies as-is

[damienriehl]

PR #88 updated — force-pushed clean entity-graph-clean branch (2 commits on latest catholicos/main) to replace the old 170-commit mixed branch. PR description updated to match.

Ready for review. Backend dependency: CatholicOS/ontokit-api#37.

[JohnRDOrazio]

UX discussion: graph view node interactions

As the entity graph nears completion, we should clarify the interaction model for clicking nodes in the graph view. See the detailed discussion on PR #88 (comment).

Key questions:

1. Should clicking a node select it in the class tree, or just expand its children in the graph?
2. Should we add an expand caret within each node (like the class tree has) to separate "select" from "expand"?
3. The viewport doesn't follow the clicked node after layout updates — this needs fixing regardless of which interaction model we choose.

The proposed model mirrors the class tree: click the node body to select it, click an expand chevron to expand children in-graph. This keeps both views consistent.