# How Archify Creates Sequence Diagrams for API Calls: A Complete Guide

> Learn how Archify generates sequence diagrams for API calls. This guide explains converting IR to HTML SVG visuals with dark/light themes and interactive exports.

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

---

**Yes, Archify can create sequence diagrams for API calls by converting a typed JSON Intermediate Representation (IR) into a self-contained HTML file with SVG visualization, complete with dark/light themes and interactive export controls.**

The open-source **tt-a1i/archify** repository provides a schema-driven toolchain specifically designed to document request/response flows. By defining your API architecture as structured JSON, you generate polished, browser-ready diagrams that capture authentication steps, cache lookups, and microservice interactions.

## The JSON-to-Diagram Pipeline

Archify implements a three-stage pipeline to transform declarative JSON into visual sequence diagrams. All validation and rendering logic resides in the sequence renderer module, ensuring type safety and consistent layout across different API call patterns.

### Schema Validation

Every sequence diagram must conform to the **sequence schema** defined in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json). The schema mandates three top-level sections:

- **`meta`** – Contains diagram metadata including `title` and `viewBox` dimensions
- **`participants`** – An array of actors with `id`, `type` (e.g., external, frontend, security), `label`, and optional `sublabel`
- **`messages`** – An array of interactions specifying `from` and `to` participant IDs, vertical position `y`, text `label`, and visual `variant`

Before rendering, the `validateSequence()` function in `archify/renderers/sequence/render-sequence.mjs` (lines 48–69) enforces structural constraints. It checks for unique participant IDs, validates message spacing, and ensures the view-box dimensions can accommodate the defined vertical positions.

### SVG and HTML Generation

Once validation passes, the renderer (`archify/renderers/sequence/render-sequence.mjs`, starting at line 14) constructs the visual output. It generates an SVG containing:

- Participant boxes with typed backgrounds and optional sub-labels
- Vertical lifelines for each actor
- Directional arrows with variant-specific styling (**emphasis**, **security**, **dashed**, **return**, or default)
- Activation bars showing processing duration
- Legend and contextual "cards" for workflow notes

The final output embeds this SVG into [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), producing a single file with built-in theme toggling.

## Structuring API Call Sequences

To document an API call, you describe the interaction as a JSON object. The repository includes a working example in [`archify/examples/cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/cache-miss-request.sequence.json) that models a full request flow with cache fallback.

Here is a minimal configuration for a login API sequence:

```json
{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "Login API Call",
    "viewBox": [900, 600]
  },
  "participants": [
    { "id": "client", "type": "external", "label": "Client", "sublabel": "browser" },
    { "id": "gateway", "type": "frontend", "label": "API GW", "sublabel": "nginx" },
    { "id": "auth", "type": "security", "label": "Auth Service", "sublabel": "JWT verify" }
  ],
  "messages": [
    { "from": "client", "to": "gateway", "y": 150, "label": "POST /login", "variant": "emphasis" },
    { "from": "gateway", "to": "auth", "y": 200, "label": "verify token", "variant": "security" },
    { "from": "auth", "to": "gateway", "y": 250, "label": "OK", "variant": "return" },
    { "from": "gateway", "to": "client", "y": 300, "label": "200 JSON", "variant": "return" }
  ],
  "activations": [
    { "participant": "gateway", "from": 140, "to": 310, "type": "frontend" },
    { "participant": "auth", "from": 190, "to": 260, "type": "security" }
  ],
  "cards": [
    {
      "dot": "emerald",
      "title": "Happy Path",
      "items": ["Client → API GW → Auth → API GW → Client"]
    }
  ]
}

```

Save this definition as [`login-api.sequence.json`](https://github.com/tt-a1i/archify/blob/main/login-api.sequence.json). The `y` coordinates control vertical sequencing, while `variant` values alter arrow colors and styles to distinguish between public calls, security checks, and return values.

## Command-Line Rendering

The CLI entry point in `archify/bin/archify.mjs` exposes a `render` sub-command that invokes the sequence renderer. To generate the HTML diagram from your JSON definition:

```bash

# Install the skill globally (one-time setup)

npx skills add tt-a1i/archify -g

# Render the sequence diagram

archify render sequence login-api.sequence.json login-api.html

```

This executes the `commandRender` handler, which validates the input against [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json), calls the rendering functions in `archify/renderers/sequence/render-sequence.mjs`, and writes the themed HTML output. Open [`login-api.html`](https://github.com/tt-a1i/archify/blob/main/login-api.html) in any browser to view the interactive diagram with toggleable dark and light modes.

## AI Agent Integration

Archify operates inside Claude, Codex, and Opencode agents that have the skill installed. When working with an AI assistant, you can provide the JSON IR directly:

```text
User: "Show me the login flow for my service."
Agent: "Generating sequence diagram..."

```

The agent constructs the JSON payload—including participants, messages, and activations—and returns the generated HTML snippet, which you can copy, export, or embed into documentation.

## Summary

- Archify creates sequence diagrams for API calls by validating JSON against [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) and rendering to SVG/HTML.
- The `validateSequence()` function in `archify/renderers/sequence/render-sequence.mjs` enforces layout rules (unique IDs, spacing, view-box limits) at lines 48–69.
- Visual styling is controlled via message `variant` properties: **emphasis**, **security**, **dashed**, **return**, and default.
- The CLI command `archify render sequence <input.json> <output.html>` handles the full pipeline, as implemented in `archify/bin/archify.mjs`.
- Output files are self-contained HTML documents based on [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), supporting dark/light themes and export controls.

## Frequently Asked Questions

### What JSON schema does Archify use to define sequence diagrams?

Archify validates all inputs against the **sequence schema** located at [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json). This schema requires a `meta` object, a `participants` array with unique IDs, and a `messages` array specifying source, target, vertical position (`y`), and visual style (`variant`).

### How do I render a sequence diagram from the command line?

Use the `archify render sequence` command followed by your input JSON and desired output HTML file: `archify render sequence input.json output.html`. This command is handled by the `commandRender` logic in `archify/bin/archify.mjs` and invokes the full validation and SVG generation pipeline.

### Can Archify validate sequence diagrams before rendering?

Yes. The `validateSequence()` function in `archify/renderers/sequence/render-sequence.mjs` (lines 48–69) runs pre-flight checks to ensure participant IDs are unique, message coordinates fit within the defined `viewBox`, and all required fields are present before any SVG is generated.

### What visual styles are supported for API call arrows?

Archify supports five message variants defined in the schema: **default** (standard arrow), **emphasis** (highlighted for critical paths), **security** (styled for auth flows), **dashed** (for conditional or async calls), and **return** (distinguished arrowhead for responses). These variants control stroke colors and arrowhead styles in the final SVG output.