# How to Create Sequence Diagrams with Timing and Async Traces in Archify

> Learn to create sequence diagrams with timing and async traces in Archify. Define JSON IR with durations and async roles. Generate animated SVG diagrams easily.

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

---

**To create sequence diagrams with timing and async traces in Archify, define a JSON IR (intermediate representation) containing participants, edges with `duration` values for timing control, and `semanticRole: "async"` for asynchronous hops, then load it via [`start.html`](https://github.com/tt-a1i/archify/blob/main/start.html) or the CLI to generate animated, exportable SVG diagrams.**

Archify's **Sequence** renderer visualizes ordered call-chains, request lifecycles, and asynchronous operations through a JSON-based intermediate representation. This guide covers how to leverage the `duration` property for latency-proportional animations and the `semanticRole` field to style async traces, using implementation details from the `tt-a1i/archify` repository.

## Architecture of the Sequence Renderer

The sequence diagram system in Archify consists of several coordinated components that transform JSON definitions into interactive visualizations:

- **UI Entry Point** ([`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html)): Reads the `type=sequence` query parameter and injects the JSON IR into the rendering pipeline.
- **Sequence Template** ([`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html)): Contains UI controls, async helper functions, and copy-prompt logic for the interactive viewer.
- **IR Builder**: JSON source files like [`docs/gallery/sources/async-job-roundtrip.sequence.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/async-job-roundtrip.sequence.json) define participants, edges, timings, and semantic roles.
- **Renderer** (`scripts/build-gallery.mjs`): Maps `type: "sequence"` to output HTML, parsing the IR to create SVG nodes, apply timing-based animations, and render async styling.
- **Export & Interaction**: The generated HTML (e.g., [`docs/gallery/artifacts/async-job-roundtrip.sequence.html`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/async-job-roundtrip.sequence.html)) embeds zoom controls, radar navigation, chapter selection, and export capabilities for SVG, PNG, and WebM formats.

## Defining the JSON Intermediate Representation

Archify consumes a structured JSON IR that describes the entire diagram topology. The renderer uses this file to calculate layout, timing, and visual styling.

### Configuring Participants and Edges

Define each actor in the `participants` array with unique IDs and display labels. The `edges` array specifies message flow between participants using `from` and `to` references.

```json
{
  "type": "sequence",
  "participants": [
    {"id": "frontend", "label": "Frontend"},
    {"id": "api", "label": "API"},
    {"id": "cache", "label": "Redis"},
    {"id": "db", "label": "Database"},
    {"id": "trace", "label": "Trace", "sublabel": "async event"}
  ],
  "edges": [
    {"from": "frontend", "to": "api", "label": "GET /items", "duration": 120},
    {"from": "api", "to": "cache", "label": "read-through", "duration": 30},
    {"from": "cache", "to": "db", "label": "miss → fetch", "duration": 150}
  ]
}

```

### Controlling Timing with Duration Values

The `duration` field (in milliseconds) controls the visual length of each edge and its animation timing. The renderer treats the longest edge as the baseline (approximately **780ms** in the reference implementation), scaling all other edges proportionally to create a "story beat" animation that reflects actual latency when played.

```json
{"from": "db", "to": "api", "label": "result", "duration": 80}

```

### Marking Async Traces with Semantic Roles

To distinguish asynchronous operations from synchronous calls, set `"semanticRole": "async"` on any edge. The renderer applies a distinct dashed stroke style and appends "async event" or "async trace" annotations to these edges, as seen in the Cache-miss example within the source gallery.

```json
{"from": "api", "to": "trace", "label": "async event", "semanticRole": "async", "duration": 0}

```

## Rendering and Interacting with Diagrams

Once the JSON IR is defined, you can render it through the browser-based UI or the command-line interface.

### Loading via Browser or CLI

Open [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) with the appropriate query parameters:

```

start.html?type=sequence&source=your-diagram.json

```

Alternatively, use the Archify CLI to launch the viewer directly:

```bash
npx archify start --type sequence --source docs/gallery/sources/async-job-roundtrip.sequence.json

```

### Interactive Controls and Animation

The rendered HTML provides keyboard shortcuts for navigation and playback:

- **P**: Play/pause the animated timeline
- **R**: Toggle route view
- **M**: Toggle radar view
- **[** / **]**: Navigate between views or chapters

The animation progresses through each edge sequentially, with the duration of each step proportional to the `duration` value specified in the JSON IR.

### Exporting Diagrams

Press **E** in the interactive viewer to export the sequence diagram in multiple formats. The export functionality supports:

- **SVG** for vector embedding
- **PNG** for raster images
- **WebM** for video capture of the animation

The generated HTML artifacts, such as [`docs/gallery/artifacts/async-job-roundtrip.sequence.html`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/async-job-roundtrip.sequence.html), include these export capabilities natively.

## Complete Working Example

The following example reproduces the *Async Job Round-trip* scenario from the Archify gallery, demonstrating API requests, cache fallbacks, and async tracing:

```json
{
  "type": "sequence",
  "participants": [
    {"id": "frontend", "label": "Frontend"},
    {"id": "api", "label": "API"},
    {"id": "cache", "label": "Redis"},
    {"id": "db", "label": "Database"},
    {"id": "trace", "label": "Trace", "sublabel": "async event"}
  ],
  "edges": [
    {"from": "frontend", "to": "api", "label": "GET /items", "duration": 120},
    {"from": "api", "to": "cache", "label": "read-through", "duration": 30},
    {"from": "cache", "to": "db", "label": "miss → fetch", "duration": 150},
    {"from": "db", "to": "api", "label": "result", "duration": 80},
    {"from": "api", "to": "frontend", "label": "response", "duration": 20},
    {"from": "api", "to": "trace", "label": "async event", "semanticRole": "async", "duration": 0}
  ]
}

```

To view this specific example:

```bash
git clone https://github.com/tt-a1i/archify.git
cd archify
open docs/gallery/artifacts/async-job-roundtrip.sequence.html

```

The rendered output shows the API-to-Trace edge as a dashed line labeled "async event" at y-position 111 in the SVG, distinguishing it from the solid synchronous call lines.

## Summary

- Archify consumes JSON IR files with `type: "sequence"` to render interactive sequence diagrams
- Use the `duration` property (in milliseconds) on edges to control timing and animation length proportionally
- Apply `"semanticRole": "async"` to render asynchronous traces with dashed lines and distinct labels
- Load diagrams via `start.html?type=sequence&source=file.json` or the `npx archify start --type sequence` CLI command
- Export final diagrams as SVG, PNG, or WebM using the **E** shortcut in the interactive viewer

## Frequently Asked Questions

### What JSON structure is required to define a sequence diagram in Archify?

Archify requires a JSON IR containing `type: "sequence"`, a `participants` array with `id` and `label` fields, and an `edges` array specifying `from`, `to`, `label`, optional `duration` (milliseconds), and optional `semanticRole` properties. The repository's [`docs/gallery/sources/async-job-roundtrip.sequence.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/async-job-roundtrip.sequence.json) provides a complete reference implementation.

### How does Archify distinguish asynchronous traces from synchronous calls?

Edges marked with `"semanticRole": "async"` in the JSON IR are rendered with a distinct dashed stroke style and optional "async event" labels, as implemented in `scripts/build-gallery.mjs`. This visual differentiation allows viewers to identify non-blocking operations immediately.

### What controls the timing and animation speed in Archify sequence diagrams?

The `duration` property on each edge determines the visual length of the animated "story beat." The renderer calculates the longest edge duration as a baseline (approximately 780ms) and scales all other edges proportionally, creating a timeline animation that reflects the relative latency of each operation.

### How do I export a sequence diagram after rendering it in Archify?

Press **E** in the interactive viewer or use the export button in the UI to download the diagram as SVG, PNG, or WebM. The export functionality is embedded in the generated HTML artifacts, such as [`docs/gallery/artifacts/async-job-roundtrip.sequence.html`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/async-job-roundtrip.sequence.html), and requires no additional build steps.