# How the Graph Visualization UI Works in Codebase Memory MCP: Architecture and Setup Guide

> Learn how the graph visualization UI works in Codebase Memory MCP. Discover its architecture and setup guide for this interactive 3D knowledge graph powered by React and Three.js.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: architecture
- Published: 2026-07-30

---

**The graph visualization UI is an optional React and Three.js frontend that renders an interactive 3D knowledge graph when enabled via the `--ui` flag, served by an embedded HTTP server on port 9749.**

The **graph visualization UI** in the `DeusData/codebase-memory-mcp` repository provides a browser-based interface for exploring codebase relationships as interactive 3D networks. Unlike the default headless mode, this UI variant bundles a React application that communicates with the MCP daemon via JSON-RPC endpoints. Understanding the architecture and activation process allows developers to leverage visual graph analysis for large-scale codebases.

## Architecture Overview

The UI implementation spans two distinct layers: a compiled React frontend and an embedded HTTP server written in C. When built with the UI variant, the binary serves static assets from `graph-ui/dist/` while simultaneously exposing RESTful endpoints for graph data retrieval.

**Core frontend components** reside in the `graph-ui/` directory and include:

- **[`graph-ui/src/main.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/main.tsx)** – Boots the React application via `createRoot(...).render(<App/>)`
- **[`graph-ui/src/App.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/App.tsx)** – Handles routing and tab selection (`graph`, `stats`, `control`) based on URL query parameters
- **[`graph-ui/src/components/GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphScene.tsx)** – Manages the Three.js canvas, creating meshes for nodes and edges while handling camera interactions
- **[`graph-ui/src/components/GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphTab.tsx)** – Controls the graph interface including node budgets, filtering toggles, and the detail sidebar
- **[`graph-ui/src/hooks/useGraphData.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/hooks/useGraphData.ts)** – Wraps the `/api/layout` endpoint with streaming support and download progress tracking
- **[`graph-ui/src/api/rpc.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/api/rpc.ts)** – Provides a minimal JSON-RPC client for tool invocation

The **server-side** implementation in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) registers HTTP routes including `/api/layout`, `/api/repo-info`, and `/rpc`, enabling the frontend to query the underlying knowledge graph.

## Data Flow from Server to Screen

Understanding the request lifecycle clarifies how the system handles large graph layouts efficiently.

1. **Static asset delivery** – When accessing `http://localhost:9749`, the server serves the compiled React bundle from `graph-ui/dist/`
2. **Layout computation** – `GraphTab` invokes `useGraphData().fetchOverview()`, which triggers a GET request to `/api/layout?project=…&max_nodes=…`
3. **Streaming response** – The daemon processes the request, runs the layout algorithm, and streams a JSON payload containing node coordinates (`x`, `y`, `z`), edge mappings, and metadata
4. **Scene construction** – [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx) receives the parsed data and instantiates Three.js meshes for each node and edge, applying display density settings from [`density.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/density.ts)
5. **State persistence** – All UI preferences (node budgets, filter selections, panel widths) serialize to `localStorage` via helpers in [`GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx) (lines 44-52)

## Enabling the Graph Visualization UI

The UI is **not** included in default binary builds. You must install or build the UI-specific variant.

### Installation via Install Script

The quickest method uses the official installer with the `--ui` flag:

```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh \
| bash -s -- --ui

```

This executes `scripts/build.sh --with-ui`, linking the React assets directly into the final executable.

### Package Manager Installation

For Node.js or Python environments, set the `CBM_VARIANT` environment variable:

```bash

# npm installation

CBM_VARIANT=ui npm install -g codebase-memory-mcp

# PyPI installation

CBM_VARIANT=ui pip install codebase-memory-mcp

```

### Manual Installation

Download the pre-built UI variant from the Releases page:

```bash
wget https://github.com/DeusData/codebase-memory-mcp/releases/download/vX.X.X/codebase-memory-mcp-ui-linux-x64.tar.gz
tar -xzf codebase-memory-mcp-ui-linux-x64.tar.gz

```

### Starting the Server

Launch the UI-enabled daemon on the default port (9749):

```bash
codebase-memory-mcp --ui=true --port=9749

```

Verify the server is serving the interface:

```bash
curl -s http://localhost:9749 | grep "Codebase Memory"

```

Open your browser to `http://localhost:9749`, select a project from the **Projects** tab, then navigate to the **Graph** tab to explore the 3D visualization.

## Key Implementation Details

### Fetching Graph Data（useGraphData.ts）

The `fetchLayout` function streams large graph data while reporting progress. Located in [`graph-ui/src/hooks/useGraphData.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/hooks/useGraphData.ts) (lines 43-84), it handles the chunked transfer from `/api/layout`:

```typescript
import { fetchLayout } from "./hooks/useGraphData";

async function loadGraph(project: string) {
  const data = await fetchLayout(project, 5000, (prog) => {
    console.log(`Loaded ${prog.receivedBytes}/${prog.totalBytes} bytes`);
  });
  console.log(`Graph has ${data.nodes.length} nodes`);
}

```

### Rendering the 3D Scene（GraphScene.tsx）

The `GraphScene` component in [`graph-ui/src/components/GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphScene.tsx) initializes the Three.js scene, camera, and renderer. It creates instanced meshes for nodes and edges, optimizing memory usage for graphs containing hundreds of thousands of entities.

### UI State Management（GraphTab.tsx）

Filter toggles and node budgets are managed in [`graph-ui/src/components/GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphTab.tsx). The following pattern handles label filtering (lines 13-20):

```typescript
const toggleLabel = useCallback((label: string) => {
  setEnabledLabels((prev) => {
    const next = new Set(prev);
    next.has(label) ? next.delete(label) : next.add(label);
    return next;
  });
}, []);

```

Node budget preferences persist across sessions via `localStorage`:

```typescript
function loadNodeBudget(project: string): number {
  const v = localStorage.getItem(`cbm-node-budget:${project}`);
  return v ? clampNodeBudget(parseInt(v, 10)) : GRAPH_RENDER_NODE_LIMIT;
}

```

## Summary

- The **graph visualization UI** requires the UI variant build and is not included in default installations
- The architecture consists of a **React frontend** (`graph-ui/src/`) and an **embedded HTTP server** ([`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c))
- Data flows from the `/api/layout` endpoint through [`useGraphData.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useGraphData.ts) to the **Three.js** renderer in [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx)
- Enable via `--ui=true` flag or install using `--ui` with the install script
- All state persists to **localStorage** for session continuity

## Frequently Asked Questions

### What port does the graph visualization UI use by default?

The UI server listens on **port 9749** by default when started with `--ui=true`. You can override this using the `--port` flag.

### Is the graph visualization UI included in the default installation?

No. The default binary is headless. You must install the **UI variant** using `--ui` with the install script, `CBM_VARIANT=ui` with package managers, or download the specific `-ui` release archive.

### Which technologies power the 3D rendering?

The 3D visualization uses **Three.js** accessed via the [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx) component, while the UI framework is **React** with **Vite** as the build tool, as configured in [`graph-ui/vite.config.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/vite.config.ts).

### How does the UI handle large codebases?

The system implements **streaming JSON responses** through the `/api/layout` endpoint, allowing the frontend to process graph data chunks progressively. Additionally, the **node budget** feature in [`GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx) limits rendered entities to maintain interactive frame rates, with uncovered files represented in a "missed skeleton" view.