code-to-diagram

Code to Diagram

Extract import and dependency relationships from a codebase via AST parsing, and automatically generate three types of diagrams:

1. Architecture Diagram — Module/directory-level dependency relationships
2. Flowchart — File-level import call chains
3. Org Chart — Directory/file hierarchy structure

Supported languages: Python, JavaScript, TypeScript, Go, Java

Output formats: Mermaid text (.mmd) or SVG images (requires mmdc installed on the system)

Usage

Basic: Analyze an Entire Project

python3 scripts/analyze_codebase.py /path/to/project

Outputs three Mermaid diagrams to stdout and writes .mmd files to the current directory.

Specify Diagram Type

# Architecture diagram only
python3 scripts/analyze_codebase.py /path/to/project --type architecture

# Flowchart only
python3 scripts/analyze_codebase.py /path/to/project --type flowchart

# Org chart only
python3 scripts/analyze_codebase.py /path/to/project --type org

Specify Output Directory and Format

# Output to a specific directory
python3 scripts/analyze_codebase.py /path/to/project --output /tmp/diagrams

# Output as SVG (requires mmdc)
python3 scripts/analyze_codebase.py /path/to/project --format svg

# Output both Mermaid and SVG
python3 scripts/analyze_codebase.py /path/to/project --format both

Output JSON Analysis Results

python3 scripts/analyze_codebase.py /path/to/project --json

Parameters

| Parameter | Description |

|-----------|-------------|

| directory | Code directory to analyze (required) |

| --type, -t | Diagram type: architecture, flowchart, org, all (default: all) |

| --output, -o | Output directory (default: current directory) |

| --format, -f | Output format: mermaid, svg, both (default: mermaid) |

| --max-files | Maximum number of files to scan (default: 500) |

| --max-depth | Maximum depth for org chart (default: 4) |

| --json | Output analysis results in JSON format |

How It Works

1. Scan phase: Recursively traverse the directory, skipping node_modules, .git, __pycache__, etc.
2. Parse phase:

• Python files: uses the ast module to parse import and from ... import statements
• JS/TS files: uses regex to match import, require, and export from
• Go files: uses regex to match import statements
• Java files: uses regex to match import statements

1. Resolve internal dependencies: Maps import paths to actual files within the project
2. Generate diagrams: Converts dependency relationships into Mermaid diagram syntax
3. Render (optional): Calls mmdc (Mermaid CLI) to render .mmd files as SVG

Use Cases

• Quickly understand the module structure of an unfamiliar project
• Visualize dependencies during code review
• Create architecture diagrams for technical documentation
• Detect circular dependencies or excessive coupling
• Analyze project structure before refactoring

Dependencies

• Python 3.7+ (standard library only, no extra packages needed)
• SVG output requires @mermaid-js/mermaid-cli (optional)

Notes

• Only analyzes static import relationships; dynamic imports are not tracked
• For large projects, use --max-files to limit the scan scope
• Mermaid diagrams with too many nodes may be hard to render; use --type to generate diagrams separately