# 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):
```bash
uv tool install codetwin
codetwin gen --help
```
Run without installing (ephemeral):
```bash
uvx codetwin --help
```
### Rust (Cargo)
You can build and run locally with Cargo (Rust toolchain required):
```bash
# From the repository root
cargo install --path .
```
Or run directly:
```bash
cargo run -- gen --help
```
## Quick Start
Generate documentation for your Rust or Python project:
```bash
# 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.
```bash
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.
```bash
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`:
```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.
```bash
ct gen --layout readme-embedded --output docs/architecture.md
```
**Output includes**:
- 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:
```toml
# 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:
```bash
# 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
- GitHub: <https://github.com/carlosferreyra/codetwin>
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for release history and notable changes.
## License
MIT