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

> Explore how code-review-graph's architecture overview generates summaries. It detects communities, counts cross-community edges, and flags structural issues for better code understanding.

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

---

**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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/communities.py), which queries the SQLite **GraphStore** for previously detected community records.

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

```python

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/community_tools.py).

### Standard Detail (`detail_level="standard"`)

Returns the complete structure:

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

```python
compact = get_architecture_overview_func(detail_level="minimal")

# Contains only summary, compressed community list, and warnings

```

---

## CLI Usage and Programmatic Access

### Command-Line Interface

```bash

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/cli.py).

### Direct API Access

For integration into custom analysis pipelines:

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