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

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, the implementation locates all elements carrying data-legend-kind attributes, tallies occurrences per kind, and injects a toolbar-style legend:

<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:

{
  "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 defines the schema: a view with type: "legend" containing ordered entries with custom labels and count visibility:

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

// 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 (line 272) — Documents "truthful configurable legends" as a core feature
• experiments/mco-showcase/mco-runtime.html — Contains the auto-legend implementation, attribute scanning, and toolbar injection
• 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 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 lines 3789–3832.

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