Config Driven Diagrams

Config-Driven Architecture Diagrams

Purpose

Render professional dark-themed architecture diagrams from a declarative JSON config. No manual drawing — define lanes, nodes, arrows, and logos in JSON; the renderer produces SVG (and optionally PNG via Playwright).

When to Use

• Architecture overview diagrams (data platform, microservices, ETL flows)
• Data flow diagrams with swimlanes (Bronze → Silver → Gold, etc.)
• System topology with tech-specific logos and palettes
• Any diagram that needs to be version-controlled and reproducible

Architecture

diagram.json (config)  →  render-diagram.js  →  output.svg + output.png
                              ↑
                        shared/logos/*.svg   (embedded as base64)

Config Schema

{
  "name": "my-architecture",         // filename prefix
  "title": "System Architecture",    // main heading
  "subtitle": "Team · Date",         // optional subheading
  "width": 1600,                     // canvas width (px)
  "height": 1100,                    // canvas height (px)
  "nodeHeight": 100,                 // card height (default: 100)
  "gap": 32,                         // compact gap between nodes
  "padding": 20,                     // inner swimlane padding

  "lanes": [                         // swimlanes (left to right)
    {
      "x": 20,                       // lane X position
      "width": 290,                  // lane width
      "label": "DATA SOURCES",       // header text
      "number": "①",                 // header prefix
      "bgColor": "#1A1520",          // optional background override
      "headerColor": "#C62828",      // optional header override
      "columns": [                   // sub-columns within lane
        {
          "distribution": "even",    // "even" | "compact-top" | "compact-bottom"
          "arrows": true,            // draw vertical arrows between nodes
          "arrowType": "data",       // "data" (solid blue) | "auth" (dashed gray)
          "arrowLabels": ["ingest", "clean"],
          "frame": {                 // optional dashed border
            "label": "SQL Server",
            "color": "#CC2927"
          },
          "nodes": [
            {
              "name": "source_db",
              "subtitle": "Core operational DB",
              "logo": "mssql",       // key from logo map
              "palette": "mssql",    // key from palette map
              "tag": "SERVICE",      // bottom-right tag
              "badge": {             // optional top-right badge
                "label": "PROD",
                "bg": "#2E7D32",
                "color": "#A5D6A7"
              }
            }
          ]
        }
      ]
    }
  ],

  "arrows": [                        // cross-lane arrows
    {
      "type": "data",                // "data" | "auth" | "curved"
      "x1": 310, "y1": 168,
      "x2": 530, "y2": 168,
      "label": "batch / CDC"
    }
  ]
}

Standard Palettes (22)

| Key | Stroke | Use For | |-----|--------|---------| | mssql | #CC2927 | SQL Server | | ingestion | #0078D4 | Azure, ADF | | bronze | #CD7F32 | Bronze layer | | silver | #A8B5C0 | Silver layer | | gold | #DAA520 | Gold layer | | delta | #00ADD8 | Delta tables | | uniform | #00ACC1 | UniForm, protocol bridges | | api | #4E8EE9 | REST APIs | | auth | #5C6BC0 | Auth, security | | spark | #E25A1C | Apache Spark | | snowflake | #29B5E8 | Snowflake | | postgres | #336791 | PostgreSQL | | kafka | #231F20 | Kafka | | redis | #DC382D | Redis | | kubernetes | #326CE5 | Kubernetes | | terraform | #7B42BC | Terraform | | python/pyiceberg | #BA68C8 | Python tools | | dotnet | #512BD4 | .NET | | react | #61DAFB | React | | trino | #DD00A1 | Trino, Flink | | duckdb | #FFC107 | DuckDB | | generic | #546E7A | Default |

Badge Conventions

| Status | bg | color | Example | |--------|-----|-------|---------| | Complete | #2E7D32 | #A5D6A7 | { "label": "COMPLETE", "bg": "#2E7D32", "color": "#A5D6A7" } | | Blocked | #B71C1C | #EF9A9A | { "label": "BLOCKED", "bg": "#B71C1C", "color": "#EF9A9A" } | | In Progress | #E65100 | #FFE0B2 | { "label": "IN PROGRESS", "bg": "#E65100", "color": "#FFE0B2" } | | Not Started | #37474F | #90A4AE | { "label": "NOT STARTED", "bg": "#37474F", "color": "#90A4AE" } |

Layout Engine Rules

Swimlanes

• Vertical lanes, left to right
• Each lane gets a colored header bar + dark background
• Internal columns for multi-column layouts within a lane

Node Distribution

• even: Space nodes evenly in available vertical space
• compact-top: Pack nodes from top
• compact-bottom: Pack nodes from bottom

Overlap Validation

• All node rectangles are checked before rendering
• Build fails with error if any overlap detected
• Formula: nodeHeight * maxNodes + gap * (maxNodes-1) + 170 for height

Cross-Lane Arrows

• data: solid blue line (data flow)
• auth: dashed gray line (auth/config)
• curved: bezier curve with custom color + opacity

Adding Logos

1. Save SVG/PNG to a logos/ directory
2. Register in LOGO_MAP with a key name
3. Add matching palette if needed
4. Logo renders as 36×36 badge with rounded background

CLI Usage

# SVG only
node render-diagram.js --config diagram.json

# SVG + PNG (requires Playwright)
node render-diagram.js --config diagram.json --png

# Custom output directory
node render-diagram.js --config diagram.json --png --out ./output

Tips

1. Width planning: Sum all lane.x + lane.width. Add 20px margins
2. Height planning: Use the overlap formula. Start tall, shrink to fit
3. Fan-out: Use curved arrows from one source to multiple targets
4. Frames: Group related nodes with column.frame (dashed border)
5. Badges: Environment indicators (PROD, DEV, BETA)
6. Tags: Categorize nodes (SERVICE, LAYER, PROTOCOL, CLIENT)
7. Config arrays: Put multiple diagram objects in one JSON file for batch rendering

Reference Implementation

The original renderer is a ~490-line Node.js script that:

• Parses CLI args for config path, PNG flag, output dir
• Defines design tokens (dark theme colors, fonts, sizes)
• Loads logos from filesystem and base64-encodes them
• Renders SVG with swimlane headers, node cards, arrows, legend
• Optionally launches Playwright for PNG screenshot at 2x DPR
• Validates no rectangle overlaps before output

Adapt this pattern for any project that needs reproducible architecture diagrams.

Lessons Learned

• Dark theme is better for presentations — high contrast, looks professional on projectors
• Config > code — changing diagram layout via JSON is 10x faster than editing SVG code
• Overlap validation saves hours — catch layout bugs at build time, not after sharing
• Playwright PNG — 2x DPR gives crisp output for docs and wikis
• Base64 logos — embed SVGs directly in the output → single self-contained file
• Radial layout center node: In radial layouts, the center node stacks logo → name → subtitle → tag vertically. The renderer uses a sequential contentY tracker to avoid overlap. Rule: center.height >= logoSize + 100 to leave room for name + subtitle + tag
• Logo SVGs with explicit fill: Custom SVG logos must NOT include fill attributes on path elements. The renderer applies fill via wrapInBadge(). If the SVG has its own fill matching the badge background, the icon becomes invisible (solid color block). Always use monochrome SVGs without fill
• Content-aware sizing: Allocate lane widths proportionally to content (longest subtitle * 7.5px + 70px). Auth nodes go top, consumers bottom

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CarlosCaPe
• Source: CarlosCaPe/octorato
• License: MIT
• Homepage: https://www.dataqbs.com/octorato

Install and usage instructions live in the source repository linked above.