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

> Discover how the architecture overview auto-generates from community structure in the code review graph. Analyze community clusters and cross-boundary dependencies to identify potential architectural smells.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: architecture
- Published: 2026-07-30

---

**The `get_architecture_overview` function in [`code_review_graph/communities.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/communities.py) at lines 2020–2089, provides immediate visibility into architectural boundaries.

### Inspecting Specific Communities

```python

# 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

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.