Archify Authoring Contract for Relationships and Routes: Complete Technical Guide

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, 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

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

{
  "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, 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 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 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	Privacy scaffold; contains the explicit guarantee that no relationship or source data is server-recorded
examples/mco-showcase/mco-runtime.html	Runtime implementation of relationship lenses and route overlay rendering
docs/research-visual-evolution-round-48.md	Design documentation describing the "Current Archify contract" model
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, examples/mco-showcase/mco-runtime.html, docs/research-visual-evolution-round-48.md, 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, 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 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 file documents the current contract model, suggesting active iteration without breaking backward compatibility for required fields.

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