# Archify Truth Auto Legend Mode vs Explicit Configuration: How It Works

> Compare Archify truth auto legend mode's automatic SVG scanning with explicit configuration's manual JSON control. Understand how to generate legends effortlessly.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-05

---

**Truth auto legend mode automatically generates a legend by scanning SVG nodes for `data-legend-kind` attributes, while explicit configuration lets authors manually define legend entries, order, and labels through a JSON view.**

Archify is an open-source diagramming tool that generates architecture visualizations from JSON definitions. Its **truth auto legend mode** creates legends dynamically based on actual diagram content, eliminating manual configuration. For documentation requiring stable layouts, **explicit legend configuration** provides full control over every legend property.

---

## How Truth Auto Legend Mode Builds Legends Dynamically

When you render a diagram without an explicit legend view, Archify defaults to truth auto legend mode. The runtime viewer scans the generated SVG and constructs the legend on-the-fly.

### The Auto-Legend Scanning Process

In [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html), the implementation locates all elements carrying `data-legend-kind` attributes, tallies occurrences per kind, and injects a toolbar-style legend:

```html
<g data-legend-bridge> … </g>
svg.setAttribute('data-legend-preview-active', kind);

```

This logic appears in lines 3789–3832 and 12450–12494 of the runtime file. The generated container `data-legend-bridge-runtime` updates automatically when underlying data changes—no rebuild required.

### What Users Control in Auto Mode

You do **not** write legend definitions. Influence the legend indirectly through your node definitions:

```json
{
  "meta": {
    "visual_preset": "signal-flow"
  },
  "nodes": [
    { "id": "web", "kind": "frontend", "label": "Web UI" },
    { "id": "api", "kind": "backend", "label": "API Server" },
    { "id": "db", "kind": "database", "label": "Postgres" }
  ],
  "edges": [
    { "from": "web", "to": "api" },
    { "from": "api", "to": "db" }
  ]
}

```

The legend displays three entries (frontend, backend, database) with node counts automatically. If you remove the database node, the entry disappears. Add a `messagebus` node, and it appears.

---

## How Explicit Legend Configuration Overrides Auto Mode

Authors requiring stable legend layouts—regardless of diagram changes—can declare an explicit **legend view** in their JSON.

### Structure of an Explicit Legend View

The [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) defines the schema: a view with `type: "legend"` containing ordered entries with custom labels and count visibility:

```json
{
  "meta": {
    "visual_preset": "signal-flow"
  },
  "views": [
    {
      "id": "my-legend",
      "type": "legend",
      "entries": [
        { "kind": "frontend", "label": "Client-side", "showCount": true },
        { "kind": "backend", "label": "Service Layer", "showCount": false },
        { "kind": "database", "label": "Persisted Data", "showCount": true }
      ],
      "order": ["frontend", "backend", "database"]
    }
  ],
  "nodes": [ … ],
  "edges": [ … ]
}

```

### What Explicit Mode Controls

Explicit configuration enables four capabilities unavailable in auto mode:

1. **Custom labels** — Replace "backend" with "Service Layer"
2. **Entry ordering** — Force sequence regardless of alphabetical or frequency-based sorting
3. **Count suppression** — Hide node counts for specific kinds
4. **Static scope** — Exclude kinds present in the diagram but omitted from `entries`

If your diagram later adds a `messagebus` node, it will **not** appear in the legend unless you update the view definition.

---

## Comparing Truth Auto Legend Mode and Explicit Configuration

| Aspect | Truth Auto Legend Mode | Explicit Legend Configuration |
|--------|------------------------|-------------------------------|
| **Configuration required** | None | JSON view definition |
| **Legend entries** | Derived from actual node kinds | Prescribed by author |
| **Update behavior** | Automatic on data change | Static unless view is edited |
| **Label customization** | Not possible | Full control per entry |
| **Entry ordering** | Determined by occurrence/frequency | Author-defined sequence |
| **Count display** | Always shown | Configurable per entry |
| **Kind filtering** | All kinds appear | Author selects subset |

---

## Switching Between Modes at Runtime

The runtime viewer supports dynamic mode selection through URL parameters.

To force explicit configuration, set the view parameter:

```js
// Navigate to explicit legend view
window.location.hash = '#view=my-legend';

```

Clicking legend entries in the toolbar toggles auto-legend preview states via `data-legend-preview-active`, but this does not override an explicit view when specified in the URL.

---

## Key Implementation Files

Understanding where legend logic lives helps diagnose behavior or extend functionality:

- **[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)** (line 272) — Documents "truthful configurable legends" as a core feature
- **[`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html)** — Contains the auto-legend implementation, attribute scanning, and toolbar injection
- **[`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)** — Specifies the JSON schema for explicit legend views
- **`archify/renderers/*/README.md`** — Explains renderer-specific legend handling

---

## Summary

- **Truth auto legend mode** requires zero configuration: Archify scans `data-legend-kind` attributes in the SVG and builds `data-legend-bridge-runtime` containers dynamically, always reflecting actual diagram contents.
- **Explicit legend configuration** uses a `type: "legend"` view to lock entry order, customize labels, suppress counts, and filter kinds—ideal for stable documentation.
- The runtime viewer in [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html) handles both modes, with URL hash parameters controlling which takes precedence.
- Auto mode hides automatically when no kinds exist; explicit mode persists regardless of underlying data changes.

---

## Frequently Asked Questions

### When should I use explicit legend configuration over auto mode?

Use explicit configuration when your documentation requires consistent legend layouts across diagram versions, or when you need custom labels that differ from raw kind names. Auto mode suits exploratory diagrams where legend contents should always match the current node set.

### Can I combine auto and explicit modes in one diagram?

No. Archify applies one legend strategy per render: explicit views override auto-detection entirely. If any `type: "legend"` view is active via URL parameter or default view selection, the auto-legend code is bypassed.

### Why does my legend entry disappear when I remove nodes in auto mode?

This is the intended behavior of truth auto legend mode. The runtime rebuilds the legend from current `data-legend-kind` occurrences. To preserve an entry regardless of node presence, switch to explicit configuration with that kind listed in `entries`.

### How do I hide node counts in the legend?

Only explicit legend configuration supports count suppression. Set `showCount: false` on individual entries in your legend view definition. Auto mode always displays counts as implemented in [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html) lines 3789–3832.