# How Archify Handles Sequence Diagrams: JSON Schema to SVG Rendering

> Discover how Archify handles sequence diagrams by validating JSON input against its schema and rendering SVG with custom layouts and trace animations. Learn more now!

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-29

---

**Archify processes sequence diagrams through a schema-first pipeline that validates JSON input against [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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)](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`](https://github.com/tt-a1i/archify/blob/main/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)](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html). The core `Archify.renderSequence()` function transforms validated JSON into interactive SVG.

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

```javascript
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)](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)](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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json). These files use the [`.sequence.json`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/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.