codetwin 0.1.16

A code to diagram/documentation generator.

codetwin

A code-to-diagram/documentation generator in Rust.

Status: Phase 3.1 ✅ - Multi-layout architecture generator with Rust + Python support. Generates documentation in multiple formats (dependency graphs, layered architecture, README summaries).

Overview

CodeTwin transforms your codebase into visual documentation through multiple layout strategies:

• Dependency Graph: Shows module interdependencies
• Layered Architecture: Organizes code into logical layers/tiers
• README-Embedded: Compact summaries perfect for GitHub discovery

Perfect for architecture reviews, onboarding, and design documentation.

Installation

Cargo

cargo install codetwin

Python (uv)

uv tool install codetwin

Run without installing (ephemeral):

uvx codetwin --help

npm

npm install -g codetwin

All three package managers install the same native binary. On first run the npm and PyPI wrappers will bootstrap the binary via the cargo-dist installer if not already present.

Quick Start

Generate documentation for your Rust or Python project:

# Generate dependency graph (default)
codetwin gen

# Generate layered architecture
codetwin gen --layout layered

# Generate README summary
codetwin gen --layout readme-embedded

# Watch mode: auto-regenerate on file changes
codetwin watch

# Python example
codetwin gen --source examples/python_sample.py

Layout Options

Dependency Graph (Default)

Shows how modules depend on each other. Ideal for understanding coupling and module relationships.

codetwin gen --layout dependency-graph --output docs/architecture.md

Output includes:

• Module-level dependency diagram (Mermaid)
• List of all modules with functions/structs
• Circular dependency detection

Layered Architecture

Organizes code into logical tiers (UI, API, Business Logic, Database, etc.). Best for architecture reviews.

codetwin gen --layout layered --output docs/layers.md

Output includes:

• Layer definitions with glob patterns
• Modules grouped by layer
• Inter-layer dependency diagram
• Layer responsibilities and key functions

Configure layers in codetwin.toml:

[[layers]]
name = "User Interface"
patterns = ["src/cli.rs", "src/ui/**"]

[[layers]]
name = "Engine"
patterns = ["src/engine.rs"]

[[layers]]
name = "Data Layer"
patterns = ["src/db/**", "src/models/**"]

README-Embedded

Compact summary designed for README files. Perfect for GitHub discovery and quick onboarding.

codetwin gen --layout readme-embedded --output docs/architecture.md

Output includes:

• Component overview table (Module | Purpose | Key Functions)
• Dependency overview diagram (Mermaid)
• Data flow explanation (numbered steps)
• Development guide with key files and contribution guidelines

Keep output under 300 lines for easy README embedding.

Configuration

Create codetwin.toml in your project root:

# Source directories to scan
source_dirs = ["src"]

# Output file for generated documentation
output_file = "docs/architecture.md"

# Layout: dependency-graph, folder_markdown, one_per_file, layered, readme-embedded
layout = "dependency-graph"

# Patterns to exclude from scanning
exclude_patterns = [
  "**/target/**",
  "**/node_modules/**",
  "**/.git/**",
  "**/tests/**"
]

# Discovery respects nested .gitignore files (and .git/info/exclude) in addition to
# exclude_patterns. The ignore rules apply to the directory they live in and below.

# Layer configuration (for layered layout)
[[layers]]
name = "Core"
patterns = ["src/lib.rs", "src/ir.rs"]

[[layers]]
name = "Engine"
patterns = ["src/engine.rs"]

Development

• Rust edition: 2024
• Min Rust: 1.93+ stable
• Key deps: tree-sitter, petgraph, serde, clap

Common tasks:

# Format & lint
cargo fmt --all
cargo clippy --all-targets -- -D warnings

# Test
cargo test --all

# Release build
cargo build --release

# Watch for changes
cargo watch -x test

Release Pipeline

CodeTwin uses cargo-dist to build platform binaries. After a GitHub Release is created, separate workflows publish wrappers to PyPI (uv tool install codetwin) and npm (npm install -g codetwin) that bootstrap the binary on first run via the cargo-dist installer.

Features

✅ Multiple Layouts - Choose the documentation style that fits your needs ✅ Rust + Python Support - Full tree-sitter-based AST parsing ✅ Flexible Configuration - Control layers, patterns, and output formats ✅ Watch Mode - Auto-regenerate on file changes ✅ JSON Export - Structured output for tooling integration ✅ Mermaid Diagrams - Embedded diagrams for visual understanding

Repository

• GitHub: https://github.com/carlosferreyra/codetwin

Changelog

See CHANGELOG.md for release history and notable changes.

License

MIT