archlens

Generate architecture diagrams from source code. Runs on CI to keep docs fresh.

Supports Rust, Python and C# (planned). Produces Mermaid, D2, ASCII, or interactive HTML output.

Install

cargo install --path crates/presentation

Usage

# Module-level dependency graph (default)
archlens .

# Project-level (crate/package dependencies from manifests)
archlens . --level project

# Type-level class diagram
archlens . --level type

# Write to file
archlens . --output docs/architecture.mmd

# Split by module (one file per module + overview)
archlens . --level type --split-by-module --output docs/arch/

# D2 format
archlens . --format d2 --output docs/architecture.d2

# Interactive HTML viewer
archlens . --format html --output docs/architecture.html

# ASCII output to terminal
archlens . --format ascii

# Scope to a subtree
archlens . --scope src/domain

# Exclude directories
archlens . --exclude tests/ --exclude generated/

# Exclude test files from diagrams (default: excluded)
archlens . --include-tests

# Show/hide dependency weights on module arrows (default: shown)
archlens . --level module --no-weights

# Watch for changes and regenerate automatically
archlens . --watch

# Analyse only files changed since a git ref (useful in CI)
archlens . --since HEAD~1

# Verbose logging
archlens . -v    # info
archlens . -vv   # debug

CI Integration

Check if committed diagrams are up to date:

archlens . --level project --check --output docs/architecture.mmd

Exit code 1 if the diagram has changed. Use --strict to also fail on parse warnings or boundary rule violations.

Only re-analyse files changed since the last release tag:

archlens . --since v1.2.0 --output docs/architecture.mmd

Compare current state against an existing file:

archlens diff docs/architecture.mmd --level project

Config

Generate a config file:

archlens init

Creates archlens.toml:

[analysis]
exclude = ["tests/", "vendor/", "generated/"]
level = "module"

[modules]
# "src/infra" = "Infrastructure"

[output]
format = "mermaid"
# path = "docs/architecture.mmd"
split_by_module = false

[rules]
# Allowed dependency directions — unlisted directions are violations
# allow = ["Application --> Domain", "Adapters --> Domain"]

# Explicitly forbidden directions — always checked
# deny = ["Domain --> Adapters", "Domain --> Application"]

Violations are printed to stderr. Pass --strict to exit with code 1 on any violation.

Diagram Levels

Level	What it shows	Source
project	Crate/package dependencies	Cargo.toml or pyproject.toml
module	Module-level dependency graph with coupling weights	Imports + manifest deps
type	Class diagram with fields, methods, signatures, relationships	Source code (tree-sitter)

Output Formats

Format	Flag	Extension	Notes
Mermaid	--format mermaid	.mmd	Default. Renders in GitHub, GitLab, Obsidian
D2	--format d2	.d2	Better layout control, renders to SVG
ASCII	--format ascii	.txt	Terminal-friendly
HTML	--format html	.html	Self-contained interactive viewer, clickable nodes

Supported Languages

Language	Types	Inheritance	Composition	Imports	Method signatures
Rust	struct, enum, trait	impl Trait for Type	struct fields	use, mod	params + return type
Python	class	class Foo(Bar)	__init__ params, type annotations	import, from ... import	typed params + return annotation
C#	planned	-	-	-	-

Architecture

Built with hexagonal architecture (ports and adapters) + DDD.

crates/
  domain/             # Core model, zero external deps
  application/        # Use cases, orchestration
  adapters/
    tree-sitter/      # Source code parsing (Rust, Python)
    cargo-workspace/  # Cargo.toml dependency extraction
    python-project/   # pyproject.toml dependency extraction
    walkdir/          # File discovery
    mermaid/          # Mermaid diagram output
    d2/               # D2 diagram output
    ascii/            # Terminal output
    html-viewer/      # Interactive HTML output
    file-writer/      # Write to disk
    stdout-writer/    # Write to stdout
    toml-config/      # Config file parsing
  presentation/       # CLI (clap), composition root

License

MIT