# Archify Authoring Contract for Relationships and Routes: Complete Technical Guide

> Understand the Archify authoring contract for relationships and routes. This JSON payload defines edges and paths for front-end rendering without server trips. Learn more in our technical guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-10

---

**The Archify authoring contract for relationships and routes is a JSON payload that specifies directed edges between nodes and ordered paths of those edges, serving as the single source of truth for front-end rendering without any server round-trips.**

The `tt-a1i/archify` repository implements a privacy-first diagramming system where all graph structure—including **relationships** (edges) and **routes** (paths)—is defined through a static data contract. This contract is authored at design time, embedded directly into the page, and never transmitted back to any server.

## What Is the Archify Authoring Contract?

The authoring contract is a pure-data JSON structure that fully describes a diagram's topology. It contains three primary elements:

- **Nodes** – Visual anchors with `id`, `label`, and `type`
- **Relationships** – Directed edges connecting source and target nodes
- **Routes** – Higher-level paths composed as ordered lists of relationship IDs

The contract is deliberately stateless and executable-free. According to [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), Archify explicitly guarantees that *"no repository path, node, relationship, or source JSON is recorded"* when diagrams are shared or embedded.

## Relationship Contract Structure

Relationships in Archify are directed edges with mandatory identity and endpoint fields.

### Required Fields

| Field | Description |
|-------|-------------|
| `id` | Stable unique identifier for the edge |
| `source` | ID of the originating node |
| `target` | ID of the destination node |

### Optional Extension Fields

- `label` – Semantic description (e.g., `"depends-on"`)
- `type` – Edge classification (e.g., `"directed"`)
- `style` – Visual properties including `stroke` and `strokeDasharray`
- `metadata` – Author-defined annotations (e.g., `{"origin": "author"}`)

### Relationship Contract Example

```json
{
  "id": "rel-42",
  "source": "node-7",
  "target": "node-12",
  "label": "depends-on",
  "type": "directed",
  "style": {
    "stroke": "var(--database-stroke)",
    "strokeDasharray": "4 2"
  },
  "metadata": { "origin": "author" }
}

```

The contract guarantees **directional integrity**: every relationship resolves unambiguously from `source` to `target` via stable IDs. The rendering engine in [`examples/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/examples/mco-showcase/mco-runtime.html) implements this through `.relationship-lens*` CSS classes that apply the specified visual styles.

## Route Contract Structure

Routes represent multi-step paths through the graph, built by referencing relationship IDs in traversal order.

### Required Fields

| Field | Description |
|-------|-------------|
| `id` | Stable unique identifier for the route |
| `segments` | Ordered array of relationship IDs composing the path |

### Optional Extension Fields

- `label` – Human-readable path name (e.g., `"user-signup-flow"`)
- `style` – Route-level visual overrides
- `metadata` – Purpose annotations (e.g., `{"purpose": "guidedStory"}`)

### Route Contract Example

```json
{
  "id": "route-5",
  "segments": ["rel-10", "rel-34", "rel-42"],
  "label": "user-signup-flow",
  "style": { "color": "var(--frontend-stroke)" },
  "metadata": { "purpose": "guidedStory" }
}

```

The route contract establishes **indirection**: routes reference relationships by ID, and the rendering engine resolves each ID back to its concrete edge definition. This allows the same relationship to participate in multiple routes without data duplication. As implemented in [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html), route overlays follow the ordered `segments` list to highlight sequences for the guided-story engine.

## Contract Consumption Pipeline

The Archify authoring contract flows through three stages from creation to display:

1. **Authoring UI** – Builds the JSON contract in-memory as users create diagrams; validates unique IDs and node existence client-side before serialization

2. **Embedding / Sharing** – Serializes to a `data-json` attribute or URL-encoded payload; [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) confirms no repository metadata leaks

3. **Rendering** – Parses the contract, generates SVG elements for nodes and relationships, and constructs route overlays by traversing `segments`

The [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) file demonstrates this complete pipeline, showing concrete JSON contract loading and rendering implementation.

## Key Source Files for the Authoring Contract

| File | Role |
|------|------|
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | Privacy scaffold; contains the explicit guarantee that no relationship or source data is server-recorded |
| [`examples/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/examples/mco-showcase/mco-runtime.html) | Runtime implementation of relationship lenses and route overlay rendering |
| [`docs/research-visual-evolution-round-48.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-48.md) | Design documentation describing the "Current Archify contract" model |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Full working demo of contract parsing and diagram rendering |

## Summary

- The **Archify authoring contract** is a pure-JSON, server-agnostic format for diagram topology
- **Relationships** require `id`, `source`, `target` and support styling and metadata extensions
- **Routes** compose ordered `segments` of relationship IDs for path-based visualizations
- All validation and rendering occurs client-side; no contract data returns to servers
- Source paths: [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), [`examples/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/examples/mco-showcase/mco-runtime.html), [`docs/research-visual-evolution-round-48.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-48.md), [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html)

## Frequently Asked Questions

### What makes the Archify authoring contract "privacy-first"?

The contract never includes repository paths, source file locations, or server-side identifiers. Per [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), Archify guarantees that *"no repository path, node, relationship, or source JSON is recorded"*—diagrams embed as pure data that renders without network dependencies after initial load.

### Can routes exist without referencing valid relationships?

No. The rendering engine resolves each segment ID against the relationship contract at parse time. Missing or malformed relationship references fail client-side validation before SVG generation, ensuring render-time consistency.

### How are relationship styles applied in the rendering engine?

The [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html) implementation maps contract `style` properties to CSS custom properties (e.g., `var(--database-stroke)`) and applies them through `.relationship-lens*` classes. Stroke patterns like `"strokeDasharray": "4 2"` render as SVG path attributes.

### Is the authoring contract versioned or extensible?

While the core structure (nodes, relationships, routes) is fixed, the `metadata` field in all three elements provides open extension points. The [`docs/research-visual-evolution-round-48.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-48.md) file documents the current contract model, suggesting active iteration without breaking backward compatibility for required fields.