Community Detection & Architecture Maps
Relevant source files
The following files were used as context for generating this wiki page:
Community detection in code-review-graph is the process of clustering related code entities—such as functions, classes, and files—into logical modules or "communities." This structural analysis allows the system to generate high-level architecture maps, identifying modular boundaries and coupling between different parts of a codebase.
By analyzing the graph of code relationships, the system can detect "architectural hotspots" (hubs) and "chokepoints" (bridges), providing developers with a structural mental model of the project that goes beyond simple directory hierarchies. Sources: code_review_graph/wiki.py, code_review_graph/communities.py, code_review_graph/tools/analysis_tools.py
Community Detection Mechanisms
The system employs two primary strategies for identifying communities within the code knowledge graph: the Leiden algorithm (for graph-based clustering) and a file-based grouping fallback.
Detection Logic Flow
The detection process prioritizes high-fidelity graph clustering but ensures structural information is available even in sparse graphs.
The system checks for the availability of the igraph library to perform Leiden clustering; otherwise, it groups nodes by their file/directory paths. Sources: code_review_graph/communities.py:48-110, tests/test_communities.py:168-182
Detection Algorithms
| Algorithm | Description | Context |
|---|---|---|
| Leiden Algorithm | A community detection algorithm that maximizes modularity. It is used when the igraph library is installed. | code_review_graph/communities.py:166-170 |
| File-based Grouping | Groups nodes based on their directory structure and file paths. Used as a fallback or for initial clustering. | code_review_graph/communities.py:112-115 |
| Recursive Splitting | If a community exceeds 25% of the total graph size, it is recursively split using Leiden to ensure granular results. | code_review_graph/communities.py:84-90 |
Architecture Mapping and Metrics
Once communities are detected, the system calculates several metrics to describe the architecture's health and cohesion.
Key Metrics
- Cohesion: Calculated as the ratio of internal edges to the total number of edges (internal + external) connected to the community members. A value of 1.0 indicates a perfectly isolated, self-contained module. Sources: code_review_graph/communities.py:192-205, tests/test_communities.py:236-258
- Dominant Language: The most frequent programming language found among the nodes in a community. Sources: code_review_graph/communities.py:317-320
- Size: The total count of nodes belonging to the community. Sources: code_review_graph/wiki.py:42
Architectural Analysis Tools
The system provides specialized tools to identify critical structural components:
- Hub Nodes: Nodes with the highest total degree (inbound + outbound edges). These represent architectural hotspots where changes have a disproportionate "blast radius." Sources: code_review_graph/tools/analysis_tools.py:27-35
- Bridge Nodes: Chokepoints identified via betweenness centrality. These nodes sit on the shortest paths between many other node pairs. Sources: code_review_graph/tools/analysis_tools.py:53-61
- Surprising Connections: Detection of unexpected coupling, such as cross-community, cross-language, or peripheral-to-hub edges. Sources: code_review_graph/tools/analysis_tools.py:116-125
Wiki Generation
The system can transform the detected community structure into a navigable Markdown wiki. This wiki includes an index of all communities and individual pages for each community.
Wiki Page Structure
Individual community pages are generated with the following sections:
- Overview: Displays size, cohesion, dominant language, and a description.
- Members: A table listing the top 50 nodes (functions, classes) in the community.
- Execution Flows: Call chains that pass through any member of the community.
- Dependencies: Summarizes incoming and outgoing cross-community edges.
Sources: code_review_graph/wiki.py:32-156, tests/test_wiki.py:130-136
Data Flow for Wiki Generation
Architecture Overview and Coupling
The get_architecture_overview tool provides a high-level view of community boundaries and cross-community coupling. It identifies warnings for "high coupling" when a significant number of edges exist between two distinct communities.
Coupling Thresholds
The system flags warnings if the number of cross-community edges (excluding TESTED_BY edges) exceeds a threshold (typically 10 edges) between any community pair. Sources: code_review_graph/communities.py:378-390, tests/test_communities.py:121-136
Tool Configuration: Detail Levels
| Detail Level | Behavior |
|---|---|
| minimal | Aggregates edges into one row per community pair with a count. Drops member lists to save tokens (typical 600KB -> <5KB reduction). |
| standard | Returns full per-edge details for all cross-community connections. |
Sources: code_review_graph/tools/community_tools.py:151-182, code_review_graph/main.py:465-475
Summary
Community Detection & Architecture Maps provide the structural foundation for token-efficient code reviews. By clustering code into modules, code-review-graph can perform impact analysis at the community level, generate automated documentation via the Wiki, and warn developers about architectural erosion or high coupling between supposedly isolated modules. Sources: code_review_graph/wiki.py, code_review_graph/communities.py, code_review_graph/main.py