Technical Specification: Conversational Knowledge Graph

1. Introduction

The Conversational Knowledge Graph aims to provide a visually engaging, interactive, and physics-based force-directed graph representation of knowledge derived from conversational interactions. This spec outlines the technical approach to building this using a React Server Component (RSC) architecture.

2. Architecture Overview

In a Next.js App Router (RSC) environment, the architecture must separate server-side data fetching from client-side interactive rendering.

• Server Components (RSCs): Responsible for fetching graph data (nodes and edges) from the backend/database, performing heavy data transformations, and passing the initial serialized payload to the client.
• Client Components: Responsible for rendering the WebGL/Canvas context, running the physics engine, and handling user interactions (pan, zoom, click, hover).

3. Technology Stack Evaluation

For rendering a physics-based graph, the two primary contenders are D3.js and Three.js.

Option A: D3.js (SVG/Canvas)

• Pros: Excellent declarative API for mapping data to visuals, robust
  d3-force
  physics engine, huge ecosystem of examples.
• Cons: DOM/SVG-based rendering degrades quickly past 1,000 nodes. Canvas improves performance but requires manual render loops.

Option B: Three.js (WebGL via React Three Fiber)

• Pros: GPU-accelerated rendering capable of handling tens of thousands of nodes/edges simultaneously. True 3D spatial layouts.
• Cons: Steeper learning curve, complex event handling (raycasting).

Recommendation: Three.js using

4. Data Model

The basic structure passed from the RSC to the Client Component:

type Node = {
  id: string;
  label: string;
  group: string;
  val: number; // Represents node size/importance
  metadata: any;
};

type Link = {
  source: string; // Node ID
  target: string; // Node ID
  type: string;
  weight: number;
};

type GraphData = {
  nodes: Node[];
  links: Link[];
};

5. Physics Engine & Force Layout

To create an organic, self-organizing graph, we will use a force-directed layout engine (e.g.,

• Link Force: Pulls connected nodes together.
• Charge Force: Pushes all nodes away from each other (Coulomb repulsion) to prevent overlap.
• Center Force: Pulls all nodes toward the center of the coordinate system to keep the graph compact.

Optimization Note: For very large graphs, the force simulation calculations should be offloaded to a Web Worker to prevent blocking the main UI thread during layout stabilization.

6. Integration with React Server Components

// page.tsx (Server Component)
import { fetchGraphData } from '@/lib/api';
import GraphClientRenderer from './GraphClientRenderer';

export default async function KnowledgeGraphPage() {
  // Fetch initial graph data on the server
  const graphData = await fetchGraphData();
  
  return (
    <div className="w-full h-screen">
      <GraphClientRenderer initialData={graphData} />
    </div>
  );
}

// GraphClientRenderer.tsx (Client Component)
'use client';
import { useRef, useState } from 'react';
import ForceGraph3D from 'react-force-graph-3d';

export default function GraphClientRenderer({ initialData }) {
  const [data, setData] = useState(initialData);
  const fgRef = useRef();

  return (
    <ForceGraph3D
      ref={fgRef}
      graphData={data}
      nodeAutoColorBy="group"
      nodeThreeObject={(node) => {
        // Custom Three.js object for nodes
      }}
      onNodeClick={(node) => {
        // Handle conversational context update
      }}
    />
  );
}

7. Conversational UI Integration

The graph must sync with the conversational interface (chat UI):

1. Dynamic Updates: As the AI extracts new entities and relationships from the chat, a WebSocket or SSE connection pushes delta updates (new nodes/links) to the client. The graph component merges these updates seamlessly without restarting the entire physics simulation.
2. Contextual Focus: Clicking a node in the graph populates the chat input with the node's context. Conversely, typing a query in the chat can highlight related nodes in the graph using graph traversal algorithms.

8. Performance Optimizations

• Instanced Mesh Rendering: Use
  THREE.InstancedMesh
  to draw thousands of identical geometries (nodes) in a single draw call.
• Level of Detail (LOD): Fade out text labels and simplify geometries when the camera zooms out.
• Simulation Freezing: Pause the
  d3-force
  simulation once the graph reaches an equilibrium state (alpha decay reaches 0) to save CPU/battery.

9. Next Steps

1. Prototype a basic
   react-force-graph-3d
   implementation with mock data.
2. Define the exact JSON schema for the AI-extracted knowledge entities.
3. Setup the WebSocket infrastructure for real-time delta updates.