analyze_architecture

analyze_architecture

Run a comprehensive architecture analysis on your project. This is the primary tool for obtaining metrics such as SCC (cycles), coupling, propagation cost, centrality, and more.

Note

This tool supports caching. Results are cached for 5 minutes (configurable via --cache-ttl) when called with the same project path, config, and preset.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
preset	string	No	Analysis preset name (see Presets)
config_path	string	No	Path to a custom arxo.yaml configuration file

Presets

Use presets to run a focused analysis instead of all metrics:

Preset	Metrics	Speed	Use case
quick	scc, l1_overview, centrality	Fast (~seconds)	Pre-commit sanity check
ci	scc, smells, layer_violations, architecture_budgeting	Moderate	CI/CD pipeline gate
risk	ricci_curvature, centrality, msr (includes hotspot score), ownership, truck_factor, causal_discovery, semantic_duplicates	Moderate	Defect and change risk
coupling	propagation_cost, msr (includes hotspot and co-change analysis), coupling_analysis, decoupling_level, clustered_cost_cochange, semantic_duplicates	Slow	Deep coupling audit
security	security, sensitive_data_flow, effect_violations	Moderate	Security analysis
runtime	cloud_cost, traffic_hotspot, critical_path, centrality, runtime_drift, sensitive_data_flow, test_coverage	Moderate	Runtime/performance analysis (requires telemetry)
ai	llm_integration, ml_architecture, rag_architecture, finetuning_architecture, agent_architecture	Moderate	LLM/AI integration audit
rag	rag_architecture, llm_integration	Fast	RAG-specific analysis
full	All 52 metrics	Very slow	Comprehensive review

Tip

Start with quick for fast feedback, then escalate to ci, coupling, or full when you need deeper analysis.

Response

Returns a JSON summary with computed metrics and any policy violations.

Response Schema

{
  "results": [
    {
      "id": "string",           // Metric ID (e.g., "scc", "centrality")
      "version": "string",      // Metric version (e.g., "1.0.0")
      "data": [                 // Metric data entries (key + typed value)
        { "key": "string", "value": { "kind": "number", "v": 0.0 } }
      ],
      "findings_count": "number" // Number of findings/evidence items
    }
  ],
  "violations": [              // Policy violations (if any)
    {
      "metric": "string",
      "expected": "number",
      "actual": "number",
      "operator": "string"
    }
  ],
  "violations_count": "number"
}

Examples

Basic analysis with quick preset

Request:

{
  "project_path": ".",
  "preset": "quick"
}

Response:

{
  "results": [
    {
      "id": "scc",
      "version": "2.0.0",
      "data": [
        { "key": "scc.cycle_count", "value": { "kind": "number", "v": 2 } },
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 5 } },
        { "key": "scc.total_nodes_in_cycles", "value": { "kind": "number", "v": 8 } }
      ],
      "findings_count": 2
    },
    {
      "id": "centrality",
      "version": "1.0.0",
      "data": [
        { "key": "centrality.module.betweenness_max", "value": { "kind": "number", "v": 0.42 } },
        { "key": "centrality.module.max_fan_in", "value": { "kind": "number", "v": 12 } },
        { "key": "centrality.module.max_fan_out", "value": { "kind": "number", "v": 8 } }
      ],
      "findings_count": 3
    }
  ],
  "violations": [],
  "violations_count": 0
}

CI preset with policy violations

Request:

{
  "project_path": "/path/to/project",
  "preset": "ci"
}

Response:

{
  "results": [
    {
      "id": "scc",
      "version": "2.0.0",
      "data": [
        { "key": "scc.max_cycle_size", "value": { "kind": "number", "v": 5 } }
      ],
      "findings_count": 1
    },
    {
      "id": "smells",
      "version": "2.0.0",
      "data": [
        { "key": "smells.hubs.count", "value": { "kind": "number", "v": 2 } },
        { "key": "smells.god_components.count", "value": { "kind": "number", "v": 1 } }
      ],
      "findings_count": 3
    }
  ],
  "violations": [
    {
      "metric": "scc.max_cycle_size",
      "expected": 0,
      "actual": 5,
      "operator": "<="
    }
  ],
  "violations_count": 1
}

Full analysis with custom config

Request:

{
  "project_path": "/path/to/myproject",
  "preset": "full",
  "config_path": "/path/to/myproject/custom-arxo.yaml"
}

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 preset: xyz	Invalid preset name	Use list_presets to see valid options
Failed to load config	Invalid YAML in config file	Check YAML syntax in config_path
Analysis timeout	Large project or slow metrics	Use a faster preset (quick or ci) or increase timeout

Performance

• Caching: Results are cached by (project_path, config_hash, preset). Repeated calls with identical parameters return cached results instantly.
• Cache TTL: Default 300 seconds (5 minutes). Configure via --cache-ttl server argument.
• Speed comparison:
  • quick: 1-5 seconds (small projects), 10-30 seconds (large monorepos)
  • ci: 5-15 seconds (small), 30-90 seconds (large)
  • full: 30-120 seconds (small), 2-10 minutes (large)

Tip

For large projects (>10k files), use incremental analysis via analyze_file_impact to scope metrics to changed files only.

Related Tools

• check_cycles — Fast cycle detection without full analysis
• list_presets — See all available presets
• get_hotspots — Extract hotspots from analysis results
• evaluate_policy — Check policy violations

Related Resources

• metrics://current/<path> — Read cached metrics without re-running analysis
• policy://violations/<path> — Read policy violations

CLI Equivalent

# Same as analyze_architecture with quick preset
arxo analyze --preset quick

# Same as analyze_architecture with custom config
arxo analyze --config custom-arxo.yaml --preset ci