High-level System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The code-review-graph system is a persistent, local-first knowledge graph designed to facilitate token-efficient code reviews. It achieves this by parsing codebases into a structural graph stored in a local SQLite database, allowing AI coding tools to query targeted context rather than reading entire files. The system supports multi-language parsing via Tree-sitter and integrates with various AI platforms through the Model Context Protocol (MCP).
Sources: CLAUDE.md:4-10, README.zh-CN.md:16-20
Core Component Overview
The system is organized into several distinct layers, ranging from low-level parsing to high-level tool integration.
System Architecture Diagram
The following diagram illustrates the data flow from the raw codebase to the final AI consumption layer.
Sources: CLAUDE.md:14-43, README.zh-CN.md:38-42
Key Subsystems
1. Data Storage and Processing
The foundation of the system is a SQLite-backed graph store, typically located in .code-review-graph/graph.db. This database utilizes WAL (Write-Ahead Logging) mode for performance and stores nodes (functions, classes, files) and edges (calls, imports, inheritance).
- Parser (
parser.py): Uses Tree-sitter for multi-language AST parsing with targeted fallbacks for broad source support. - Incremental Update (
incremental.py): Implements git-based change detection to update the graph only for modified files, ensuring sub-2-second updates. - Post-processing (
main.py): Independent execution of expensive steps like flow detection, community detection (Leiden algorithm), and FTS5 indexing.
Sources: CLAUDE.md:15-25, code_review_graph/main.py:109-130, README.zh-CN.md:65-72
2. Analysis and Intelligence
The system performs high-level structural analysis to identify risks and relationships.
| Component | Description | File Reference |
|---|---|---|
| Impact Analysis | Calculates the "blast radius" of changes using BFS traversals. | code_review_graph/changes.py |
| Flow Detection | Traces execution paths from entry points (e.g., HTTP handlers). | code_review_graph/flows.py |
| Community Detection | Clusters related code using the Leiden algorithm for architecture mapping. | code_review_graph/communities.py |
| Refactoring Engine | unified entry point for renames, dead code detection, and move suggestions. | code_review_graph/refactor.py |
Sources: CLAUDE.md:27-38, code_review_graph/main.py:440-475
3. Interface Layer (MCP & CLI)
The primary interaction method for AI tools is the FastMCP server, which exposes approximately 30 tools and 5 prompt templates.
Visualization Subsystem
The system provides interactive D3.js visualizations. It supports multiple aggregation modes (full, community, file) to handle large graphs effectively.
- Mode Selection: Automatically switches to community mode when node counts exceed a threshold (e.g., 3000 nodes).
- Data Export: The
export_graph_datafunction serializes nodes, edges, flows, and communities into JSON for the D3 template.
Sources: code_review_graph/visualization.py:20-35, code_review_graph/visualization.py:139-158
Platform Integrations
The skills.py module manages the automated configuration of various AI environments.
| Platform | Configuration File | Integration Method |
|---|---|---|
| Claude Code | .mcp.json | JSON Object with type "stdio" |
| VS Code | .vscode/mcp.json | JSON Object |
| Zed | settings.json | context_servers key |
| Cursor | .cursor/mcp.json | JSON Object |
| Codex | config.toml | TOML section [mcp_servers] |
Sources: code_review_graph/skills.py:48-120, code_review_graph/skills.py:228-260
VS Code Extension Architecture
The VS Code extension (extension.ts) acts as a bridge between the local Python CLI/Server and the IDE UI.
- Backend Communication: Uses
CliWrapperto run build/update commands andSqliteReaderfor direct database access. - UI Components: Implements TreeView providers for the Code Graph, Blast Radius analysis, and Graph Stats.
- Webview: Hosts the D3.js visualization generated by the core Python package.
Sources: code-review-graph-vscode/src/extension.ts:18-35, code-review-graph-vscode/src/extension.ts:518-550
Conclusion
The high-level architecture of code-review-graph emphasizes a local-first approach where structural intelligence is cached in a SQLite database. By decoupling parsing from analysis and utilizing the Model Context Protocol, the system provides a high-performance, token-efficient interface that enables AI tools to perform deep architectural reviews and impact analysis with minimal overhead.
Sources: CLAUDE.md:4-10, README.zh-CN.md:208-230