How Archify Handles Sequence Diagrams: JSON Schema to SVG Rendering

Archify processes sequence diagrams through a schema-first pipeline that validates JSON input against sequence.schema.json, then deterministically generates SVG output with configurable layouts, message variants, and step-wise trace animations.

The tt-a1i/archify repository treats sequence diagrams as first-class diagram types distinct from architecture or workflow visualizations. The system enforces strict validation through JSON Schema, enabling precise control over participant positioning, message styling, and animation modes through declarative configuration files.

The Schema-Driven Model

JSON Schema Definition

Every sequence diagram begins with validation against [archify/schemas/sequence.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json). This schema mandates a strict document structure that the renderer consumes to generate visual output.

Required Document Structure

A valid sequence diagram JSON requires these top-level fields:

• schema_version — Currently locked to 1
• diagram_type — Must be the literal string "sequence"
• meta — Contains title, optional subtitle, viewBox coordinates, animation mode, and visual preset
• participants — Ordered array of actors with id, type, label, and optional sublabel or brand
• messages — Chronological list of interactions linking from and to participants with vertical y positioning and style variant
• activations — Optional array defining lifespan bars showing when participants are active
• segments — Optional horizontal headers that group messages into logical phases
• cards — Optional explanatory cards displayed alongside the diagram

Rendering Pipeline and Layout Engine

Coordinate Calculation

The sequence renderer computes horizontal positioning using fixed geometric metrics. Participants render as 86 px boxes separated by 108 px gaps unless column_fit is set to "spread", which enables fluid layout distribution.

Message Variants and Visual Styles

Each message renders as a horizontal line at its prescribed y coordinate. The variant enum determines line styling:

• default — Solid line for standard communication
• emphasis — Bold line highlighting critical paths
• security — Purple-colored line indicating secure channels
• dashed — Dashed line for optional or conditional flows
• return — Thin return-arrow line for response messages

Activation Bars and Lifelines

The renderer draws vertical lifelines for each participant and overlays activation bars using the activations array, where each entry specifies participant, from and to y-coordinates, and type.

Validation and Normalization

When loading a diagram, Archify fetches the JSON, validates it against sequence.schema.json, and normalizes the data by assigning default values for omitted optional fields such as animation or views. This ensures the renderer always receives a complete, valid data structure.

Animation and Export Capabilities

Trace Animation Mode

When meta.animation is set to "trace", the generator creates step-wise animations that reveal messages sequentially rather than displaying the complete diagram immediately. This mode works with focus groups defined in the JSON to highlight specific interaction phases.

Visual Presets and Quality Profiles

The renderer supports four visual presets—classic, signal-flow, blueprint, and editorial—combined with quality profiles (standard or showcase) that control rendering fidelity for documentation or high-resolution presentation exports.

Loading Sequence Diagrams in the UI

Fetch and Render Workflow

The front-end registers a "sequence" renderer via the type-tab button defined in [scripts/start-template.html](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html). The core Archify.renderSequence() function transforms validated JSON into interactive SVG.

async function loadSequenceDiagram(url) {
  const response = await fetch(url);
  const diagram = await response.json();          // validated against sequence.schema.json
  const svg = Archify.renderSequence(diagram);    // core renderer
  document.getElementById('diagram-container').innerHTML = svg;
}

// Example usage:
loadSequenceDiagram('docs/gallery/sources/cache-miss-request.sequence.json');

Gallery Build Integration

Automated Documentation Generation

The build script scripts/build-gallery.mjs processes all source files where type equals "sequence", invokes the same rendering engine used in the UI, and writes static HTML to the gallery folder.

if (source.type === 'sequence') {
  const diagram = await readJson(source.input);
  const html = renderSequenceDiagram(diagram);   // calls the same renderer as the UI
  await writeFile(`gallery/${source.output}`, html);
}

Complete Example: Cache Miss Request

The repository includes a production-ready example at [docs/gallery/sources/cache-miss-request.sequence.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/cache-miss-request.sequence.json) that demonstrates complex multi-participant flows. The rendered output appears in [archify/examples/sequence-cache-miss-request.html](https://github.com/tt-a1i/archify/blob/main/archify/examples/sequence-cache-miss-request.html).

Minimal Sequence Diagram JSON

Create a valid diagram by defining participants and messages following the schema structure:

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "Simple Ping‑Pong",
    "viewBox": [600, 300]
  },
  "participants": [
    { "id": "client", "type": "external", "label": "Client" },
    { "id": "server", "type": "backend", "label": "Server" }
  ],
  "messages": [
    { "from": "client", "to": "server", "y": 120, "label": "PING", "variant": "default" },
    { "from": "server", "to": "client", "y": 180, "label": "PONG", "variant": "return" }
  ],
  "activations": [
    { "participant": "client", "from": 110, "to": 190, "type": "external" },
    { "participant": "server", "from": 130, "to": 170, "type": "backend" }
  ]
}

Save this as simple-ping-pong.sequence.json and load it through the UI or gallery build script. The renderer produces a two-box diagram with activation bars, a solid ping line, and a thin return-arrow pong line.

Summary

• Schema-first approach: Archify validates all sequence diagrams against sequence.schema.json before rendering, ensuring structural integrity.
• Deterministic layout: The renderer uses fixed 86 px boxes with 108 px gaps or spread layouts, calculating coordinates from the y values in message definitions.
• Rich styling system: Five message variants (default, emphasis, security, dashed, return) control visual communication of different interaction types.
• Animation support: Setting animation to "trace" enables step-wise message revelation for interactive documentation.
• Unified pipeline: The same renderSequenceDiagram() function powers both the interactive UI and static gallery generation via build-gallery.mjs.

Frequently Asked Questions

What file format does Archify use for sequence diagrams?

Archify uses strict JSON files that conform to sequence.schema.json. These files use the .sequence.json extension by convention and require schema_version: 1 and diagram_type: "sequence" as top-level fields.

How does Archify position participants in a sequence diagram?

The renderer calculates horizontal positions using fixed metrics—86 px wide participant boxes spaced 108 px apart—unless the column_fit property is set to "spread", which distributes participants evenly across the available viewBox width.

Can sequence diagrams in Archify include animations?

Yes. When the meta.animation field is set to "trace", the renderer generates step-wise animations that reveal messages sequentially. This works with optional segments and focus groups to highlight specific phases of complex interactions.

How do I add a sequence diagram to the Archify gallery?

Place your JSON file in docs/gallery/sources/ and reference it in docs/gallery/manifest.json with "type": "sequence". Running scripts/build-gallery.mjs automatically validates your diagram, renders it to HTML, and outputs it to the gallery folder using the same renderSequenceDiagram() function employed by the interactive UI.

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