How Code-Review-Graph's Architecture Overview Generates Summaries from Community Structure

Code-review-graph produces architecture summaries by detecting communities in the code-dependency graph, counting cross-community edges, and flagging high-coupling pairs that may indicate structural issues.

The code-review-graph open-source tool transforms raw code-dependency data into actionable architectural insights. By applying community detection to grouped code entities, it reveals the hidden modular structure of a codebase. This article explains how the architecture overview system generates summaries from these community structures, based on the actual implementation in the repository.

---

Core Architecture: From Communities to Summaries

The architecture overview pipeline follows a clear three-stage process: collect communities, measure inter-community coupling, and surface warnings. Each stage maps directly to functions in the source code.

Stage 1: Retrieve Community Data

The process begins with get_communities() in code_review_graph/communities.py, which queries the SQLite GraphStore for previously detected community records.

from code_review_graph.communities import get_communities
from code_review_graph.graph import GraphStore

store = GraphStore("/path/to/.crg.db")
communities = get_communities(store)  # Returns list of community objects

Each community object contains:

• Community ID (numeric identifier)
• Name (human-readable label)
• Size (member count)
• Members (list of qualified names, e.g., ["myproject.utils.helper", "myproject.utils.parser"])

Stage 2: Build Node-to-Community Mappings

get_architecture_overview() constructs a node_to_community dictionary that maps every qualified name to its parent community ID. This enables O(1) lookups when classifying edges in the next stage.

The function iterates through all communities and populates the mapping at code_review_graph/communities.py lines 20–31.

Stage 3: Count Cross-Community Edges

Edge analysis follows strict filtering rules:

1. Load all edges via store.get_all_edges()
2. Ignore TESTED_BY edges — these represent expected test-to-code coupling and are excluded from coupling measurement
3. Detect cross-community edges — for each edge, compare source and target community IDs
4. Aggregate by community pair — canonicalize (src_community, tgt_community) pairs and increment counters

# Pseudo-code representing the core loop in communities.py

for edge in store.get_all_edges():
    if edge.kind == "TESTED_BY":
        continue  # Expected coupling, skip

    
    src_comm = node_to_community.get(edge.source)
    tgt_comm = node_to_community.get(edge.target)
    
    if src_comm != tgt_comm:
        pair = canonical_pair(src_comm, tgt_comm)
        cross_community_counts[pair] += 1

Stage 4: Generate Coupling Warnings

After aggregation, the system applies heuristic thresholds to identify problematic coupling:

Condition	Action
Edge count ≤ 10	Normal, no action
Edge count > 10 + neither community is test-dominated	Generate warning

Test-dominated communities are detected via _is_test_community(), which examines member naming patterns.

Example warning format:

"High coupling (12 edges) between 'utils' and 'api'"

---

Detail Levels: Standard vs. Minimal Output

The architecture overview supports two detail levels controlled through the CLI-friendly wrapper get_architecture_overview_func() in code_review_graph/tools/community_tools.py.

Standard Detail (detail_level="standard")

Returns the complete structure:

from code_review_graph.tools.community_tools import get_architecture_overview_func

full = get_architecture_overview_func(detail_level="standard")
print(full["summary"])      # Human-readable summary

print(full["communities"])  # Full community objects with member lists

print(full["cross_community_edges"])  # Individual edge records

print(full["warnings"])     # High-coupling alerts

Minimal Detail (detail_level="minimal")

The _minimal_overview() function (lines 152–162 in community_tools.py) compresses output for token-constrained environments:

• Removes: Per-node member lists
• Aggregates: Edges to one row per community pair
• Preserves: Edge count and top-three edge kinds only

compact = get_architecture_overview_func(detail_level="minimal")

# Contains only summary, compressed community list, and warnings

---

CLI Usage and Programmatic Access

Command-Line Interface

# Default minimal view (recommended for quick inspection)

crg architecture

# Full detail with complete edge enumeration

crg architecture --detail-level standard

The architecture sub-command is registered in code_review_graph/cli.py.

Direct API Access

For integration into custom analysis pipelines:

from code_review_graph.communities import get_architecture_overview
from code_review_graph.graph import GraphStore

store = GraphStore("/path/to/.crg.db")
overview = get_architecture_overview(store)

print(f"{len(overview['communities'])} communities discovered")
print(f"{len(overview['cross_community_edges'])} cross-community edges")
print("Warnings:", overview["warnings"])

store.close()

---

How the Summary Structure Enables Actionable Insights

The architecture overview format supports multiple downstream consumers:

Consumer	Usage
Human reviewers	Read summary and warnings for quick structural assessment
LLM-based tools	Ingest minimal JSON to stay within context windows
hints.py system	Convert warnings into interactive coupling suggestions during code review

The separation of static community layout (what modules exist) from dynamic coupling analysis (how modules interact) allows the tool to surface architectural drift that static analysis might miss.

---

Summary

• get_architecture_overview() in code_review_graph/communities.py is the core engine that transforms community structure into architectural summaries
• The algorithm filters TESTED_BY edges, aggregates cross-community connections, and applies thresholds to detect excessive coupling
• Output granularity is controlled by get_architecture_overview_func() in community_tools.py, with _minimal_overview() reducing token consumption by ~60–80%
• Warnings trigger only when cross-community edge counts exceed 10 and neither community is test-dominated
• The architecture CLI command and direct Python API expose identical functionality for shell and programmatic workflows

---

Frequently Asked Questions

What file contains the main architecture overview logic?

The core implementation resides in code_review_graph/communities.py. The get_architecture_overview() function performs community retrieval, node mapping, edge counting, and warning generation. Lines 20–31 handle the critical node-to-community mapping and edge classification loop.

Why are TESTED_BY edges excluded from coupling analysis?

TESTED_BY edges represent expected structural relationships between test code and implementation. Including them would inflate coupling metrics for legitimate test coverage patterns. The detection logic explicitly skips these edges at code_review_graph/communities.py before counting cross-community connections.

How does the minimal detail level differ from standard output?

Minimal detail removes member lists from community objects and aggregates all edges between two communities into a single record with counts and top-three edge kinds. This transformation in _minimal_overview() (lines 152–162 of community_tools.py) preserves essential coupling information while reducing response size for LLM consumers.

Can I use the architecture overview without the CLI?

Yes. Import get_architecture_overview() directly from code_review_graph.communities and pass a GraphStore instance. For wrapper functionality including detail-level selection, use get_architecture_overview_func() from code_review_graph.tools.community_tools.

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