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

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 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): Reads the type=sequence query parameter and injects the JSON IR into the rendering pipeline.
• Sequence Template (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 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) 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.

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

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

{"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 with the appropriate query parameters:

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

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

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

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

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 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, and requires no additional build steps.

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