# Hub Node Detection: How Code-Review-Graph Finds Architectural Hotspots

> Discover hub node detection a graph-analysis technique that uncovers code architectural hotspots by identifying most connected symbols and their blast radius.

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

---

**Hub node detection is a graph-analysis technique that identifies the most-connected symbols in a codebase by ranking nodes according to their total degree (inbound plus outbound edges), revealing architectural hotspots where changes have the largest blast radius.**

In the `tirth8205/code-review-graph` repository, hub node detection serves as a core capability for surfacing structural risk areas. By treating functions, classes, and modules as nodes in a dependency graph, the algorithm quantifies connectivity to pinpoint exactly which symbols anchor the architecture—and which ones threaten systemic stability when modified.

## What Is a Hub Node?

A **hub node** is any non-file symbol whose **total degree** (sum of incoming and outgoing relationships) exceeds that of peers in the same codebase. Relationships include `CALLS`, `IMPORTS`, `TESTED_BY`, and other edge types persisted in the graph store.

The distinction matters: high **in-degree** means many callers depend on the symbol; high **out-degree** means the symbol itself depends heavily on others. Either condition—or their combination—signals a coordination point where ripple effects concentrate.

## How Hub Node Detection Works

The detection algorithm is implemented in [`code_review_graph/analysis.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/analysis.py) via the `find_hub_nodes` function (lines 14–55). The pipeline executes six precise steps:

1. **Collect all edges** from `GraphStore` using `store.get_all_edges()`.
2. **Count degrees** with two `Counter` objects: `in_degree` and `out_degree` accumulate inbound and outbound edge frequencies per qualified name (lines 22–27).
3. **Filter to code symbols** by retrieving `store.get_all_nodes(exclude_files=True)` and their community identifiers via `store.get_all_community_ids()` (lines 29–30).
4. **Compute total degree** for each node:
   ```python
   ind = in_degree.get(qn, 0)
   outd = out_degree.get(qn, 0)
   total = ind + outd
   ```

   Nodes with `total == 0` are discarded (lines 35–38).
5. **Build result records** containing name, qualified name, kind, file path, individual degrees, total degree, and community ID (lines 40–48).
6. **Rank and truncate** by descending `total_degree`, returning the top `top_n` entries (default 10) (lines 51–55).

File nodes are explicitly excluded because they function as containers rather than logical code units; the analysis targets actual symbols that carry behavior.

## Why Total Degree Reveals Architectural Hotspots

Nodes with elevated total degree are **structural linchpins**. Consider the dual risk profile:

- **High in-degree**: Widely consumed utilities, base classes, or shared services. Changes break numerous dependents.
- **High out-degree**: Complex coordinators with intricate downstream dependencies. Changes require understanding many collaborators.

When a single node scores highly on both metrics, it becomes a **change amplification zone**—a small modification can cascade through both upstream consumers and downstream implementations. This is precisely what architects mean by a "hotspot": not merely complex code, but code whose complexity is structurally entangled with system-wide stability.

## Detecting Hub Nodes in Practice

### Using the MCP Tool Interface

The public entry point `get_hub_nodes_tool` in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) (lines 8–24) wraps the analysis for integration with MCP-compatible environments:

```python
from code_review_graph.main import get_hub_nodes_tool

# Return the 5 most-connected hubs in the current repository

result = get_hub_nodes_tool(top_n=5)

print(result["hub_nodes"])

# → [{'name': 'UserService', 'qualified_name': '/src/user.py::UserService', ...}, ...]

```

The tool auto-resolves the repository root and returns JSON-compatible output suitable for automated reporting or IDE integration.

### Direct Analysis API

For custom workflows, invoke `find_hub_nodes` directly:

```python
from code_review_graph.graph import GraphStore
from code_review_graph.analysis import find_hub_nodes

store = GraphStore.from_path("/path/to/repo/.code-review-graph/store")
hubs = find_hub_nodes(store, top_n=3)

for hub in hubs:
    print(f"{hub['name']} ({hub['total_degree']} connections) – {hub['file']}")

```

This yields raw dictionaries for further processing, visualization, or CI/CD gating.

### Combining with Impact Analysis

Hub detection gains power when paired with transitive dependency queries:

```python
from code_review_graph.analysis import find_hub_nodes
from code_review_graph.graph import GraphStore

store = GraphStore.from_path("...")
hubs = find_hub_nodes(store, top_n=1)
hub_qn = hubs[0]["qualified_name"]

# Reveal exact blast radius

dependents = store.get_transitive_dependencies(hub_qn)
print(f"{hub_qn} impacts {len(dependents)} other nodes")

```

The `GraphStore.get_transitive_dependencies` method traverses the dependency graph to enumerate all symbols reachable from the hub—converting abstract connectivity metrics into concrete change-impact assessments.

## Summary

- **Hub node detection** ranks code symbols by total degree (inbound plus outbound edges) to surface architectural hotspots.
- The algorithm lives in [`analysis.py`](https://github.com/tirth8205/code-review-graph/blob/main/analysis.py) with `find_hub_nodes` as the core implementation.
- **File nodes are excluded**; analysis targets logical symbols only.
- High total degree indicates either broad consumption, heavy coordination, or both—signaling elevated change risk.
- Results integrate via `get_hub_nodes_tool` (MCP interface) or direct API calls for custom tooling.

## Frequently Asked Questions

### What qualifies as a hub node in code-review-graph?

A hub node is any non-file symbol (function, class, module, etc.) whose total degree—sum of incoming and outgoing edges in the dependency graph—ranks among the highest in the repository. The `exclude_files=True` filter in `store.get_all_nodes()` ensures containers don't dilute the results.

### How does total degree differ from simple dependency count?

Total degree combines `in_degree` (how many symbols call or reference the node) with `out_degree` (how many symbols the node itself depends upon). This captures both **fan-in risk** (breaking dependents) and **fan-out complexity** (coordination burden), whereas simple counts might miss one dimension.

### Can hub nodes change across codebase versions?

Yes. As code evolves, refactoring can redistribute connectivity. Regular hub detection runs—especially before large refactorings—establish baseline risk profiles and verify that architectural changes actually reduce hotspot concentration rather than shifting it.

### Why exclude file nodes from hub detection?

Files are structural containers with artificially inflated connectivity; nearly every symbol in a file would contribute to that file's degree. The algorithm targets logical code units whose connectivity reflects genuine architectural coupling patterns, not directory organization artifacts.