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

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 and serves as the data source for all visualization operations.

Generating the HTML Visualization

The core logic resides in 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:

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:

# 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.
• 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 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 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 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 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. 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 and injected into the HTML via the __D3_SCRIPTS__ placeholder during generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}