How to Define Connections Between Components in Archify: A Complete JSON Schema Guide

In Archify, you define connections between components by adding objects to the connections array in your Architecture diagram JSON, where each object specifies from and to properties referencing component IDs along with optional styling and routing configuration.

The tt-a1i/archify repository uses a declarative JSON format to model system architectures. Defining connections between components requires understanding the structured schema that controls how lines are drawn, labeled, and routed between nodes in your diagrams.

The Connections Array Structure

Every Architecture diagram in Archify contains a top-level connections array that operates alongside the components array. According to the source code in archify/schemas/architecture.schema.json, each connection object links two components by their unique identifiers and supports extensive customization for visual presentation.

The minimal required properties for any connection are:

• from – The ID of the source component (string, required)
• to – The ID of the target component (string, required)

All other properties are optional and control the visual representation of the connector line.

Essential Connection Properties

When you define connections between components in Archify, you can leverage several property categories to control appearance and behavior.

Identification and Labeling

Beyond the required endpoints, connections support descriptive metadata:

• label – Text displayed directly on the connector line
• variant – Predefined style classes including emphasis, security, or dashed
• width – Line thickness as a number (minimum 0.5)

Anchor Point Control

Control exactly where lines attach to component boxes using side-specific properties:

• fromSide – Attachment side on the source (left, right, top, bottom)
• toSide – Attachment side on the target (left, right, top, bottom)

Routing Configuration

The route property determines how the line travels between components:

• auto – Default automatic routing
• straight – Direct line between points
• orthogonal-h – Horizontal-first orthogonal path
• orthogonal-v – Vertical-first orthogonal path

For custom paths, the via property accepts an array of {x, y} coordinate objects defining intermediate waypoints.

Basic Connection Example

The following example from the Archify codebase demonstrates a simple API connection between a frontend and backend component:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Flow" },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Frontend", "pos": [100, 200], "size": [120, 60] },
    { "id": "backend",  "type": "backend",  "label": "Backend",  "pos": [300, 200], "size": [120, 60] }
  ],
  "connections": [
    {
      "from": "frontend",
      "to": "backend",
      "label": "API Call",
      "variant": "emphasis",
      "fromSide": "right",
      "toSide": "left",
      "route": "orthogonal-h"
    }
  ]
}

This configuration creates a highlighted horizontal connector attaching to the right side of the frontend and left side of the backend, as implemented in examples/archify-repo.architecture.json.

Advanced Connection Patterns

Multi-Point Routing with Via

For complex architectures requiring lines that navigate around obstacles, define explicit waypoints:

{
  "from": "user",
  "to": "database",
  "route": "straight",
  "via": [
    { "x": 200, "y": 300 },
    { "x": 200, "y": 500 }
  ]
}

The via array injects intermediate coordinates between the source and destination anchors, overriding automatic routing algorithms.

Precise Label Positioning

Fine-tune label placement using coordinate offsets:

• labelAt – Position along the line (0.0 to 1.0)
• labelDx – Horizontal offset in pixels
• labelDy – Vertical offset in pixels
• labelSegment – Which line segment carries the label (for multi-segment routes)

Styling Variants and Security Connections

Archify supports semantic styling through the variant property. As defined in the Architecture schema, available options include:

• emphasis – High-visibility styling for critical paths
• security – Denotes authentication or secure data flows
• dashed – Indicates optional, planned, or asynchronous connections

The example diagram in examples/archify-repo.architecture.json demonstrates these patterns by connecting the user component to agents with the emphasis variant, then linking agents to ir with both a label and the same variant styling.

Summary

• Define connections by adding objects to the connections array in your Architecture JSON
• Reference components using the required from and to ID properties
• Control attachment points with fromSide and toSide (left, right, top, bottom)
• Select routing behavior via the route property (auto, straight, orthogonal-h, orthogonal-v)
• Create custom paths by providing coordinate objects in the via array
• Apply semantic styling using variant values like emphasis or security
• Validate schemas against archify/schemas/architecture.schema.json in the tt-a1i/archify repository

Frequently Asked Questions

What is the difference between route types in Archify?

The route property in archify/schemas/architecture.schema.json supports four modes: auto lets the renderer choose the path, straight draws a direct line, while orthogonal-h and orthogonal-v force right-angle paths that prioritize horizontal or vertical segments respectively. Use orthogonal routes for clean flowcharts and straight routes for direct relationships.

How do I create curved or custom paths between components?

While Archify does not support Bezier curves directly, you achieve custom routing using the via array property. Each element in this array must be an object with x and y coordinates that force the connector to pass through specific points between the source and target components.

Can I style connections differently for security versus data flow?

Yes. Set the variant property to security for authentication flows, emphasis for critical system interactions, or dashed for planned or optional connections. These variants reference predefined styles in the Archify renderer that apply distinct colors, line patterns, or thickness automatically.

Where is the connection schema validated in the codebase?

The JSON Schema defining all connection properties resides in archify/schemas/architecture.schema.json within the tt-a1i/archify repository. This schema validates that from and to reference existing component IDs and enforces constraints on properties like width (minimum 0.5) and enumerated values for route, fromSide, and toSide.

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