How to View the Interactive D3.js Code Graph Visualization in code-review-graph

The repository ships a self-contained HTML generator that converts a GraphStore instance into a force-directed D3.js visualization, accessible via the code-review-graph visualize CLI command or the generate_html() Python API.

The code-review-graph toolkit by tirth8205 enables developers to explore code relationships through interactive web-based graphs. The visualization system, implemented in code_review_graph/visualization.py, automatically bundles the D3.js library and supports multiple rendering modes to handle projects of varying complexity.

Core Architecture and Data Export

The visualization pipeline begins with the export_graph_data() function in code_review_graph/visualization.py (lines 72-84). This method extracts structured data from a GraphStore instance, including:

• Nodes and edges representing code entities and their relationships
• Statistics about the graph structure
• Optional flow information and community detection data

The GraphStore class, defined in code_review_graph/graph.py, serves as the data source that persists these elements to the graph database.

Rendering Modes and Thresholds

The generate_html() function controls how the graph renders based on project scale. It accepts a mode parameter with the following options:

• "auto" (default): Automatically switches to community or file aggregation when node/edge counts exceed safe rendering limits
• "full": Renders every individual node and relationship
• "community": Aggregates nodes by detected communities
• "file": Aggregates by file-level groupings

The auto-selection thresholds are defined as constants at the top of code_review_graph/visualization.py:

• DEFAULT_MAX_FULL_NODES
• DEFAULT_MAX_FULL_EDGES

When the graph exceeds these limits, the system downsamples to maintain browser performance.

Command-Line Workflow

Before visualizing, build the graph database for your target repository:

# 1. Build the graph database

code-review-graph build

# 2. Generate visualization with automatic mode selection

code-review-graph visualize output.html

# 3. Force full detail rendering

code-review-graph visualize output.html --mode=full

# 4. Serve locally to ensure D3 assets are reachable

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

The CLI internally instantiates a GraphStore, calls generate_html(), and handles asset bundling. The function builds a JSON blob and injects it into the bundled HTML template (lines 558-560 of visualization.py). The --serve flag starts a local server to host the vendored D3 library.

Programmatic Generation

For custom workflows, generate the HTML directly from Python:

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

# Load existing graph database

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

# Generate interactive visualization

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

This approach allows you to override the default thresholds and integrate visualization generation into automated pipelines.

Interactive Features and Offline Support

The generated HTML file is fully self-contained and works offline. The _write_d3_asset() function (lines 56-84) copies the vendored d3.v7.min.js from code_review_graph/assets/ into the output directory alongside the HTML.

The D3.js implementation supports:

• Zoom and pan navigation
• Node dragging to rearrange the force-directed layout
• Searchable nodes for quick navigation
• Legend toggles to filter by relationship type
• Community coloring based on detection algorithms
• Help overlay with usage instructions

The JavaScript code is injected via the __D3_SCRIPTS__ placeholder in the HTML template (lines 41-53 of visualization.py).

Summary

• The visualization engine lives in code_review_graph/visualization.py and operates on GraphStore instances from code_review_graph/graph.py.
• generate_html() supports four rendering modes, with "auto" intelligently selecting between full detail and aggregated views based on DEFAULT_MAX_FULL_NODES and DEFAULT_MAX_FULL_EDGES thresholds.
• Use code-review-graph visualize for CLI generation, or import generate_html() for programmatic control.
• Output files bundle d3.v7.min.js for offline viewing and include interactive features like zoom, pan, drag, and search.

Frequently Asked Questions

Where is the D3.js visualization logic implemented?

According to the tirth8205/code-review-graph source code, the core logic resides in code_review_graph/visualization.py. This file contains the generate_html() and export_graph_data() functions that prepare the graph data and construct the interactive HTML page using the bundled D3 library.

How does the automatic rendering mode work?

The mode="auto" setting (default) checks the node and edge counts against DEFAULT_MAX_FULL_NODES and DEFAULT_MAX_FULL_EDGES constants defined in visualization.py. If the graph exceeds these limits, it automatically switches to community or file aggregation to prevent browser performance degradation; otherwise, it renders the full force-directed layout.

Can I view the visualization without an internet connection?

Yes. The _write_d3_asset() function (lines 56-84) copies the vendored d3.v7.min.js file from code_review_graph/assets/ into the output directory. The generated HTML references this local copy via the __D3_SCRIPTS__ placeholder, making the visualization fully functional offline.

How do I force a specific visualization layout?

Pass the --mode flag to the CLI or the mode parameter to generate_html(). Valid options are "full" for complete detail, "community" for community-based aggregation, or "file" for file-level grouping. This overrides the automatic threshold-based selection.

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