diagram-workflow

Diagram Workflow

End-to-end architecture diagram pipeline: define a JSON graph → render SVG → inject into project markdown → rebuild site.

When to use

When creating or updating architecture diagrams for portfolio project pages.

Prerequisites

• bun runtime
• rsvg-convert (for PNG previews, optional)
• The scripts in this addon's scripts/ directory

Graph JSON spec

Each diagram is a JSON file in _diagrams/{project-id}.json:

{
  "title": "Caption below the diagram",
  "nodes": [
    {
      "id": "unique-id",
      "label": "Box label",
      "sub": "Subtitle text",
      "tag": "web",
      "column": 0,
      "row": 0,
      "children": [
        { "id": "child", "label": "Child box", "sub": "detail", "tag": "scripting" }
      ]
    }
  ],
  "edges": [
    { "from": "source-id", "to": "target-id", "label": "optional annotation", "accent": true }
  ]
}

Semantic tags

Tag	Use for
web	frontends, browsers, UIs
backend	servers, APIs, runtimes
state	databases, stores, config
artifacts	builds, files, models
processing	engines, pipelines, transforms
scripting	scripting, plugins, extensions
infra	containers, VMs, infrastructure
external	external services, APIs, providers
input	user input, sources, triggers
output	results, exports, destinations
monitor	monitoring, logging, observability

Tags control box colours consistently across all diagrams. Use "style": "box-accent" to override.

Layout rules

• column (0-based, left-to-right) and row (0-based, top-to-bottom) control placement
• Nodes with children get a dashed group container; children render as smaller boxes below the parent
• Column width auto-expands when children are wider than BOX_W
• Arrows are orthogonal with rounded corners (r=14), routed to the inner parent rect

Edge guidelines

• Be sparing with labels — only annotate when the relationship isn't obvious
• Use "accent": true for the primary data flow path
• Use "color": "#hex" for custom arrow colours