# Archify Sequence vs Data Flow vs Lifecycle Diagrams: How to Choose the Right Model
> Understand Archify sequence, data flow, and lifecycle diagrams. Learn how to choose the right model for effective system-level technical communication and choose the best diagram for your needs.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-17
---
**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`](https://github.com/tt-a1i/archify/blob/main/README.md) [[source]](https://github.com/tt-a1i/archify/blob/main/README.md#sequence-data‑flow‑lifecycle)
## 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`](https://github.com/tt-a1i/archify/blob/main/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:
```svg
GET /dashboard
```
*Source:* [`examples/sequence-cache-miss.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html) [[source]](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html)
### CLI Command for Sequence Diagrams
```bash
node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
```
This generates both [`sequence-cache-miss.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/dataflow-product-analytics.html) [[source]](https://github.com/tt-a1i/archify/blob/main/examples/dataflow-product-analytics.html)
### CLI Command for Data Flow Diagrams
```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html) [[source]](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html)
### CLI Command for Lifecycle Diagrams
```bash
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`](https://github.com/tt-a1i/archify/blob/main/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]](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs)
## 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`](https://github.com/tt-a1i/archify/blob/main/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.