How Archify Automatically Sizes SVG viewBox and Accounts for Legend Footprint in Architecture Diagrams

Archify auto‑sizes the SVG viewBox based on intrinsic layout measurements and automatically reserves space for visible legends, ensuring responsive diagrams without manual dimension tuning.

Every diagram rendered by tt‑a1i/archify outputs as a self‑contained SVG file. The library eliminates guesswork around canvas sizing by computing the exact bounding box needed for all nodes, edges, and overlays—then adjusting further when a legend is displayed. This article explains the mechanics of Archify viewBox auto‑sizing and legend footprint handling, with source‑level detail from the runtime viewer and compiler test suite.

How Automatic viewBox Sizing Works in Archify

Archify's layout engine measures every visual element during compilation to establish the diagram's extents. These measurements flow directly into the SVG's viewBox attribute.

Measuring Layout Extents

When the JSON‑IR (intermediate representation) for a diagram is compiled, the engine walks the graph and records dimensions for:

• Nodes and their labels
• Edges and connection points
• Lanes, panels, and grouping containers

The resulting bounding box becomes the viewBox dimensions. The core routine in the runtime viewer (archify/viewer.js) writes the attribute directly:

mapSvg.setAttribute(
  'viewBox',
  [viewBox.x, viewBox.y, viewBox.width, viewBox.height].join(' ')
);

This code appears at line 11855 in generated artifacts such as maka-regenerated.workflow.html according to the visual‑check test source.

Explicit vs. Computed Dimensions

Users may supply explicit dimensions via meta.viewBox:

{
  "meta": {
    "viewBox": [720, 400]
  }
}

When omitted, Archify computes the size from layout capacity. The test case explicit viewBox height capacity names the authored tall node in archify/test/workflow-compiler.test.mjs (lines 715‑722) validates this behavior—verifying that computed sizes accommodate the tallest node without clipping.

The computed viewBox then feeds into scaling logic that clamps viewport requests, preventing pan or zoom operations from revealing empty space outside the diagram. This safeguard appears in archify/test/visual-check.test.mjs (lines 11547‑11569).

Legend Footprint and viewBox Adjustments

Legends in Archify are optional overlays that annotate semantic kinds (e.g., database, backend, frontend). Their visibility directly impacts the required canvas size.

Legend Modes and viewBox Impact

Legend configuration lives under meta.legend.mode with values including:

• hidden — legend excluded, viewBox shrinks to content only
• all — full legend displayed, viewBox expands to accommodate
• Additional preset modes for right‑side or bottom positioning

Tests in workflow-compiler.test.mjs confirm that toggling meta.legend.mode from hidden to all resizes the viewBox accordingly. This ensures no diagram element is obscured by the legend overlay.

Runtime Legend Measurement

The viewer measures the legend's rendered footprint before finalizing dimensions:

// From archify/test/viewer-chrome-layout.test.mjs (lines 161-190)
const legendRect = legend.getBoundingClientRect();
// legendRect.width and legendRect.height added to viewBox capacity

This integration test verifies that the browser‑measured DOM rectangle correctly influences the final SVG boundaries.

Hidden Legend Optimization

When meta.legend.mode is set to hidden, the layout engine deliberately excludes the legend's footprint from calculations. The test in visual-check.test.mjs (lines 64‑84) validates that no empty margin persists where the legend would have appeared—preventing wasted canvas space in exported images.

Practical Code Examples

Let Archify Compute viewBox Automatically

{
  "title": "Sample Architecture",
  "nodes": [{ "id": "frontend", "type": "component", "label": "Browser" }],
  "edges": [{ "source": "frontend", "target": "api" }],
  "meta": {
    "legend": { "mode": "hidden" }
  }
}

Compile with:

node archify/bin/archify.mjs deliver architecture.json out.html

The resulting SVG carries a viewBox matching intrinsic layout—no explicit size declaration needed.

Fixed viewBox with Legend Auto‑Positioning

{
  "meta": {
    "title": "Fixed Size",
    "viewBox": [720, 400],
    "legend": { "mode": "all" }
  }
}

Archify honors the [720, 400] dimensions while auto‑positioning the legend inside this rectangle, ensuring no overflow.

Inspect Computed viewBox at Runtime

const svg = document.querySelector('svg');
const vb = svg.viewBox.baseVal;
console.log(`viewBox = ${vb.width}×${vb.height}`);

Works in any rendered Archify artifact, including examples/web-app.html.

Key Implementation Files

File	Responsibility
archify/bin/archify.mjs	CLI entry; invokes compiler for layout and viewBox calculation
archify/test/workflow-compiler.test.mjs	Unit tests for viewBox capacity and legend interactions
archify/test/viewer-chrome-layout.test.mjs	Integration tests for runtime legend footprint measurement
archify/generated/<artifact>.html	Runtime viewer with final viewBox assignment (line 11855)
archify/test/visual-check.test.mjs	Overflow prevention and hidden legend margin elimination

Summary

• Automatic measurement — Archify walks all diagram elements to determine intrinsic bounds, eliminating manual viewBox tuning.
• Legend awareness — Visible legends expand the viewBox via runtime DOM measurement; hidden legends trigger footprint exclusion.
• Responsive guarantees — The computed viewBox ensures uniform browser scaling without cropping or whitespace artifacts.
• Export fidelity — PNG/SVG exports retain exact viewBox dimensions matching on‑screen rendering.

Frequently Asked Questions

Can I override Archify's automatic viewBox sizing?

Yes. Provide meta.viewBox: [width, height] in your diagram JSON. Archify will use these dimensions while still auto‑positioning legend overlays within the specified rectangle.

Does a hidden legend affect exported image dimensions?

No. When meta.legend.mode is hidden, the layout engine excludes the legend footprint entirely. Exported images contain only diagram content with no reserved legend margin.

How does Archify prevent legend content from being clipped?

The runtime viewer calls legend.getBoundingClientRect() and adds the measured width/height to viewBox capacity before finalizing the SVG. This integration-tested behavior (in viewer-chrome-layout.test.mjs) guarantees legends render fully within the visible canvas.

What happens if I resize the browser window?

Archify's viewBox remains fixed to content bounds while the browser scales the SVG uniformly. The scaling logic in visual-check.test.mjs clamps viewport transformations, ensuring panning and zooming never reveal empty space outside the diagram's measured extents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}