Architecture Overview

Arxo is a multi-language architecture analysis tool that helps you understand, measure, and enforce architectural patterns in your codebase.

How It Works

Arxo operates through a multi-stage pipeline:

Source Code → Parsing → Graph Building → Analysis → Metrics → Policy Evaluation → Report

1. Code Parsing

Arxo parses source files in multiple languages:

TypeScript/JavaScript - Including React, Vue, Angular
Python - Including Django, Flask
Rust - Including Cargo workspaces
Java - Including Maven, Gradle projects
Kotlin - Including Android projects
Go - Including Go modules

The parser extracts:

Import/dependency relationships
Function and method calls
Type definitions and usage
File and module structure

2. Graph Construction

Arxo builds multiple interconnected graphs:

Import Graph

Module-level dependencies
Package relationships
Directory structure
External dependencies

Call Graph

Function-to-function calls
Method invocations
Cross-module calls
Dynamic dispatch resolution

Entity Graph

File-level relationships
Component boundaries
Package structure

3. Analysis & Metrics

Arxo computes 50+ architectural metrics across categories:

Structural - Cycles, centrality, modularity
Coupling - Propagation cost, dependencies
Evolution - Change patterns, hotspots
Quality - Smells, violations, test coverage
AI/LLM - Observability, cost tracking, security
Security - Data flow, sensitive information

4. Policy Evaluation

Define architectural rules in YAML:

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

Arxo evaluates policies and reports violations with context.

5. Output Formats

Arxo generates reports in multiple formats:

Console - Human-readable terminal output
JSON - Machine-readable for CI/CD
HTML - Interactive web reports
SARIF - Integration with code scanning tools
MessagePack - Efficient binary format

Data Flow Diagram

┌─────────────┐
│ Source Code │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  Parser         │ ← Extracts imports, calls, types
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Import Graph   │ ← Module dependencies
│  Call Graph     │ ← Function calls
│  Entity Graph   │ ← File relationships
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Derived Data   │ ← SCCs, reachability, centrality
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Metrics        │ ← 50+ architectural metrics
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Policy Engine  │ ← Evaluate invariants
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Report         │ ← JSON/HTML/Console output
└─────────────────┘

Components

Core Engine (Closed Source)

The core analysis engine handles:

Language parsing and AST extraction
Graph construction and indexing
Metric computation
Performance optimization
Caching and incremental analysis

The engine is distributed as a binary library to ensure:

Consistent analysis across platforms
Optimized performance
Protection of proprietary algorithms

Public Interfaces (Open Source)

Public components you can inspect and extend:

CLI (arxo-cli)

Command-line interface
Configuration loading
Output formatting
Progress reporting

MCP (arxo-mcp) — MCP docs

Model Context Protocol integration
AI assistant tools
Cursor IDE integration

LSP Server (arxo-lsp)

Real-time analysis in editors
Code lens indicators
Diagnostic messages
Quick fixes

Type Definitions (arxo-types)

Data structures
Configuration schema
Plugin interfaces

Key Features

Multi-Language Support

Arxo analyzes multiple languages in a single codebase:

Monorepo support (Nx, Turborepo, Lerna)
Cross-language call tracking
Unified dependency graphs
Language-specific patterns

Incremental Analysis

Arxo caches analysis results:

Only re-analyzes changed files
Persists graph indices
Configurable cache location
Cache invalidation on config changes

Parallel Execution

Metrics are computed in parallel:

Multi-threaded graph operations
Concurrent metric plugins
Memory-efficient streaming
Progress tracking

Extensibility

Arxo supports custom configurations:

Custom metric selection
Configurable thresholds
Language-specific filters
Output customization

Architecture Principles

Language-Agnostic Core - Same analysis pipeline for all languages
Graph-Based Analysis - Everything is modeled as relationships
Incremental Computation - Cache and reuse previous results
Policy as Code - Enforce architecture with declarative rules
Multi-Format Output - Integrate with any toolchain

Performance Characteristics

Typical analysis times (on modern hardware):

Project Size	Files	Analysis Time
Small	<100	1-3 seconds
Medium	100-1,000	5-15 seconds
Large	1,000-10,000	30-90 seconds
Very Large	>10,000	2-5 minutes

Incremental analysis (only changed files): 1-5 seconds

Security & Privacy

Arxo operates entirely locally:

No data sent to external servers
No telemetry or tracking
All analysis happens on your machine
Source code never leaves your environment

Sandbox (Linux)

On Linux you can run the engine in a Landlock self-sandbox with --sandbox. The engine restricts itself before any file I/O: the project path is read-only, only the cache directory (e.g. ~/.cache/arxo) is writable, and network access is not allowed when the kernel supports Landlock ABI v4+. If Landlock is unavailable (e.g. kernel < 5.13), the run continues without sandbox. On macOS and Windows, --sandbox is ignored. See CLI analyze: Sandbox for usage.

Docker (cross-platform)

Run Arxo in a sandboxed container with no network access and read-only filesystem:

docker run --rm --read-only --network=none --cap-drop=ALL \
  -v $(pwd):/workspace:ro -v /tmp/arxo-cache:/home/arxouser/.cache:rw \
  arxo/arxo analyze --path /workspace

Or use the helper script: ./releases/docker/run-sandboxed.sh analyze --path .. See releases/docker/README.md for details.

Next Steps

Configuration Guide - Configure analysis options
CLI Reference - Complete command documentation
Metrics Overview - Available metrics
Policy Examples - Real-world policies