Generate architecture diagrams from Infrastructure-as-Code files (Docker Compose, Helm charts)
npm install @clarity-tools/cliGenerate beautiful, hand-drawn style architecture diagrams from your Infrastructure-as-Code files.
- Auto-detection: Finds docker-compose.yml, compose.yml, and Helm charts
- Smart layout: Semantic grouping with ELK.js layout engine
- LLM enhancement: Optional AI-powered service descriptions (via OpenRouter)
- Excalidraw output: Hand-drawn style diagrams you can edit
- PNG export: High-quality rendered images
``bash`
npm install -g @clarity-tools/cli
Requirements:
- Node.js 18+
- Chromium (auto-downloaded by Puppeteer on first run)
`bashRun in a directory with docker-compose.yml or Helm chart
cd my-project
iac-diagrams
Usage
bash
iac-diagrams [path] [options]
`Arguments:
-
- File or directory to process (default: current directory)Options:
-
-o, --output - Output directory (default: ./docs/diagrams)
- --no-llm - Disable LLM enhancement
- --no-png - Skip PNG rendering (output .excalidraw only)
- --artifacts - Save parsed/enhanced/elk JSON artifacts alongside outputs
- -v, --verbose - Show detailed outputExamples:
`bash
Process current directory
iac-diagramsProcess specific file
iac-diagrams docker-compose.ymlProcess Helm chart directory
iac-diagrams ./charts/my-app/Custom output directory
iac-diagrams -o ./architecture/Skip LLM and PNG (fast mode)
iac-diagrams --no-llm --no-pngVerbose output
iac-diagrams -v
`Configuration
$3
The tool can use OpenRouter's LLM API to:
- Generate service descriptions
- Suggest logical groupings
- Add category metadata
To enable, set your OpenRouter API key:
bash
Set via CLI
iac-diagrams config set-key sk-or-...Or via environment variable
export OPENROUTER_API_KEY=sk-or-...View current config
iac-diagrams config showClear API key
iac-diagrams config clear-key
`Output
Files are saved to the output directory (default
):`
docs/diagrams/
├── docker-compose.excalidraw # Excalidraw JSON (open at excalidraw.com)
└── docker-compose.png # Rendered PNG image
With
, additional JSON files are saved:`
docs/diagrams/
├── docker-compose.parsed.json # Parsed InfraGraph
├── docker-compose.enhanced.json # Enhanced InfraGraph (LLM if enabled)
├── docker-compose.elk-input.json # ELK input graph
└── docker-compose.elk-output.json # ELK output graph (with positions)
The
file can be opened at excalidraw.com for editing.Supported Formats
| Format | Status | Notes |
|--------|--------|-------|
| Docker Compose | ✅ | docker-compose.yml, compose.yml |
| Helm Charts | ✅ | Detects Chart.yaml in directories |
| Kubernetes YAML | 🔜 | Coming soon |
| Terraform | 🔜 | Coming soon |
Troubleshooting
$3
If you see "Browser not available for PNG rendering", Puppeteer couldn't launch Chromium.
Fix:
`bash
Install Chrome for Puppeteer
npx puppeteer browsers install chromeOr use your system Chrome
export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"Or skip PNG generation
iac-diagrams --no-png
`$3
The tool looks for:
-
, docker-compose.yaml
- , compose.yaml
- Directories containing (Helm charts)$3
Ensure your OpenRouter API key is valid:
`bash
iac-diagrams config show
`The key should start with
- Shapes: rectangles for application services, ellipses for databases/caches, diamonds for message queues
- Colors: blue=database, red=cache, green=storage, yellow=queue
- Layering: UI -> API -> worker -> data -> infrastructure
MIT