How to Use Archify for Sequence Diagrams: A Complete Guide

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

{
  "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), 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) 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). 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:

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

<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/. The file [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)
• 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) 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) 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 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) demonstrates the dual-theme CSS pattern.

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