How the Architecture Overview Auto‑Generates from Community Structure in Code‑Review Graph

The get_architecture_overview function in code_review_graph/communities.py automatically derives a high‑level architectural summary by analyzing community clusters and their cross‑boundary dependencies, flagging any pair of communities with more than ten connecting edges as a potential architectural smell.

The code‑review‑graph project provides automated code analysis by detecting communities—clusters of related code nodes—within a repository. The architecture overview feature transforms these detected communities into actionable insights by mapping inter‑community dependencies without requiring additional analysis passes. This article explains exactly how the system auto‑generates architectural summaries from existing community structure data stored in the SQLite‑backed GraphStore.

The Four‑Stage Generation Pipeline

The auto‑generation process follows a deterministic pipeline implemented in the get_architecture_overview helper. Each stage consumes data already persisted in the graph store, ensuring the overview reflects the latest community detection results.

Stage 1: Load Detected Communities

The process begins by invoking get_communities to retrieve all stored community objects and their member nodes. This ensures the architecture overview is synchronized with the most recent clustering analysis.

According to the source in code_review_graph/communities.py (lines 998–1013), the community detector returns every stored community along with its constituent nodes, providing the foundation for subsequent boundary analysis.

Stage 2: Build the Node‑to‑Community Lookup Map

To enable O(1) community membership checks when scanning edges, the function constructs a dictionary mapping each node's qualified_name to its community id.

As implemented in code_review_graph/communities.py (lines 2034–2039), this node_to_community map eliminates the need for expensive repeated searches through community member lists during the edge traversal phase.

Stage 3: Scan Edges for Cross‑Community Boundaries

With the lookup map ready, the system retrieves all edges via store.get_all_edges() and iterates through them once. For each edge, it identifies the source and target communities using the pre‑built map.

The logic specifically:

• Collects edges where src_comm != tgt_comm (cross‑boundary connections)
• Excludes edges of kind TESTED_BY, as test‑to‑code coupling represents expected relationships rather than architectural violations
• Tallies counts using a Counter for each unordered pair of community IDs

This edge scanning loop appears in code_review_graph/communities.py (lines 2046–2064).

Stage 4: Emit Warnings for Architectural Smells

The final stage identifies high‑coupling patterns. Any community pair sharing more than ten cross‑community edges triggers a warning, unless _is_test_community determines that either community is test‑dominated (since test‑code coupling is considered normal).

The warning generation logic in code_review_graph/communities.py (lines 2070–2082) produces human‑readable strings like "High coupling (12 edges) between 'auth' and 'db'" while skipping false positives from test‑heavy communities.

Working with the Generated Architecture Overview

The function returns a structured dictionary containing the full community data, cross‑community edge tallies, and accumulated warnings. Because the operation only reads from the existing GraphStore, it executes efficiently without re‑running community detection.

Basic Usage

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

# Assume `store` has already been populated (e.g., via `crg analyze …`)

overview = get_architecture_overview(store)

print("Communities detected:", len(overview["communities"]))
print("Cross‑community edges:", len(overview["cross_community_edges"]))
print("Warnings:")
for w in overview["warnings"]:
    print(" •", w)

This pattern, defined in code_review_graph/communities.py at lines 2020–2089, provides immediate visibility into architectural boundaries.

Inspecting Specific Communities

# Find the “auth” community (name may vary)

auth_comm = next(c for c in overview["communities"] if c["name"] == "auth")
print("Auth community size:", auth_comm["size"])
print("Members:")
for qn in auth_comm["members"]:
    print(" –", qn)

Filtering High‑Coupling Pairs

high_coupling = [
    (pair, cnt) for pair, cnt in overview["cross_community_edges"]
    if cnt > 10
]
for (src, tgt), count in high_coupling:
    print(f"{src} ↔ {tgt}: {count} edges")

Summary

• get_architecture_overview in code_review_graph/communities.py automatically generates architectural summaries by analyzing pre‑computed community structures.
• The four‑stage pipeline involves loading communities, building O(1) lookup maps, scanning all edges once while excluding TESTED_BY relationships, and tallying cross‑community connections.
• Coupling warnings trigger at the 10‑edge threshold, filtered to ignore test‑dominated communities via _is_test_community.
• The resulting dictionary exposes communities, cross‑community edge counts, and architectural smell warnings without requiring additional analysis passes.

Frequently Asked Questions

What data source does the architecture overview use to avoid re‑running analysis?

The function reads directly from the SQLite‑backed GraphStore instance populated by prior crg analyze commands. It calls store.get_all_edges() and get_communities to access existing community detection results, making the overview generation a read‑only operation that completes in milliseconds regardless of repository size.

Why are TESTED_BY edges excluded from cross‑community coupling counts?

Edges of kind TESTED_BY represent intentional coupling between test code and implementation code. Since this relationship is expected architectural behavior rather than a design flaw, the edge scanning logic in code_review_graph/communities.py explicitly filters them out before tallying cross‑community connections.

How does the system determine if a community is "test‑dominated"?

Before emitting a high‑coupling warning, the pipeline consults the internal _is_test_community helper. This function analyzes the community's member nodes to determine if the majority are test files; if so, the warning is suppressed because heavy coupling between test and production code is normal.

Can I adjust the threshold for what constitutes "high coupling"?

The current implementation hardcodes the threshold at ten edges within the warning generation logic (lines 2070–2082 of code_review_graph/communities.py). To modify this sensitivity, you would need to edit the source or fork the repository to parameterize the threshold in future versions.

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