Archify Sequence vs Data Flow vs Lifecycle Diagrams: How to Choose the Right Model

Archify renders five diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each designed for a specific style of system-level technical communication.

The tt-a1i/archify repository provides a CLI-driven visualization engine that transforms plain-text prompts into precise, schema-validated diagrams. This guide focuses on the three interaction-oriented types—Sequence, Data Flow, and Lifecycle—explaining their distinct modeling purposes, visual conventions, and CLI usage patterns.

What Each Diagram Type Models

According to the repository's README, Archify maps diagram types to communication goals through specific prompt structures:

Diagram type	What it models	Typical prompt hints
Architecture	Components, services, storage, trust boundaries	"Scope, core components, primary path"
Workflow	CI/CD pipelines, approvals, runbooks	"Participants, order, branches, exceptions"
Sequence	API calls, cache fall-backs, auth checks, async traces	"Callers, callees, returns, timing"
Data Flow	Pipelines, lineage, PII handling, consumer relationships	"Sources, transforms, stores, boundaries"
Lifecycle	State machines, retries, waits, terminal outcomes	"States, events, retry and cancellation paths"

Source: README.md [source]

Sequence Diagrams: Time-Ordered Interaction Traces

A Sequence diagram visualizes request-response flows between participants across a timeline. Use this type when you need to document RPC-style traces, authentication checks, or cache-miss handling.

Visual Conventions

Archify renders participants as vertical lifelines with horizontally flowing arrows. Each arrow carries a semantic class that encodes interaction type:

• a-default – normal request/return (gray)
• a-emphasis – forward calls (green)
• a-security – security-related messages (red)
• a-dashed – asynchronous trace events (orange)

Example: Cache-Miss Request Path

The file examples/sequence-cache-miss.html demonstrates a full request path: browser → JWT verification → Redis cache miss → PostgreSQL fallback → async trace emission.

The underlying SVG markup applies these semantic classes directly:

<path d="M 177 228 L 271 228" class="a-emphasis" marker-end="url(#arrowhead-emphasis)"/>
<text x="224" y="218" class="t-backend" font-size="9" text-anchor="middle">GET /dashboard</text>

Source: examples/sequence-cache-miss.html [source]

CLI Command for Sequence Diagrams

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

This generates both sequence-cache-miss.json (the typed IR) and a preview HTML file.

Data Flow Diagrams: Asset Movement and Lineage

A Data Flow diagram tracks how data assets move through pipelines—from sources through transforms to stores. This type excels at mapping PII handling, consumer relationships, and replay mechanisms.

Structural Pattern

Unlike Sequence diagrams, Data Flow diagrams group arrows into source → transform → store pipelines. The same semantic classes apply, but edge labels like "stream", "transform", or "store" determine styling.

Example: Product Analytics Pipeline

The file examples/dataflow-product-analytics.html maps Kafka topics, consumer groups, replay mechanisms, and dead-letter queues. Each pipeline stage uses a-default, a-emphasis, or a-dashed classes to distinguish data movement patterns.

Source: examples/dataflow-product-analytics.html [source]

CLI Command for Data Flow Diagrams

node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ"

Lifecycle Diagrams: State Machines and Terminal Outcomes

A Lifecycle diagram renders finite-state machines with explicit retry logic, interruption points, and terminal exits. Use this for agent run lives, CI job steps, or any process that can pause, fail, or cancel.

Visual Structure

Archify places states on a horizontal rail (class c-lane) with grouped interrupt/recovery lanes below the main phase band:

• a-emphasis – normal forward transitions (e.g., "queued → planning")
• a-security – approval checkpoints
• a-dashed – retry or error paths

Example: Agent-Run Lifecycle

The file examples/lifecycle-agent-run.html shows phases: Queued → Planning → Executing → Reviewing → Completed. It also renders interruption states (Needs Approval, Blocked), recoverable failures, and terminal exits (Cancelled, Expired).

The SVG encodes each lane and transition with semantic classes, making the diagram readable and exportable.

Source: examples/lifecycle-agent-run.html [source]

CLI Command for Lifecycle Diagrams

node archify/bin/archify.mjs guide "Show an agent run lifecycle with retries and cancellations"

How Archify Generates All Three Types

Archify's CLI (archify/bin/archify.mjs) follows a consistent pipeline for every diagram type:

1. Parse the plain-text prompt
2. Build a typed JSON IR ("typed source")
3. Validate against the schema in archify/schemas/
4. Render deterministic HTML/SVG output

You can invoke stages manually:

• guide – full pipeline from prompt to preview
• validate – schema compliance check
• deliver – final artifact export

The JSON schema definitions for all five diagram types reside in archify/schemas/README.md and related files, ensuring structural consistency across Sequence, Data Flow, and Lifecycle representations.

CLI entry point: archify/bin/archify.mjs [source]

Summary

• Sequence diagrams model time-ordered interactions with semantic arrow classes for security, async, and emphasis paths
• Data Flow diagrams trace asset lineage through source-transform-store pipelines, highlighting PII and consumer boundaries
• Lifecycle diagrams render state machines with retry logic and terminal exits on horizontal lanes with interrupt groups
• All three types share Archify's CLI workflow (guide, validate, deliver) and schema-validated JSON IR architecture

Frequently Asked Questions

How do I choose between a Sequence and Data Flow diagram for my use case?

Use a Sequence diagram when timing and call order matter—API requests, auth flows, cache operations. Use a Data Flow diagram when tracking data assets through transformations—pipelines, lineage, PII movement. The prompt hint "callers, callees, returns, timing" signals Sequence; "sources, transforms, stores, boundaries" signals Data Flow.

What does the a-dashed semantic class represent across diagram types?

In Sequence diagrams, a-dashed marks asynchronous trace events. In Data Flow diagrams, it indicates replay or DLQ paths. In **Lifecycle diagrams`, it denotes retry or error transitions. The class maintains consistent visual meaning—non-primary, exceptional, or deferred flow—regardless of diagram type.

Can I manually edit the generated JSON IR before rendering?

Yes. The guide subcommand outputs both .json (typed IR) and .html (preview). You can modify the JSON and run validate then deliver separately. The schemas in archify/schemas/ define valid structures for each diagram type, ensuring your edits remain compliant.

Where are the schema definitions for each diagram type?

Schema documentation lives in archify/schemas/README.md with supporting JSON schema files in the same directory. These schemas enforce type safety for Architecture, Workflow, Sequence, Data Flow, and Lifecycle diagram structures before HTML/SVG rendering occurs.

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