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

> Archify automatically sizes SVG viewBox and accounts for legend footprint ensuring responsive diagrams without manual tuning. Get perfectly scaled architecture visualizations effortlessly.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-31

---

**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](https://github.com/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`](https://github.com/tt-a1i/archify/blob/main/archify/viewer.js)) writes the attribute directly:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/maka-regenerated.workflow.html) according to the visual‑check test source.

### Explicit vs. Computed Dimensions

Users may supply explicit dimensions via `meta.viewBox`:

```json
{
  "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:

```javascript
// 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

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

```

Compile with:

```bash
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

```json
{
  "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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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.