How to Generate a Sequence Diagram with Archify: Complete Step-by-Step Guide

Archify generates sequence diagrams from structured JSON files by validating them against a sequence schema and rendering through the D2 engine, producing exportable PNG, SVG, or WebM outputs.

Archify is an open-source diagramming tool that transforms JSON descriptions into polished architecture visuals. To create a sequence diagram with Archify, you supply a JSON file following the sequence schema, then render it via the web UI or CLI. The result shows participants as vertical lifelines and messages as ordered horizontal arrows—perfect for documenting system interactions.

Prerequisites and Project Structure

Before generating diagrams, ensure you have Archify installed. The CLI entry point is declared in archify/package.json as archify render ….

Archify watches JSON files in the examples/ folder or any path you provide. Key files to know:

• archify/schemas/sequence.schema.json — JSON Schema defining all valid fields
• examples/ — Default directory for diagram source files
• docs/start.html — Interactive web UI for drag-and-drop rendering

Step 1: Create a Valid Sequence JSON File

Archify requires a specific structure. The top-level object must contain "type": "sequence" plus participants and messages arrays.

{
  "type": "sequence",
  "participants": [
    { "id": "client", "label": "Client" },
    { "id": "service", "label": "Service" },
    { "id": "db", "label": "Database" }
  ],
  "messages": [
    { "from": "client", "to": "service", "label": "GET /orders" },
    { "from": "service", "to": "db", "label": "SELECT * FROM orders" },
    { "from": "db", "to": "service", "label": "Result set" },
    { "from": "service", "to": "client", "label": "200 OK" }
  ]
}

Save this as my-sequence.sequence.json. The "type" field tells Archify which renderer to invoke.

Step 2: Define Participants with IDs and Labels

Each participant in the participants array becomes a vertical lifeline. Required fields:

• id — unique identifier referenced by messages
• label — human-readable display name

Optional styling: add color or icon for visual distinction.

{
  "id": "service",
  "label": "Order Service",
  "color": "#4A90D9"
}

Step 3: List Messages in Chronological Order

The messages array determines the horizontal flow. Each message requires:

• from — participant id sending the message
• to — participant id receiving the message
• label — text shown on the arrow

Optional styling: bend or stretch adjust arrow curvature.

Self-messages: Set "from" and "to" to the same id. Archify renders this as a self-loop arrow.

Step 4: Render with the Archify CLI

Validate and generate your diagram using:

npx archify render my-sequence.sequence.json

This command:

1. Reads and parses the JSON
2. Validates against archify/schemas/sequence.schema.json
3. Invokes the D2 rendering engine
4. Outputs SVG/HTML to the configured destination (default: out.svg)

For batch processing or CI/CD pipelines, the CLI supports output redirection and custom paths.

Step 5: Use the Web UI for Interactive Generation

Open docs/start.html in your browser for a visual workflow:

1. Paste JSON directly into the editor, or
2. Drop a .sequence.json file onto the upload zone
3. Preview renders instantly
4. Click Download PNG, SVG, or WebM to export

The web UI performs the same schema validation as the CLI, surfacing errors with field-level detail.

Real-World Example: Cache-Miss Request

The repository includes a production-ready reference in archify/examples/cache-miss-request.sequence.json. This demonstrates:

• Multiple participants with custom styling
• Complex message flows including error paths
• Proper chronological ordering for readability

The rendered output lives at examples/sequence-cache-miss-request.html and was auto-generated by Archify.

Another pattern example, archify/examples/async-job-roundtrip.sequence.json, shows asynchronous request-response flows with delayed returns.

Validation and Troubleshooting

Archify strictly validates input against sequence.schema.json. Common errors and fixes:

Error	Cause	Solution
Missing "type" field	Schema mismatch	Add "type": "sequence" to root
Unknown participant id in message	Typo in from/to	Ensure id matches participants array
Validation fails silently	JSON syntax error	Run through jq or linter first
Messages out of order	Logical sequencing	Re-sort messages array chronologically

Export and Embedding Options

Once rendered, diagrams are available in three formats:

• PNG — raster format for presentations and docs
• SVG — scalable, editable vector for web embedding
• WebM — animated format for video documentation

The CLI writes SVG to disk; the web UI provides one-click downloads for all formats.

Summary

• Archify generates sequence diagrams from JSON files with "type": "sequence" and properly structured participants and messages arrays
• Chronological ordering in the messages array determines visual flow
• Schema validation at archify/schemas/sequence.schema.json ensures correct structure before rendering
• Two interfaces: CLI (npx archify render) for automation, web UI (docs/start.html) for interactive work
• Three export formats: PNG, SVG, and WebM for different use cases
• Self-messages and styling options (color, bend, stretch) customize appearance
• Reference examples in archify/examples/ demonstrate production patterns

Frequently Asked Questions

What JSON schema does Archify use for sequence diagram validation?

Archify validates all sequence diagram inputs against archify/schemas/sequence.schema.json. This schema defines required fields (type, participants, messages), participant structure (id, label, optional color/icon), and message structure (from, to, label, optional styling). If validation fails, Archify emits descriptive errors indicating which fields are missing or malformed.

Can I generate sequence diagrams without using the command line?

Yes. Open docs/start.html in any modern browser to use Archify's interactive web UI. You can paste JSON directly into the editor or drag-and-drop a .sequence.json file. The UI renders previews instantly and provides download buttons for PNG, SVG, and WebM exports—no terminal required.

How do I show a function calling itself in an Archify sequence diagram?

Set both "from" and "to" to the same participant id in your message object. Archify renders this as a self-loop arrow on that participant's lifeline. Example: { "from": "service", "to": "service", "label": "internal retry" }.

Where can I find complete working examples of Archify sequence diagrams?

The repository contains two fully-documented examples: archify/examples/cache-miss-request.sequence.json (cache layer interactions) and archify/examples/async-job-roundtrip.sequence.json (asynchronous patterns). Both include styling, multiple participants, and realistic message flows. The rendered HTML outputs are also checked in under examples/.

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