Introduction to Arxo

Introduction

Arxo is a comprehensive architecture analysis tool that helps you understand, measure, and enforce architectural patterns in your codebase. It supports TypeScript/JavaScript, Python, Rust, Java, Kotlin, and Go — all from a single binary written in Rust.

What Is Arxo?

Arxo parses your source code, builds dependency graphs, computes architectural metrics, and evaluates policy invariants — giving you a quantitative view of your architecture and automated guardrails to prevent drift.

Cycles

Detect and eliminate circular dependencies with SCC analysis.

Coupling

Measure propagation cost — how far changes ripple through the system.

Centrality

Find hub modules with high fan-in/fan-out that are risky to change.

Key Features

Multi-Language Support

Analyze polyglot codebases with a single tool:

• TypeScript / JavaScript — React, Next.js, Node.js, Bun
• Python — Django, Flask, FastAPI
• Rust — Cargo workspaces
• Java — Maven, Gradle
• Kotlin — Android, Spring
• Go — Go modules

Architectural Metrics

Category	Metrics
Structural	SCC (cycle detection), Centrality (fan-in, fan-out, betweenness)
Coupling	Propagation Cost (change impact), Coupling Analysis (composite coupling hotspots), Ricci Curvature (dependency bottlenecks)
Synthesis	L1 Overview (aggregate risk score from structural + coupling metrics)

Policy Enforcement

Define architectural rules in YAML and enforce them in CI/CD to prevent regressions:

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies"
    - metric: propagation_cost.system.ratio
      op: "<="
      value: 0.10
      message: "Keep system propagation cost under 10%"

Multiple Output Formats

Format	Use case
Console	Human-readable terminal output with pass/fail indicators
JSON	Machine-readable for CI/CD pipelines and custom tooling
HTML	Interactive web reports with dependency graph visualization
SARIF	GitHub Code Scanning and VS Code Problems panel integration

Fast and Incremental

• Parallel computation — Metrics run concurrently across available cores.
• Cached results — Repeated analysis returns instantly until the cache TTL expires.
• Incremental mode — Only recompute metrics affected by changed files.
• Preset-based — Run only the metrics you need: quick finishes in seconds, full runs everything.

Quick Start

Installation

Install the pre-built binary from GitHub Releases, or use npm:

npm install -g arxo

See Installation for other options (Docker, direct download).

First Analysis

# Quick health check — SCC, centrality, overview (~seconds)
arxo analyze --preset quick

# Full analysis — all available metrics
arxo analyze --preset full

Sample Output

Analyzing project...
  Parsed 247 files
  Built import graph (183 nodes, 412 edges)

Results:
  scc.max_cycle_size: 0          No cycles
  propagation_cost.system.ratio: 0.12          Low coupling
  centrality.module.hub_like_count: 0   No hubs

No policy violations

How It Works

1. Parse

   Extract imports, function calls, and type relationships from source files across all supported languages.

2. Build Graphs

   Construct import graphs (module-level dependencies), call graphs (function-level), and entity graphs (component relationships).

3. Compute Metrics

   Run metrics in two phases: independent base metrics first (SCC, Propagation Cost, Centrality), then synthesizer metrics that aggregate the base results (L1 Overview).

4. Evaluate Policies

   Check each policy invariant against computed metric values. Report violations with expected vs. actual values.

5. Report

   Output results in your chosen format — Console, JSON, HTML, or SARIF — and exit with a non-zero code if any invariant fails.

See Architecture Overview for a deep dive into the engine internals.

Core Concepts

Metrics

Quantitative measures of architectural properties. Each metric produces one or more numeric values and optional findings (warnings about specific modules or edges).

• SCC — Detects circular dependencies via Tarjan’s algorithm.
• Propagation Cost — Fraction of reachable pairs in the dependency graph (0–1). Lower is better.
• Centrality — Betweenness, fan-in, fan-out, PageRank. Identifies hub modules that sit on many dependency paths.
• L1 Overview — Aggregates base metrics into an overall structural risk score.
• Flow Analysis — Measures dependency flow: node/link count, density, and max fan-in.
• Coupling Analysis — Identifies coupling hotspots across the module graph.

Graphs

The import graph powers the analysis:

Graph	Captures	Used by
Import Graph	Module-level import / require / use edges	SCC, Propagation Cost, Centrality, Flow Analysis, Coupling Analysis, L1 Overview

Policies

Declarative invariants that must hold. Each invariant references a metric value, a comparison operator, and a threshold:

invariants:
  - metric: scc.max_cycle_size
    op: "=="
    value: 0
  - metric: propagation_cost.system.ratio
    op: "<="
    value: 0.10

When an invariant fails, the CLI exits with a non-zero code and reports the violation — making it easy to use as a CI gate.

Presets

Pre-configured analysis profiles that control which metrics run:

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

Use Cases

Development

• Pre-commit hooks — Run arxo analyze --preset quick to catch cycles and hub modules before committing.
• IDE integration — The VS Code extension shows violations inline and provides a metrics dashboard.
• MCP for AI assistants — The MCP server lets Cursor, Claude, and other AI tools call architecture analysis directly.

CI/CD

• Pull request gates — Enforce policies automatically with --fail-fast.
• Baseline comparison — Compare metrics against main to catch regressions in PRs.
• Code scanning — Export SARIF reports for GitHub Code Scanning or GitLab integration.

Architecture Review

• Dependency analysis — Measure propagation cost and find tightly coupled modules.
• Hub detection — Identify god modules with high fan-in and fan-out that are risky to change.
• Cycle elimination — Find and break circular dependencies before they spread.

Example Scenarios

Prevent Circular Dependencies

arxo.yaml

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies allowed"

arxo analyze --preset quick --fail-fast

Enforce Loose Coupling

data:
  import_graph:
    group_by: folder
    group_depth: 2

metrics:
  - id: propagation_cost
  - id: scc

policy:
  invariants:
    - metric: propagation_cost.system.ratio
      op: "<="
      value: 0.15
      message: "Modules must stay loosely coupled"
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies"

Detect Hub Modules

metrics:
  - id: centrality

policy:
  invariants:
    - metric: centrality.module.hub_like_count
      op: "=="
      value: 0
      message: "No god modules with high fan-in and fan-out"
    - metric: centrality.module.max_fan_out
      op: "<="
      value: 15
      message: "No module should depend on more than 15 others"

Next Steps

Installation

Install Arxo with pre-built binaries (no Rust required).

Quick Start

Run your first analysis in under a minute.

Configuration

Set up metrics, policies, and output formats.

Metrics Reference

Browse available metrics and interpretation guides.

Integration

• CI/CD Integration — Automate checks in GitHub Actions, GitLab CI, and Jenkins.
• Library Integration — Use Arxo as a Rust library in your own applications.
• VS Code Extension — Real-time analysis, inline violations, and metrics dashboard.
• MCP Server — Architecture analysis for AI assistants (Cursor, Claude Desktop).

Guides

• Policy Examples — Real-world policy configurations.
• Breaking Cycles — Strategies for fixing circular dependencies.
• Presets — Choosing the right analysis profile.
• Output Formats — Console, JSON, HTML, and SARIF.
• Troubleshooting — Common issues and solutions.

Architecture

• Architecture Overview — How the engine works internally.
• Graph Types — Import, call, and entity graphs explained.

Community and Support

• GitHub: github.com/arxohq/arxo
• Issues: github.com/arxohq/arxo/issues
• Discussions: github.com/arxohq/arxo/discussions