https://github.com/lsh-0/stacked-svg
https://github.com/lsh-0/stacked-svg
c4 c4-model c4model diagrams-as-code plantuml plantuml-diagrams svg
Last synced: 11 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/lsh-0/stacked-svg
- Owner: lsh-0
- Created: 2025-09-19T06:14:13.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-12-19T06:06:39.000Z (5 months ago)
- Last Synced: 2025-12-22T01:46:48.130Z (5 months ago)
- Topics: c4, c4-model, c4model, diagrams-as-code, plantuml, plantuml-diagrams, svg
- Language: Go
- Homepage:
- Size: 557 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Stacked C4 SVG
Generate self-contained, navigable C4 architecture diagrams from PlantUML with embedded JavaScript navigation.
## Features
- **Self-contained**: Single SVG file with all diagrams and navigation
- **Clickable navigation**: Click diagram elements to drill down between C4 levels
- **Flexible diagram count**: Supports 3 or 4 C4 levels (code level optional)
## Quick Start
1. **Create your PlantUML C4 diagrams** with numbered prefixes:
```
01-context.puml
02-container.puml
03-component.puml
04-code.puml (optional)
```
2. **Generate the stacked SVG**:
```bash
./manage.sh generate > output.svg
# With custom title
./manage.sh generate --title "My System" > output.svg
# With output file
./svg-stacker --output output.svg --title "My System"
```
3. **View the result**: Open the generated SVG in your browser
## Generating C4 Diagrams with Claude
Use the built-in `prompt` command to generate C4 diagrams with Claude Code:
```bash
./svg-stacker prompt
```
This automatically:
1. Detects Claude Code CLI in your PATH
2. Analyzes your project (name, README, languages, key files)
3. Invokes Claude with the full C4 specification and project context
4. Claude generates `.puml` files and saves them to `docs/c4/`
Claude will validate each generated file's syntax and fix any errors until all files pass PlantUML validation.
## How It Works
1. Detects `.puml` files and generates SVGs via PlantUML in temp directory
2. Extracts SVG content and validates XML structure
3. Processes PlantUML `$link` elements and converts to JavaScript onclick handlers
4. Creates layered SVG with embedded navigation controls
5. Pretty-prints embedded SVG content for readability
6. Produces single self-contained file ready for sharing
## Requirements
- Go compiler for building the generator
- PlantUML installed and available in PATH
- PlantUML C4 library for diagram generation
## Usage
### Using manage.sh (recommended)
```bash
# Build
./manage.sh build
# Test
./manage.sh test
# Generate with default title
./manage.sh generate examples/ > example.svg
# Generate with custom title
./manage.sh generate examples/ --title "My Architecture" > example.svg
# Generate to file with title
./manage.sh generate examples/ --output output.svg --title "My System"
```
### Using svg-stacker directly
```bash
# Output to stdout
./svg-stacker > output.svg
# Output to file
./svg-stacker --output output.svg
# With custom title
./svg-stacker --output output.svg --title "My System"
```
## PlantUML File Naming
Files must be numbered 01-04 with the following convention:
- `01-*.puml` - Context diagram (required)
- `02-*.puml` - Container diagram (required)
- `03-*.puml` - Component diagram (required)
- `04-*.puml` - Code diagram (optional)
Example: `01-context.puml`, `02-container.puml`, `03-component.puml`, `04-code.puml`
## Adding Clickable Navigation
To enable drill-down navigation, add `$link` parameter to your PlantUML elements:
```plantuml
System(my_system, "My System", "Description", $link="02-container.svg")
Container(my_container, "Container", "Tech", "Description", $link="03-component.svg")
Component(my_component, "Component", "Description", $link="04-code.svg")
```
The link filenames don't matter - they're replaced with JavaScript navigation.
## Project Structure
- `examples/` - Example PlantUML source files (.puml)
- `main.go` - Go generator source code
- `navigation.js` - JavaScript navigation logic (embedded into final SVG)
- `manage.sh` - Build and generate script
- `svg-stacker` - Compiled Go binary (gitignored)
- `CLAUDE.md` - Development guidance for Claude Code
