get_hotspots

get_hotspots

Identify architectural hotspots — modules with high coupling, high centrality, high churn, or trapped in circular dependencies. These are the modules most in need of refactoring attention.

Tip

Use this after detecting policy violations to prioritize which modules to fix first.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
metric_type	string	No	Filter hotspots by metric type (e.g., centrality, scc)

Response

Returns a JSON summary with hotspot findings grouped by metric.

Response Schema

{
  "hotspots": [
    {
      "metric": "string",          // Metric ID (e.g., "centrality", "scc")
      "title": "string",            // Finding title (e.g., "Hub module detected")
      "severity": "error|warning|info",
      "evidence_count": "number"    // Number of modules/evidence items
    }
  ],
  "findings_count": "number",      // Total number of findings
  "violations_count": "number"     // Policy violations count
}

Severity Levels

Severity	Interpretation
error	Critical issue — blocks architecture quality goals
warning	Significant issue — should be addressed soon
info	Minor issue or informational finding

Examples

Multiple hotspots detected

Request:

{
  "project_path": "."
}

Response:

{
  "hotspots": [
    {
      "metric": "centrality",
      "title": "Hub module detected",
      "severity": "warning",
      "evidence_count": 3
    },
    {
      "metric": "scc",
      "title": "Circular dependency",
      "severity": "error",
      "evidence_count": 2
    },
    {
      "metric": "centrality",
      "title": "High betweenness centrality",
      "severity": "warning",
      "evidence_count": 1
    }
  ],
  "findings_count": 6,
  "violations_count": 1
}

Interpretation:

• 3 hub modules (high fan-in)
• 2 circular dependencies (cycles)
• 1 module with high betweenness (critical junction point)
• 6 total findings (sum of evidence counts)
• 1 policy violation triggered

Filter by metric type

Request:

{
  "project_path": ".",
  "metric_type": "centrality"
}

Response:

{
  "hotspots": [
    {
      "metric": "centrality",
      "title": "Hub module detected",
      "severity": "warning",
      "evidence_count": 3
    },
    {
      "metric": "centrality",
      "title": "High betweenness centrality",
      "severity": "warning",
      "evidence_count": 1
    }
  ],
  "findings_count": 4,
  "violations_count": 0
}

No hotspots (clean architecture)

Request:

{
  "project_path": "/path/to/clean-project"
}

Response:

{
  "hotspots": [],
  "findings_count": 0,
  "violations_count": 0
}

Common Hotspot Types

Hub modules

Finding: "Hub module detected"

What it means: A module with high fan-in (many modules depend on it)

Why it matters: Changes ripple widely; testing burden is high; often a bottleneck

How to fix:

• Split into smaller, focused modules
• Extract interfaces/facades
• Apply Dependency Inversion Principle

God classes

Finding: "God class detected"

What it means: A module with high fan-out (depends on many modules)

Why it matters: Violates Single Responsibility Principle; difficult to test and maintain

How to fix:

• Extract responsibilities into separate modules
• Apply Extract Class refactoring
• Use dependency injection

Circular dependencies

Finding: "Circular dependency"

What it means: Modules form import cycles

Why it matters: Prevents modular compilation; amplifies change propagation; hides dependencies

How to fix:

• Break the cycle by extracting shared interfaces
• Introduce a mediator/event bus
• Invert dependencies using abstractions

See Breaking Cycles for detailed guidance.

High betweenness centrality

Finding: "High betweenness centrality"

What it means: Module sits on many shortest dependency paths

Why it matters: Critical junction point — failure affects many modules; single point of failure

How to fix:

• Introduce redundant paths (alternative implementations)
• Split module into smaller, independent units
• Apply facade pattern to reduce coupling

Workflow

Use this tool to prioritize refactoring efforts:

1. get_hotspots → identify problem areas
2. Sort by severity (errors first, then warnings)
3. For each hotspot:
   a. Run analyze_file_impact on affected files
   b. Run suggest_refactors for recommendations
   c. Implement fixes
   d. Re-run get_hotspots to verify improvement

See Workflows: Hotspot detection and refactoring for a full example.

Error Cases

Error	Cause	Solution
missing required parameter: project_path	project_path not provided	Include project_path in request
No such file or directory	Invalid project path	Verify path exists and is accessible
Unknown metric_type: xyz	Invalid filter value	Omit metric_type or use valid metric ID

Performance

• Speed: 1-5 seconds (uses quick preset internally)
• Caching: Does not use cache (always fresh analysis)
• Scalability: Efficiently handles 10k+ module projects

Filtering Hotspots

Use metric_type to focus on specific concerns:

metric_type	What it finds
centrality	Hub modules, god classes, high betweenness
scc	Circular dependencies
smells	Architectural smells (hubs, god classes, etc.)
propagation_cost	High propagation risk modules

Note

Omitting metric_type returns hotspots from all metrics (recommended for initial assessment).

Interpreting Results

High evidence_count

More evidence items means more modules affected. Prioritize hotspots with high evidence counts for maximum impact.

Multiple findings for same metric

Example: 3 hub modules + 1 high betweenness = systemic coupling issue

Action: Consider a broader architectural refactoring (e.g., layer extraction, microservices split) rather than fixing modules individually.

No hotspots but violations exist

If hotspots is empty but violations_count > 0, the violations are from metrics not included in the quick preset.

Action: Run analyze_architecture with ci or full preset to see all findings.

Related Tools

• check_cycles — Fast cycle detection
• analyze_file_impact — Assess blast radius of hotspot modules
• suggest_refactors — Get prioritized refactoring recommendations
• evaluate_policy — Check policy violations

Related Guides

• Breaking Cycles — Step-by-step cycle refactoring
• Refactoring Patterns — Common refactoring strategies
• Centrality Metrics — Understanding hub modules and betweenness

CLI Equivalent

# Get hotspots using CLI
arxo analyze --preset quick --format json | jq '[.results[].findings[] | {metric: .id, title: .title, severity: .severity}]'