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

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. 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, 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 that models a full request flow with cache fallback.

Here is a minimal configuration for a login API sequence:

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

# 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, calls the rendering functions in archify/renderers/sequence/render-sequence.mjs, and writes the themed HTML output. Open 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:

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

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