How to Work with Node Component Types and Variants in Archify

Assign a type field to each component in your *.architecture.json file (external, frontend, backend, security, cloud, or messagebus) and use the variant attribute on connections to control visual styling.

Archify visualizes system architecture as a directed graph where components act as nodes and connections form the edges. The rendering engine in tt-a1i/archify derives all visual properties—colors, icons, line styles—from declarative metadata in your architecture JSON files. This guide explains how to leverage built-in component types and connection variants to produce clear, semantically meaningful diagrams.

Understanding Component Types

Archify recognizes six built-in component types. Each maps to a specific CSS variable set that controls fill color, stroke, and iconography in the generated HTML output.

Type	Semantic Purpose	Real Example from archify-repo.architecture.json
external	Actors outside system boundaries	"type": "external" for the You node【examples/archify-repo.architecture.json#L11-L14】
frontend	UI layers that render or capture data	"type": "frontend" for Agent Hosts【examples/archify-repo.architecture.json#L19-L22】
backend	Server-side processing nodes	"type": "backend" for Renderers ×5【examples/archify-repo.architecture.json#L52-L55】
security	Policy enforcement or validation	"type": "security" for JSON Schema【examples/archify-repo.architecture.json#L44-L47】
cloud	Persistent cloud artifacts	"type": "cloud" for HTML Artifact【examples/archify-repo.architecture.json#L78-L81】
messagebus	Stream-like data carriers	"type": "messagebus" for JSON IR【examples/archify-repo.architecture.json#L36-L39】

The renderer in experiments/visual-evolution/prototype.html reads these type values and applies corresponding CSS custom properties such as --frontend-fill or --security-stroke. You do not need to write CSS—just declare the type in your JSON.

{
  "id": "schema-validator",
  "type": "security",
  "label": "JSON Schema"
}

Working with Connection Variants

Connection variants control how edges render between nodes. Unlike component types, which are fixed semantic categories, variants express styling intent for specific relationships.

Variant	Visual Effect	Typical Use Case
emphasis	Solid thick line	Primary data flow paths
security	Solid line with padlock indicator	Security-critical connections
dashed	Dashed line	Auxiliary or optional flows
(default)	Thin solid line	Standard connections

The archify-repo.architecture.json file demonstrates all three explicit variants:

{
  "from": "agent-hosts",
  "to": "json-ir",
  "variant": "emphasis"
}

{
  "from": "json-ir",
  "to": "json-schema",
  "variant": "security"
}

{
  "from": "html-artifact",
  "to": "archify-zip",
  "variant": "dashed"
}

Source: 【examples/archify-repo.architecture.json#L22-L31】 and 【examples/archify-repo.architecture.json#L62-L66】

Controlling Orthogonal Routing with Side Anchors

For precise layout control, combine variants with fromSide and toSide properties. These dictate which edge of a node the connection attaches to when using orthogonal routing.

{
  "from": "agents",
  "to": "skill",
  "fromSide": "top",
  "toSide": "bottom"
}

Source: 【examples/archify-repo.architecture.json#L15-L20】

Toggling Visual Variants in the Prototype UI

The prototype.html demonstration includes a runtime variant switcher that cycles through predefined view modes. This is implemented in JavaScript at lines 322-349:

// Build the list of available variants
var variants = [
  { key: "signal",    name: "Signal View" },
  { key: "blueprint", name: "Blueprint View" },
  { key: "ember",     name: "Ember View" }
];

// Initialise from URL
var params = new URLSearchParams(window.location.search);
var selected = params.get('variant');
var index = Math.max(0, variants.findIndex(v => v.key === selected));

// Update UI and URL when the user clicks the arrows
function setVariant(next) {
  var nextIndex = (index + next + variants.length) % variants.length;
  var variant = variants[nextIndex];
  document.documentElement.setAttribute('data-prototype-variant', variant.key);
  label.innerHTML = '<span class="prototype-key">'
    + (nextIndex + 1) + '/' + variants.length + '</span> — ' + variant.name;
  params.set('variant', variant.key);
  history.replaceState(null, '', '?' + params);
}

Source: experiments/visual-evolution/prototype.html【experiments/visual-evolution/prototype.html#L322-L349】

Access alternative views by appending ?variant=blueprint or ?variant=ember to the prototype URL. The chosen variant writes to document.documentElement as data-prototype-variant, which CSS selectors use to show, hide, or recolor diagram layers.

Complete Architecture File Example

{
  "components": [
    { "id": "user",      "type": "external",   "label": "End User" },
    { "id": "web-ui",    "type": "frontend",   "label": "React App" },
    { "id": "api",       "type": "backend",    "label": "REST API" },
    { "id": "validator", "type": "security",   "label": "JWT Check" },
    { "id": "database",  "type": "cloud",      "label": "PostgreSQL" },
    { "id": "events",    "type": "messagebus", "label": "Event Stream" }
  ],
  "connections": [
    { "from": "user",      "to": "web-ui",    "variant": "emphasis" },
    { "from": "web-ui",    "to": "api",       "variant": "emphasis" },
    { "from": "api",       "to": "validator", "variant": "security" },
    { "from": "validator", "to": "database",  "variant": "security" },
    { "from": "api",       "to": "events",    "variant": "dashed" }
  ]
}

Save this as my-system.architecture.json and process it through Archify's rendering pipeline. The output HTML will automatically apply type-based node styling and variant-based edge styling.

Summary

• Six component types (external, frontend, backend, security, cloud, messagebus) drive node appearance through CSS custom properties
• Three connection variants (emphasis, security, dashed) plus default styling control edge rendering
• fromSide/toSide properties enable precise orthogonal routing when needed
• Runtime variant switching in prototype.html supports multiple visual interpretations of the same architecture data
• All styling is declarative—no CSS or JavaScript required in your architecture files

Frequently Asked Questions

What happens if I use an unknown component type?

Archify falls back to default styling. The renderer in prototype.html applies a neutral color scheme when no matching CSS variable exists for the declared type. For predictable results, stick to the six documented types or extend the CSS in your custom renderer.

Can I define custom connection variants beyond emphasis, security, and dashed?

The core engine accepts any string value for variant, but the built-in prototype.html only provides CSS rules for the three documented variants. To add custom variants, extend the CSS in your renderer template with classes like .connection-customname and reference them in your JSON.

How do I make the prototype UI default to a specific variant?

Append ?variant=KEY to the URL, where KEY matches an entry in the variants array defined in prototype.html lines 324-328. The initialization code at lines 332-333 reads this parameter and sets the active view accordingly.

Where does the actual rendering logic live?

The visual prototype at experiments/visual-evolution/prototype.html contains the reference implementation. It parses *.architecture.json files, maps type values to CSS variables, and applies variant classes to connection SVG elements. For production use, adapt this logic into your target rendering environment.

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