codetwin 0.1.9

A code to diagram/documentation generator.
Documentation

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

Python (uv)

Install via uv (recommended):

uv tool install codetwin
codetwin gen --help

Run without installing (ephemeral):

uvx codetwin --help

Rust (Cargo)

You can build and run locally with Cargo (Rust toolchain required):

# From the repository root
cargo install --path .

Or run directly:

cargo run -- gen --help

Quick Start

Generate documentation for your Rust or Python project:

# Generate dependency graph (default)
ct gen

# Generate layered architecture
ct gen --layout layered

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

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

# Python example
ct 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.

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

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

ct 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 treats cargo-dist binaries as the source of truth for all CLI wrappers. The GitHub Release artifacts produced by cargo-dist are reused to populate codetwin/_bin/ before uv build, so the PyPI wheel always ships the exact same binaries that were released.

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

Changelog

See CHANGELOG.md for release history and notable changes.

License

MIT