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

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 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:

   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 (lines 8–24) wraps the analysis for integration with MCP-compatible environments:

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:

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:

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 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.

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