# How to Use Archify for Sequence Diagrams: A Complete Guide

> Learn how to use Archify for sequence diagrams. This guide shows you to generate SVG, PNG, JPEG, and WebP diagrams from text or JSON with Archify.

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

---

**Archify renders sequence diagrams from natural language prompts or JSON input, exporting them as SVG, PNG, JPEG, or WebP with dual-theme support.**

Archify is an open-source, browser-based diagram generator that supports five visual languages including **sequence diagrams**. This guide walks through creating request-response flow diagrams using the `tt-a1i/archify` codebase, from launching the editor to embedding production-ready SVGs.

## Opening the Sequence Diagram Editor

Archify uses a URL-driven interface to switch between diagram types. To access the sequence diagram mode directly, open the entry page with the `type=sequence` query parameter.

In [[`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html)](https://github.com/tt-a1i/archify/blob/main/docs/start.html), the initialization script reads the `type` URL parameter and automatically activates the *Sequence* tab. This lands you in a dedicated text editor optimized for describing interaction flows.

**Quick access URL:**

```

https://t1-a1i.github.io/archify/start.html?type=sequence

```

Bookmark this link for one-click access to the sequence editor.

## Creating Sequence Diagrams from Natural Language

The primary workflow uses **natural language prompts** to describe system interactions. Archify parses these descriptions into an intermediate representation (IR) that drives the visual renderer.

### Step-by-Step Prompt Workflow

1. **Describe the interaction** in the text editor using narrative or concise technical language
2. **Press Enter or click Generate** to trigger the rendering pipeline
3. **Review the generated SVG** injected into `<div class="diagram-container">`

Example prompt:

```

User opens the dashboard, the API verifies a JWT, falls back to Redis cache, then reads from Postgres and emits a trace event

```

The parsing engine extracts **participants** (User, API, Redis, Postgres, Trace), **messages** (verify JWT, read cache, query profile), and **activation bars** to build the diagram structure.

## Using the JSON Intermediate Representation

For precise control, toggle the **⚙️ JSON** button to edit the intermediate representation directly. The JSON schema defines participants, messages, and optional styling metadata.

### Complete JSON IR Example

```json
{
  "type": "sequence",
  "participants": [
    {"id": "user", "label": "User"},
    {"id": "web", "label": "Web App"},
    {"id": "api", "label": "API"},
    {"id": "auth", "label": "Auth"},
    {"id": "cache", "label": "Redis"},
    {"id": "db", "label": "Postgres"},
    {"id": "trace", "label": "Trace"}
  ],
  "messages": [
    {"from": "web", "to": "api", "label": "GET /dashboard"},
    {"from": "api", "to": "auth", "label": "verify JWT"},
    {"from": "auth", "to": "api", "label": "claims ok"},
    {"from": "api", "to": "cache", "label": "read cache"},
    {"from": "cache", "to": "api", "label": "miss"},
    {"from": "api", "to": "db", "label": "query profile"},
    {"from": "db", "to": "api", "label": "rows"},
    {"from": "api", "to": "cache", "label": "set cache"},
    {"from": "api", "to": "trace", "label": "emit trace"},
    {"from": "api", "to": "web", "label": "200 JSON"}
  ]
}

```

Paste this JSON into the editor, press **Generate**, and Archify renders a complete sequence diagram with lifelines, activation bars, and semantic styling.

## Understanding the Rendering Architecture

The sequence diagram rendering pipeline in Archify consists of three core components:

### 1. Parser and IR Builder

Converts natural language or JSON into a structured representation with participant definitions, message sequences, and timing data.

### 2. SVG Generator

Implemented 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), this module constructs SVG elements using:
- **Semantic CSS classes**: `.c-frontend`, `.c-backend`, `.c-security`, `.c-database`, `.c-cache`
- **Marker definitions** for arrowheads and activation indicators
- **Calculated geometry** for lifeline positioning and message routing

### 3. Theme and Interaction Layer

The `Archify.theme` module manages dark/light mode switching. The toolbar provides zoom, lane focus, and flow tracing interactions.

## Customizing Diagram Appearance

Archify applies **semantic styling** based on participant IDs and types. The CSS class mapping ensures consistent visual language across diagrams:

| Participant Type | CSS Class | Typical Color |
|-----------------|-----------|---------------|
| User-facing components | `.c-frontend` | Blue tones |
| Server/API layers | `.c-backend` | Green tones |
| Authentication services | `.c-security` | Amber/orange |
| Databases | `.c-database` | Purple tones |
| Cache layers | `.c-cache` | Cyan tones |

Reference the generated SVG in [[`examples/sequence-cache-miss.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html)](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html) to see these classes applied to lifelines, message arrows, and activation boxes.

## Interacting with Generated Diagrams

Once rendered, sequence diagrams support several interaction modes via the toolbar:

- **Theme toggle**: Switch between light and dark modes instantly
- **Zoom controls**: Scale the diagram for detailed inspection
- **Lane focus**: Highlight individual participant lifelines
- **Flow tracing**: Animate message sequences step-by-step

These interactions are powered by the `Archify.theme` and `Archify.export` modules defined in the template script.

## Exporting Sequence Diagrams

Archify supports **four export formats** with optional dual-theme packaging:

| Format | Use Case | Dual-Theme Support |
|--------|----------|------------------|
| SVG | Documentation, version control, further editing | Yes |
| PNG | Presentations, Slack/email sharing | Yes |
| JPEG | Compact raster for web pages | Yes |
| WebP | Modern compression, smaller file sizes | Yes |

The export logic resides in the inline `/* Export — PNG / JPEG / … */` section of [[`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). It works by:
1. Serializing the current SVG DOM
2. Optionally scaling for high-DPI output
3. Rendering to canvas (for raster formats)
4. Invoking the browser's download API

Access exports through the **Export** button in the diagram toolbar.

## Embedding Diagrams in External Pages

Generated sequence diagrams can be embedded in documentation or applications using three approaches:

### Method 1: Inline SVG (Recommended)

Copy the generated `<svg>` element directly:

```html
<svg viewBox="0 0 820 760" role="img" aria-label="Authentication flow diagram">
  <!-- paste Archify-generated SVG content here -->
</svg>

```

This preserves interactivity and ensures crisp rendering at any scale.

### Method 2: External SVG Reference

Download via the Export menu and reference as an image:

```html
<img src="diagrams/api-auth-flow.svg" alt="API authentication sequence" loading="lazy">

```

### Method 3: Gallery Artifacts

For production documentation, use the pre-built artifacts in [`docs/gallery/artifacts/`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/). The file [[`cache-miss.sequence.html`](https://github.com/tt-a1i/archify/blob/main/cache-miss.sequence.html)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/cache-miss.sequence.html) demonstrates export-ready SVG with embedded dual-theme CSS.

## Summary

- **Launch**: Use `?type=sequence` to open the sequence editor directly in [[`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html)](https://github.com/tt-a1i/archify/blob/main/docs/start.html)
- **Create**: Write natural language prompts or define precise JSON IR with participants and messages
- **Render**: The engine 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) generates semantic SVG with `.c-*` CSS classes
- **Customize**: Toggle themes, zoom, and trace flows via the integrated toolbar
- **Export**: Download as SVG, PNG, JPEG, or WebP with optional dual-theme packaging
- **Embed**: Use inline SVG for documentation or external references for email/presentations

## Frequently Asked Questions

### What input formats does Archify accept for sequence diagrams?

Archify accepts **natural language descriptions** in the main editor or **JSON intermediate representation** via the ⚙️ JSON toggle. The JSON schema requires `type: "sequence"`, a `participants` array with `id` and `label` fields, and a `messages` array with `from`, `to`, and `label` properties. No other formats (PlantUML, Mermaid, etc.) are directly supported.

### Can I customize colors and styling in sequence diagrams?

Styling is **semantic and automatic** based on participant ID patterns. The renderer assigns CSS classes like `.c-frontend`, `.c-backend`, `.c-security`, `.c-database`, and `.c-cache`. To override colors, modify the generated SVG's `<style>` block or post-process the export. The [[`examples/sequence-cache-miss.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html)](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html) file shows the complete class structure.

### Does Archify support offline usage or self-hosting?

Yes. The entire application is **static HTML/JavaScript** with no server-side dependencies. Clone the `tt-a1i/archify` repository and open [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html) directly in a browser, or serve via any static file server. The rendering engine, theme system, and export functionality are fully client-side.

### How do I export diagrams for both light and dark themes?

Use the **dual-theme export option** in the Export menu. This packages the SVG with embedded CSS that responds to `prefers-color-scheme` media queries, or generates separate PNG/JPEG files for each theme. The implementation in [[`docs/gallery/artifacts/cache-miss.sequence.html`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/cache-miss.sequence.html)](https://github.com/tt-a1i/archify/blob/main/docs/gallery/artifacts/cache-miss.sequence.html) demonstrates the dual-theme CSS pattern.