# How to Generate an Interactive D3.js Visualization of the Code Graph in code-review-graph

> Generate an interactive D3.js visualization of your code graph with code-review-graph. This guide shows you how to transform GraphStore instances into dynamic force-directed charts effortlessly.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The repository ships a self-contained HTML generator that turns a `GraphStore` instance into a force-directed D3.js visualization.**

The `code-review-graph` project provides built-in tooling to transform static code analysis data into dynamic, explorable network diagrams. Whether you are auditing repository complexity or reviewing module dependencies, you can generate an interactive D3.js visualization of the code graph in code-review-graph using either Python APIs or a convenient CLI wrapper.

## Prerequisites: Building the GraphStore

Before rendering any visuals, you need a populated **GraphStore**. This object persists nodes, edges, and metadata extracted from your codebase. The store is implemented in [`code_review_graph/graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/graph.py) and serves as the data source for all visualization operations.

## Generating the HTML Visualization

The core logic resides in [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py), specifically within the `generate_html()` function. This utility exports graph data, selects an appropriate rendering mode, and bundles everything into a standalone HTML file.

### Programmatic Generation with Python

For custom workflows, import `generate_html` and pass a `GraphStore` instance:

```python
from code_review_graph.graph import GraphStore
from code_review_graph.visualization import generate_html

# Load an existing graph database

store = GraphStore(path="my_project.graphdb")

# Generate the interactive HTML file

html_path = generate_html(
    store,
    output_path="graph.html",
    mode="auto",
    max_full_nodes=3000,
    max_full_edges=9000,
)

print(f"Visualization written to {html_path}")

```

### Command-Line Interface

The package exposes a `visualize` subcommand that handles store initialization and HTML generation automatically:

```bash

# Build the graph database first

code-review-graph build

# Generate visualization (auto-mode)

code-review-graph visualize graph.html

# Serve locally to ensure the D3 asset is reachable

code-review-graph visualize --serve graph.html

```

## Understanding Rendering Modes

The `mode` parameter controls how the graph is aggregated to maintain performance. According to the source code, `generate_html()` accepts four strategies:

- **`auto`** (default): Automatically switches to *community* or *file* aggregation when node/edge counts exceed `DEFAULT_MAX_FULL_NODES` or `DEFAULT_MAX_FULL_EDGES` defined at the top of [`visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/visualization.py).
- **`full`**: Renders every individual node and edge in a force-directed layout.
- **`community`**: Aggregates nodes by detected community clusters.
- **`file`**: Aggregates at the file level for high-level architecture views.

Override auto-selection using `--mode=full` in the CLI or the `mode` argument in Python.

## How the HTML Generation Works

The `generate_html()` function performs three critical operations to produce the final file.

First, it calls `export_graph_data()` (lines 72-84) to extract nodes, edges, statistics, optional flows, and community information from the `GraphStore`.

Second, it constructs a JSON blob and injects it into a bundled HTML template (lines 558-560). The template contains a `__D3_SCRIPTS__` placeholder (lines 41-53) where the D3 logic is inserted.

Third, it ensures offline functionality by copying the vendored D3 build via `_write_d3_asset` (lines 56-84). This writes [`d3.v7.min.js`](https://github.com/tirth8205/code-review-graph/blob/main/d3.v7.min.js) from `code_review_graph/assets/` next to the output HTML, falling back to CDN only if the local asset is missing.

## Exploring the Interactive Features

Open the generated `.html` file in any modern browser to access the D3.js interface. The visualization supports:

- **Zoom and pan** for navigating large graphs
- **Node dragging** to rearrange the force layout manually
- **Searchable nodes** to quickly locate specific functions or files
- **Legend toggles** to filter by relationship types
- **Community coloring** to identify modular clusters
- **Help overlay** for keyboard shortcuts and controls

All interactivity is powered by the D3 v7 script injected during the generation phase.

## Summary

- The `generate_html()` function in [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py) is the primary entry point for creating visualizations.
- It supports four rendering modes (`auto`, `full`, `community`, `file`) to handle graphs of varying complexity.
- The function exports data via `export_graph_data()`, injects it into an HTML template, and vendors [`d3.v7.min.js`](https://github.com/tirth8205/code-review-graph/blob/main/d3.v7.min.js) for offline use.
- Use the Python API for custom integration or the `code-review-graph visualize` CLI for rapid generation.
- Generated files include interactive features like search, zoom, pan, and community highlighting.

## Frequently Asked Questions

### What is the default behavior when a graph becomes too large?

When `mode="auto"` is selected, the generator compares node and edge counts against `DEFAULT_MAX_FULL_NODES` and `DEFAULT_MAX_FULL_EDGES` thresholds. If the graph exceeds these limits, it automatically switches to community or file aggregation to prevent browser performance degradation.

### Can I view the visualization without an internet connection?

Yes. The `_write_d3_asset` function copies the vendored [`d3.v7.min.js`](https://github.com/tirth8205/code-review-graph/blob/main/d3.v7.min.js) from `code_review_graph/assets/` into the same directory as the output HTML. This allows the force-directed graph to render completely offline; the code only falls back to a CDN if the local file is missing.

### How do I force a full node-level view regardless of graph size?

Pass `mode="full"` to `generate_html()` in Python, or use `--mode=full` with the CLI command. Be aware that rendering thousands of nodes in a single force simulation may cause browser slowdowns or freezes.

### Where is the D3 JavaScript code stored in the repository?

The D3 library itself lives at [`code_review_graph/assets/d3.v7.min.js`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/assets/d3.v7.min.js). The interactive logic that creates the force simulation, drag behavior, and search functionality is embedded as a template string within [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py) and injected into the HTML via the `__D3_SCRIPTS__` placeholder during generation.