awslabs / awslabs/diagram-as-code
Support draw.io (mxGraph XML / .drawio) as an output format
- Dominant language
- Go
- Stars
- 1.6k
- Forks
- 101
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 2
Description
**Is your feature request related to a problem? Please describe.**
`awsdac` only emits a rasterized PNG (`output.png`). Once a diagram is generated it
cannot be re-opened or edited as a vector graphic. Many teams iterate on architecture diagrams
in [diagram.net (draw.io)](https://www.drawio.com/), where shapes, groups, and connections are
editable objects. Because the PNG is the only artifact, users who want to hand-tweak layout,
restyle, or extend a generated diagram have to start over by hand. There is no way to round-trip
from "diagram as code" into an editable canvas.
The automated, code-driven generation is genuinely valuable — it keeps diagrams reproducible,
reviewable, and in sync with infrastructure, and it covers the vast majority of cases well. But
in practice there are situations where the last-mile appearance still needs manual adjustment:
for deliverables such as proposal documents, design review decks, or customer-facing
presentations, people often want to nudge a node's position, tweak spacing or colors, add an
annotation, or otherwise polish small visual details that a fully automated layout doesn't
intend to control. With PNG-only output, those final touches force the diagram out of the tool
entirely. An editable draw.io export would let users keep the auto-generated diagram as the
source of truth and still do the small, presentation-oriented refinements on top of it.
**Describe the solution you'd like**
Add a draw.io / mxGraph XML (`.drawio`) exporter as an alternative output format, selected by the
output file extension (e.g. `awsdac input.yaml -o diagram.drawio`).
The internal diagram model is already format-agnostic and fully resolved before rasterization, so
this can be done without touching layout logic:
- `internal/types/Resource` already carries geometry (`bindings`), fill/border colors, border
type, label, `direction`/`align`, `children`, and `links`.
- `internal/types/Link` carries source/target, Windrose connection points, arrowheads, line
style/width, and labels.
- `canvas.Scale()` → `ZeroAdjust()` (`internal/ctl/create.go`) resolves all absolute coordinates
before the current `png.Encode(...)` call, so an exporter can consume the same graph.
Proposed approach:
1. Introduce an output-encoder abstraction so the format isn't hardcoded, e.g.:
```go
type DiagramEncoder interface {
Encode(w io.Writer, resources map[string]*types.Resource) error
}
2. Refactor the existing PNG path in createDiagram() (internal/ctl/create.go) into a
PNGEncoder implementing this interface (preserving current behavior, including
--width/--height resizing).
3. Add a new DrawioEncoder that walks the resolved Resource/Link graph and emits mxGraph
XML: resources → mxCell vertices with absolute mxGeometry, groups/children → nested
cells, links → mxCell edges with source/target and arrow/line styling.
4. Dispatch on the -o output file extension (.png vs .drawio), defaulting to PNG for
backward compatibility.
**Describe alternatives you've considered**
- SVG export instead of/in addition to draw.io — produces a vector image but, like PNG, is
not natively re-editable as draw.io objects (shapes/containers/edges). draw.io can import SVG
but only as a flat image, losing the object graph. Could be a complementary follow-up.
- A standalone converter tool (PNG/YAML → drawio) — keeps awsdac unchanged but duplicates
layout knowledge and can't reuse the already-resolved geometry, so it would be more fragile.
- Status quo (PNG only) — keeps things simple but blocks the edit/round-trip workflow.
**Additional context**
Known mapping challenges worth discussing before implementation:
- AWS service icons: decide whether to reference draw.io's built-in AWS shape library
(shape=mscae/... / mxgraph.aws4.*) or embed the icon images, so the result looks correct
when opened in draw.io.
Contributor guide
Research direction
Start in internal/ctl/create.go, reading createDiagram(), canvas.Scale(), ZeroAdjust(), and the existing png.Encode(...) path; then inspect internal/types/Resource and Link. Done means preserving PNG behavior while dispatching .drawio output and producing editable mxGraph XML for resolved resources, groups, links, geometry, and styling.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100