archlens/README.md

archlens

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

Supports Rust and Python. Produces Mermaid or ASCII 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/

# ASCII output to terminal
archlens . --format ascii

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

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

# 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.

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

Diagram Levels

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

Supported Languages

Language	Types	Inheritance	Composition	Imports
Rust	struct, enum, trait	impl Trait for Type	struct fields	use, mod
Python	class	class Foo(Bar)	__init__ params, type annotations	import, from ... import
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
    walkdir/        # File discovery
    mermaid/        # Mermaid diagram output
    ascii/          # Terminal output
    file-writer/    # Write to disk
    stdout-writer/  # Write to stdout
    toml-config/    # Config file parsing
  presentation/     # CLI (clap), composition root

License

MIT