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

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#L36-L55) and references reusable definitions in [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 (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/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/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).

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

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

{
  "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 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 lines 20-22.
• The complete schema specification resides in 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.

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#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).

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