Metrics Overview

Arxo provides a comprehensive suite of architecture metrics organized into six categories. Each metric produces numeric values you can track over time and enforce with policy invariants.

Metric Categories

Structure & Organization

Understand how your code is organized: are there circular dependencies? Which modules are critical? Is the codebase layered cleanly?

Circular Dependencies

Finds import cycles — modules that depend on each other directly or indirectly. The single most important health signal.

Critical Modules

Identifies hub modules that many others depend on. These are your highest-risk files when making changes.

Layer Structure

Checks whether your codebase follows a clean top-to-bottom layering, or if dependencies go in every direction.

Module Boundaries

Detects natural clusters of tightly-related files and measures how well-isolated they are from the rest.

Core vs Periphery

Shows which parts of the codebase form a dense, interconnected “core” versus loosely-connected peripheral modules.

Dependencies & Coupling

How far do changes ripple? Where are the dependency bottlenecks? These metrics help you keep modules loosely connected.

Change Impact

Measures what fraction of the system a change can reach. High values mean touching one file can break many others.

Coupling Risk

Ranks modules by composite coupling risk using structural, logical, instability, and ownership signals.

Flow Analysis

Compares structural, git co-change, and runtime flow to surface bottlenecks and mismatch.

Dependency Bottlenecks

Finds narrow points in your dependency graph where too many paths converge — the edges most likely to cause problems.

Change History

Analyze your Git history to see which files change together, who owns what, and where instability is hiding.

Change Patterns

Mines commit history to find change hotspots, frequently modified files, and temporal coupling between modules.

Code Health

Spot architectural problems early: god modules, unstable packages, fragile single-points-of-failure, and complexity hotspots.

Code Smells

Detects structural anti-pattern families (cycles, hubs, god components, hierarchy/interface/feature smells) and rolls them into a risk score.

Effect Violations

Enforces side-effect boundaries with direct/transitive violations, capability leaks, hubs, and coverage confidence signals.

Layer Violations

Enforces explicit layer dependency and effect rules declared in architecture.layers.

Package Health

Checks whether packages follow good design principles — are they too concrete? Too unstable? Too entangled?

Monorepo Governance

Audits package policy violations, blast radius, build graph drift, dependency governance, and ownership risk.

Visibility

Measures public API exposure leakage and structural concentration to highlight boundary and blast-radius risk.

FSD Boundaries

Enforces Feature-Sliced boundaries: cross-slice imports, API bypasses, shared gravity, layer jumps, and slice cycles.

Architecture Resilience

Measures how robust your architecture is to removing a module. Finds single-points-of-failure that could bring things down.

Complexity Hotspots

Identifies areas of high complexity and clusters modules by feature similarity to reveal hidden architectural boundaries.

LLM Architecture

Architecture guardrails for LLM integrations.

LLM Architecture

LLM integration architecture: observability, security, governance, and resilience controls.

ML Architecture

Architecture guardrails for ML training, serving, and MLOps controls.

ML Architecture

ML pipeline architecture: skew, reproducibility, lineage, serving maturity, and monitoring controls.

Fine-tuning Architecture

Architecture guardrails for LLM fine-tuning pipelines.

Fine-tuning Architecture

Fine-tuning pipeline architecture: pinning, lineage, eval integrity, checkpoint safety, and adapter governance.

RAG Architecture

Architecture guardrails for retrieval-augmented generation systems.

RAG Architecture

Retrieval and grounding architecture: latency, freshness, tenant safety, and evaluation controls.

Agent Architecture

Architecture guardrails for multi-agent orchestration and tool-calling systems.

Agent Architecture

Agent and orchestration architecture.

Insights & Actions

Summary scores and concrete recommendations that tell you what to fix and where to start.

Cross-Metric Insights

Combines results from all metrics to surface the most critical architectural issues in one place.

Refactoring Suggestions

Actionable recommendations for breaking cycles, reducing coupling, and improving architecture — with specific files to change.

Quick Start

New to Arxo? Start with these three metrics to get a complete picture:

Circular Dependencies

Are there import cycles?

Change Impact

How far do changes ripple?

Critical Modules

Which modules are most critical?

Quick Reference

Structure & Organization

Metric	What it measures	Good value	Bad value
`scc.max_cycle_size`	Largest cycle size	`0` (no cycles)	> 5 modules
`scc.component_count`	Number of independent components	High (= module count)	Low (many modules merged into cycles)
`centrality.module.max_fan_out`	Most dependencies from a single module	< 10	> 20
`centrality.module.max_fan_in`	Most dependents on a single module	< 15	> 30
`centrality.module.hub_like_count`	Modules with both many dependents and dependencies	0	> 3
`centrality.module.betweenness_max`	How much traffic flows through the busiest module	< 0.30	> 0.60
`hierarchy.module.edge.upward_weight_ratio`	Share of dependency weight going upward/lateral	`<= 0.05`	`> 0.15`
`hierarchy.module.agony.weighted_depth_normalized`	Weighted hierarchy erosion normalized by depth	`<= 0.08`	`> 0.15`
`hierarchy.module.edge.skip_layer_ratio`	Share of edges skipping intermediate layers	`<= 0.10`	`> 0.20`
`modularity.module.best_q`	Community separation quality	`>= 0.30`	`< 0.20`
`modularity.module.singleton_community_ratio`	Partition fragmentation	`<= 0.30`	`> 0.40`
`modularity.module.boundary_edge_ratio`	Cross-community dependency share	`<= 0.55`	`> 0.70`

Dependencies & Coupling

Metric	What it measures	Good value	Bad value
`propagation_cost.system.ratio`	How far changes can ripple (0–1)	< 0.10	> 0.40
`coupling_analysis.risk_index`	Composite module coupling risk (0–1)	< 0.35	> 0.60
`flow_analysis.graph.density`	How interconnected the directed dependency graph is	< 0.10	> 0.30
`flow_analysis.graph.max_fan_in_weight`	Highest inbound dependency weight for one module	< 10	> 25
`flow_analysis.graph.flow_hierarchy`	DAG-likeness of flow (higher means fewer cycle edges)	> 0.80	< 0.60

These are interpretation bands. Default propagation_cost finding thresholds are intentionally stricter for alerting (system_high: 0.5, system_critical: 0.7) to reduce noise.

Insights & Actions

Metric	What it measures	Good value	Bad value
`l1.risk.overall`	Overall architecture risk score	< 0.30	> 0.60
`l1.risk.structure`	Structure sub-score	< 0.30	> 0.60

How Metrics Relate

Source Code
  │
  ▼
Import Graph ──► Grouping (file / folder / package)
  │
  ├─ Structure & Organization
  │   ├──► Circular Dependencies (cycles)
  │   ├──► Critical Modules (fan-in, fan-out, hubs)
  │   ├──► Layer Structure, Module Boundaries, Core vs Periphery
  │
  ├─ Dependencies & Coupling
  │   ├──► Change Impact (propagation cost)
  │   └──► Dependency Bottlenecks
  │
  ├─ Code Health
  │   ├──► Code Smells, Package Health
  │   └──► Architecture Resilience, Complexity Hotspots
  │
  └─ Insights & Actions
      ├──► Cross-Metric Insights (combines all of the above)
      └──► Refactoring Suggestions (what to fix)

Structure, Dependencies, and Code Health metrics run independently in parallel. Insights & Actions runs after — it reads all the results and produces summary scores and recommendations.

Metric Selection Guide

Microservices / Modular Monoliths

Goal: Keep services loosely coupled and cycle-free.

metrics:
  - id: scc
  - id: propagation_cost
  - id: centrality
  - id: fsd_architecture
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies between services"
    - metric: propagation_cost.system.ratio
      op: "<="
      value: 0.15
      message: "Services must stay loosely coupled"

Monolith / Feature-Sliced Design

Goal: Enforce layer boundaries and keep module coupling low.

data:
  import_graph:
    group_by: folder
    group_depth: 2
metrics:
  - id: scc
  - id: propagation_cost
  - id: centrality
  - id: fsd_architecture
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
    - metric: centrality.module.hub_like_count
      op: "=="
      value: 0
      message: "No god modules allowed"
    - metric: fsd.public_api_bypass_count
      op: "=="
      value: 0
      message: "Do not bypass slice public APIs"

Quick CI Gate

Goal: Fast pass/fail check on every pull request.

metrics:
  - id: scc
policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0

arxo analyze --preset quick --fail-fast

Using Presets

Presets control which metrics run. For the core metrics:

Preset	Included metrics	Typical time
`quick`	SCC, L1 Overview, Centrality	1–5 seconds
`full`	All available metrics	Varies by project size

# Fast feedback
arxo analyze --preset quick

# Everything
arxo analyze --preset full

See Presets for the full list of available presets.

Interpretation Tips

Track trends, not just absolutes — A propagation_cost.system.ratio of 0.12 is fine on its own; what matters is whether it’s growing or shrinking over time.
Group by folder, not file — File-level graphs are noisy. Use group_by: folder with group_depth: 2 for meaningful module boundaries.
Combine metrics — SCC tells you if there are cycles; Centrality tells you which modules are critical; Propagation Cost tells you how far changes reach. Together they give a complete picture.
Start strict, relax later — Set scc.max_cycle_size == 0 from day one. It’s much harder to remove cycles than to prevent them.
Focus on fan-out first — High fan-out modules are the easiest to refactor (extract shared dependencies) and yield the biggest coupling reduction.