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

> Learn how to generate sequence diagrams with Archify from JSON files. This guide walks you through the process step by step, enabling easy visualization of your system architecture.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) — JSON Schema defining all valid fields
- `examples/` — Default directory for diagram source files
- [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/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.

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

```json
{
  "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:

```bash
npx archify render my-sequence.sequence.json

```

This command:

1. Reads and parses the JSON
2. Validates against [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) in your browser for a visual workflow:

1. Paste JSON directly into the editor, or
2. Drop a [`.sequence.json`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss-request.html) and was auto-generated by Archify.

Another pattern example, [`archify/examples/async-job-roundtrip.sequence.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) ensures correct structure before rendering
- **Two interfaces**: CLI (`npx archify render`) for automation, web UI ([`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/cache-miss-request.sequence.json) (cache layer interactions) and [`archify/examples/async-job-roundtrip.sequence.json`](https://github.com/tt-a1i/archify/blob/main/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/`.