Archify Sequence Diagrams: Complete Guide to Key Fields and JSON Schema

Archify sequence diagrams require five primary fields—participants, messages, groups, annotations, and metadata—defined in archify/schemas/sequence.schema.json to render deterministic, D2-compatible visualizations.

Archify is an open-source diagramming framework hosted at tt-a1i/archify that generates architectural visualizations from structured JSON. Understanding the exact field specifications for Archify sequence diagrams ensures your diagrams validate against the canonical schema and render correctly through the sequence diagram engine.

Core Schema Fields for Archify Sequence Diagrams

The schema at archify/schemas/sequence.schema.json defines the data structure consumed by the rendering pipeline. Every sequence diagram must include participants and messages, while groups, annotations, and metadata remain optional.

Participants Array

The participants field is a required array of objects defining the actors or components displayed horizontally across the diagram. Each participant object requires:

• id: A unique string identifier used as a reference in message routing
• label: Human-readable text rendered above the lifeline
• Optional styling: color, icon, or other visual attributes

The order of participants in this array determines their left-to-right placement on the canvas.

Messages Array

The messages field is a required ordered array defining the vertical flow of communication. Each message object contains:

• from: String ID of the sender participant
• to: String ID of the receiver participant (matches from for self-messages)
• label: Text displayed on the arrow connector
• async: Boolean indicating dashed asynchronous arrows when true
• response: Boolean enabling return-message styling when true
• bend / stretch: Numeric layout hints typically set to 0 and 1.0 to enforce strict horizontal message lines without curvature

According to the source code in archify/renderers/sequence/render-sequence.mjs, these fields ensure zero-bend horizontal sequencing compatible with D2 rendering rules.

Groups Array (Optional)

The groups field defines logical containers for participants or message phases. Each group includes:

• id: Unique identifier
• label: Display name for the container
• members: Array of participant IDs belonging to the group
• Optional styling: Visual properties for borders or backgrounds

Groups effectively model lifelines, activation bars, or higher-level architectural phases without altering the underlying message sequence.

Annotations Array (Optional)

The annotations field attaches explanatory notes to specific diagram points. Each annotation specifies:

• target: Reference to a message ID or participant ID
• text: The note content
• position: Placement hints such as "left", "right", or "center"

These annotations render as callouts or footnotes without disrupting the vertical message flow.

Metadata Object (Optional)

The metadata field stores repository-level provenance information consumed by Archify tooling but ignored by the layout engine. Standard properties include:

• version: Schema or diagram version string
• author: Creator identifier
• description: Free-form documentation text

How the Fields Interact in the Rendering Pipeline

The renderSequence function in archify/renderers/sequence/render-sequence.mjs processes these fields through a deterministic layout engine.

Participants establish the horizontal axis. The renderer calculates fixed X-coordinates based on array index, ensuring consistent left-to-right positioning regardless of message complexity.

Messages drive the vertical timeline. The renderer processes the messages array sequentially, drawing arrows from source to target coordinates. Self-messages render as curved arrows when from equals to, while standard messages remain strictly horizontal per the constraints documented in docs/research-visual-evolution-round-46.md.

Groups wrap around participant lifelines visually but do not reorder the underlying sequence. The renderer uses the members array to determine bounding boxes without altering message routing.

Practical Implementation Examples

Minimal Valid Sequence Diagram

Create a JSON file following the schema structure:

{
  "participants": [
    { "id": "client", "label": "Client", "color": "#4A90E2" },
    { "id": "server", "label": "API Server", "color": "#7ED321" }
  ],
  "messages": [
    { "from": "client", "to": "server", "label": "GET /items", "async": false },
    { "from": "server", "to": "client", "label": "200 OK", "response": true }
  ],
  "groups": [
    {
      "id": "auth_flow",
      "label": "Authentication Phase",
      "members": ["client", "server"]
    }
  ],
  "annotations": [
    { "target": "msg1", "text": "Initial request", "position": "right" }
  ],
  "metadata": { "version": "1.0", "author": "Jane Doe" }
}

Rendering with JavaScript

Import the sequence renderer to generate SVG output:

import { renderSequence } from '@archify/renderers/sequence';

const diagramSpec = /* load JSON from above */;
const svgElement = renderSequence(diagramSpec);
document.getElementById('canvas').appendChild(svgElement);

The renderSequence function validates the input against archify/schemas/sequence.schema.json before constructing the DOM nodes, throwing validation errors for missing required fields like participants or malformed message references.

Key Source Files

Understanding the implementation requires examining these specific files in the tt-a1i/archify repository:

• archify/schemas/sequence.schema.json: Canonical JSON schema defining all field types, constraints, and required properties
• archify/renderers/sequence/render-sequence.mjs: Core rendering logic implementing the layout engine and D2 SVG generation
• archify/references/delivery-contract.md: Cross-renderer specifications detailing how sequence diagrams share common field patterns with architecture, workflow, and dataflow diagrams
• docs/research-visual-evolution-round-46.md: Design rationale for zero-bend message constraints and lifeline rendering invariants

Summary

• Required fields: Every Archify sequence diagram must include participants and messages arrays defined in archify/schemas/sequence.schema.json
• Layout determinism: The messages array order controls vertical sequencing, while participants array order controls horizontal positioning
• Optional enhancements: Use groups for visual containment, annotations for documentation, and metadata for versioning
• Rendering entry point: Call renderSequence() from archify/renderers/sequence/render-sequence.mjs after validating your JSON structure
• Strict constraints: Keep bend at 0 and stretch at 1.0 to maintain horizontal message lines compatible with D2 output

Frequently Asked Questions

What happens if I omit the participants field in an Archify sequence diagram?

The schema validation will fail. According to archify/schemas/sequence.schema.json, participants is a required array that defines the horizontal axis of the diagram. The renderSequence function in archify/renderers/sequence/render-sequence.mjs expects this field to map message from and to references to coordinate positions. Without it, the renderer cannot calculate lifeline placements or route arrows.

How do I create a self-message in Archify sequence diagrams?

Set the from and to fields to the same participant ID within a message object. When renderSequence detects matching identifiers, it renders a curved arrow returning to the same lifeline rather than a horizontal line between distinct participants. You can optionally set async: true to render the self-message with a dashed line style.

Can I reorder participants without changing the message flow?

Yes. The visual left-to-right order strictly follows the participants array index order, independent of the messages array sequence. You can rearrange participant IDs in the participants array to adjust horizontal layout without modifying message routing, provided you maintain consistent ID references in the from and to fields.

Where does Archify enforce the zero-bend constraint for message lines?

The constraint is defined in docs/research-visual-evolution-round-46.md and implemented in archify/renderers/sequence/render-sequence.mjs. By default, the renderer sets bend to 0 and stretch to 1.0 for all messages, ensuring strictly horizontal arrow lines that comply with D2 sequence diagram specifications. Manual adjustment of these values may cause validation warnings depending on your schema version.

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