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

> Learn to define connections between components in Archify using its JSON schema. Map component IDs with from and to properties to visually represent relationships in your diagrams.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`.