# How to Configure Legends in Archify Architecture Diagrams: Complete Guide to meta.legend

> Easily configure legends in Archify architecture diagrams using meta.legend. Control visibility and customize entries for clear visualization. Learn how now.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Configure legends in archify architecture diagrams by defining the `meta.legend` object in your architecture-IR JSON, using the `mode` property to control visibility (`auto`, `all`, or `hidden`) and the `entries` object to customize labels and visibility per component type.**

Archify automatically generates diagram legends from the metadata section of your architecture-IR files, providing visual keys that map component types to their semantic meanings. Understanding how to configure legends in archify architecture diagrams allows you to suppress irrelevant entries, customize labels, or display a complete reference regardless of diagram content. The legend system follows the JSON schema defined in [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json#L36-L55) and references reusable definitions in [[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json).

## Understanding the Legend Schema

The **legend configuration** resides within the `meta` object of your architecture definition. According to the source schema in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) (lines 36-55), the `meta.legend` object controls how the visual key renders alongside your diagram.

### Component Type Definitions

Legend entries correspond directly to **component types** defined in [[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json#L20-L22). The seven recognized types are:

- `frontend`
- `backend`
- `database`
- `cloud`
- `security`
- `messagebus`
- `external`

When a component of a given type exists in your diagram, Archify creates a corresponding legend entry unless explicitly configured otherwise.

## Legend Display Modes

The **`meta.legend.mode`** property, defined in [[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json#L26-L28), determines when the legend appears. This property accepts three string values that govern visibility behavior.

### Auto Mode (Default)

When `mode` is set to **`auto`** or omitted entirely, Archify displays legend entries only for component types actually present in the diagram. This is the default behavior demonstrated in [[`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json)](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json).

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Flow" },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "UI", "pos": [40,200] },
    { "id": "backend", "type": "backend", "label": "Service", "pos": [200,200] }
  ],
  "connections": [
    { "from": "frontend", "to": "backend" }
  ]
}

```

In this configuration, only the *frontend* and *backend* entries appear in the rendered legend.

### All Mode

Setting `mode` to **`all`** forces the legend to display every possible component type, regardless of whether those components exist in the current diagram. Use this when you want a complete reference key visible for documentation consistency.

### Hidden Mode

The **`hidden`** value suppresses the legend entirely, removing the visual key from the rendered output. Use this for diagrams where component meanings are self-evident or explained in accompanying text.

## Customizing Legend Entries

The **`meta.legend.entries`** object, defined in [[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json#L29-L36), provides per-type customization. Each key corresponds to a component type and accepts two properties:

- **`label`**: Overrides the default display text for that component type
- **`visible`**: A boolean that forces the entry to show (`true`) or hide (`false`), overriding the `mode` setting for that specific type

### Per-Type Label Overrides

Customize the displayed text to match your domain terminology. For example, change `database` to "Postgres DB" or `frontend` to "Web UI" to provide context-specific documentation.

### Visibility Control

The `visible` property creates exceptions to the global `mode`. Even when `mode` is `"all"`, you can hide specific entries by setting `"visible": false`. Conversely, in `"auto"` mode, you can force an entry to appear even without corresponding components by setting `"visible": true`.

## Configuration Examples

### Full Custom Legend Configuration

This example demonstrates complete legend control with custom labels and selective visibility:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "My Service",
    "legend": {
      "mode": "all",
      "entries": {
        "frontend":  { "label": "Web UI",          "visible": true },
        "backend":   { "label": "API Service",    "visible": true },
        "database":  { "label": "Postgres DB",    "visible": false },
        "cloud":     { "label": "AWS Cloud" },
        "security":  { "label": "Auth Layer" },
        "messagebus":{ "label": "Kafka Bus" },
        "external":  { "label": "Third-Party API" }
      }
    }
  },
  "components": [
    { "id": "ui",   "type": "frontend",   "label": "UI",   "pos": [40,300] },
    { "id": "api",  "type": "backend",    "label": "API",  "pos": [200,300] },
    { "id": "pg",   "type": "database",   "label": "DB",   "pos": [360,300] }
  ],
  "connections": [
    { "from": "ui",   "to": "api" },
    { "from": "api",  "to": "pg" }
  ]
}

```

The legend always appears because `mode` is `"all"`. The *Database* entry remains hidden despite the presence of a database component due to `"visible": false`.

### Minimal Auto Mode Configuration

For diagrams requiring no special customization, omit the `legend` object entirely:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Service Architecture" },
  "components": [
    { "id": "web", "type": "frontend", "label": "Web App", "pos": [100,100] },
    { "id": "svc", "type": "backend", "label": "API", "pos": [300,100] }
  ]
}

```

Archify automatically generates a legend containing only the *frontend* and *backend* entries.

## Summary

- **Configure legends in archify architecture diagrams** using the `meta.legend` object in your architecture-IR JSON.
- Set **`mode`** to `auto` (show only present types), `all` (show every type), or `hidden` (suppress legend) as defined in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) lines 26-28.
- Customize individual entries using the **`entries`** object with `label` and `visible` properties per component type.
- Component types (`frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`) are defined in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) lines 20-22.
- The complete schema specification resides in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) lines 36-55.

## Frequently Asked Questions

### How do I hide specific component types from the legend?

Add an entry to `meta.legend.entries` with the component type as the key and set `"visible": false`. For example, to hide database entries: `"database": { "visible": false }`. This override works regardless of the global `mode` setting or whether components of that type exist in your diagram.

### What is the default legend behavior in Archify?

By default, Archify uses **`auto`** mode, displaying legend entries only for component types present in your diagram. If you omit the `meta.legend` object entirely, the system automatically generates a minimal legend based on the components array, as implemented in the rendering engine according to [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json).

### Can I customize the label text for component types?

Yes. Within `meta.legend.entries`, specify the component type key and provide a custom string for the `label` property. For example, `"frontend": { "label": "React Applications" }` changes the legend display from the default "Frontend" to your custom text, improving semantic clarity for specialized documentation.

### Where is the legend schema defined?

The legend schema is defined in two locations within the tt-a1i/archify repository. The main `meta.legend` object structure appears in [[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json#L36-L55), while reusable definitions including `legendMode`, `legendEntry`, and `componentType` enums are located in [[`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json).