D3.js Interactive Visualization
Relevant source files
The following files were used as context for generating this wiki page:
The D3.js Interactive Visualization system provides a structural mapping of codebases, allowing users and AI agents to explore relationships between code entities. It translates a SQLite-backed knowledge graph into a force-directed visual representation, supporting zoomable, draggable, and searchable nodes that represent files, classes, functions, and tests.
This system is utilized in two primary contexts: as a standalone self-contained HTML file generated by the CLI and as an integrated Webview within the VS Code extension. It supports advanced features such as community drill-down, impact radius highlighting, and execution flow visualization to minimize token usage during code reviews by identifying only the most relevant code sections.
Sources: code_review_graph/visualization.py:12-23, README.zh-CN.md:120-140
System Architecture and Data Flow
The visualization architecture follows a pipeline from raw code parsing to interactive browser rendering. The Python backend extracts data from the GraphStore, processes it into a JSON-serializable format, and either embeds it into an HTML template or serves it via a Webview provider.
The diagram illustrates the flow from SQLite storage through Python aggregation functions to the D3.js frontend rendering.
Sources: code_review_graph/visualization.py:27-200, code-review-graph-vscode/src/webview/graph.ts:160-230
Core Data Structures
The visualization represents code entities as Nodes and their relationships as Edges. The frontend uses specialized types to extend these with D3-specific simulation properties.
Node and Edge Definitions
| Entity | Properties | Source |
|---|---|---|
| GraphNode | id, kind, name, qualifiedName, filePath, lineStart, lineEnd, params, returnType, community_id | graph.ts:40-56 |
| GraphEdge | id, kind, sourceQualified, targetQualified, filePath, line, weight | graph.ts:58-65 |
| Node Kinds | File, Class, Function, Test, Type, Community | graph.ts:36-36, visualization.py:124 |
| Edge Kinds | CALLS, IMPORTS_FROM, INHERITS, IMPLEMENTS, TESTED_BY, CONTAINS, DEPENDS_ON, CROSS_COMMUNITY | graph.ts:38-46, visualization.py:136 |
Rendering Mode Logic
The visualization supports multiple modes to handle large graphs effectively:
- Full Mode: Every individual node is rendered.
- Community Mode: Aggregates nodes into "super-nodes" based on detected communities. Supports double-clicking a community to "drill down" into its internal structure.
- File Mode: Aggregates all symbols into their respective file nodes, sized by symbol count.
- Auto Mode: Switches from "full" to "community" if the node count exceeds a threshold (default: 3000 nodes).
Sources: code_review_graph/visualization.py:17-23, code_review_graph/visualization.py:182-187
Interactive Visual Components
The D3.js implementation includes a variety of visual cues and interactive controls to facilitate codebase exploration.
Styling and Symbology
Nodes are styled based on their kind, using distinct colors and D3 symbols:
- File: Blue circle (#58a6ff), Radius 18.
- Class: Orange square (#f0883e), Radius 12.
- Function: Green triangle (#3fb950), Radius 6.
- Test: Purple diamond (#d2a8ff), Radius 6.
Sources: code-review-graph-vscode/src/webview/graph.ts:71-96
Force Simulation Configuration
The simulation utilizes multiple D3 forces to create an organized layout:
- Link Force: Sets distances based on edge type (e.g.,
CONTAINSedges are shorter). - Charge Force: Prevents overlap using
forceManyBodywith negative strength. - Collide Force: Prevents node overlap based on the node's radius.
- Center/X/Y Forces: Keeps the graph centered in the viewport.
Sources: code_review_graph/visualization.py:510-525, code-review-graph-vscode/src/webview/graph.ts:362-385
Interaction Flow (Webview)
This diagram shows the communication between the UI, the Webview logic, and the VS Code extension host.
Sources: code-review-graph-vscode/src/webview/graph.ts:285-300, code-review-graph-vscode/src/views/graphWebview.ts:114-130
Visual Export and Integration
The visualization is not limited to active exploration; it supports several export and integration methods.
CLI Generation
The CLI provides the visualize command to generate standalone artifacts:
- HTML: Self-contained file with embedded JSON and D3 logic.
- GraphML: For use in Gephi or yEd.
- SVG/Obsidian: Static vector graphics or Markdown-linked vaults.
Sources: README.zh-CN.md:200-210, code_review_graph/visualization.py:177-200
Extension Integration
In VS Code, the visualization acts as a live dashboard.
- Bi-directional Sync: Clicking a node in the graph navigates to the source code, while clicking
revealInTreein the extension highlights the corresponding node in the graph. - Impact Radius: When reviewing changes, the graph can be filtered to show only "seeds" (changed files) and their "blast radius" (impacted dependents).
Sources: code-review-graph-vscode/src/extension.ts:470-485, code-review-graph-vscode/src/views/graphWebview.ts:147-155
Summary
The D3.js Interactive Visualization module is a critical interface for the code-review-graph project. By combining structural code analysis with force-directed graph rendering, it provides a high-fidelity map of dependencies. Whether used through the CLI to generate documentation or as a VS Code Webview to assist in real-time code review, it successfully reduces the cognitive load and token cost associated with understanding complex, large-scale software architectures.
Sources: README.zh-CN.md:15-30, code_review_graph/main.py:650-660