# Five Diagram Types in Archify: When to Use Each One

> Discover the five diagram types in Archify: Architecture, Workflow, Sequence, Data Flow, and Lifecycle. Learn when to use each for optimal system visualization and understanding.

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

---

**Archify supports five diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each designed for specific system views ranging from high-level infrastructure to state-machine flows.**

The `tt-a1i/archify` repository provides a type-safe diagram generation tool that transforms structured JSON into self-contained HTML/SVG visualizations. Understanding these five Archify diagram types helps you select the right view for documenting everything from cloud infrastructure to complex state machines.

## Architecture Diagrams

Use **Architecture** diagrams to visualize high-level system components, cloud resources, databases, caches, services, and security boundaries. This diagram type excels at showing deployment topology and infrastructure relationships across cloud environments.

According to the Archify source code, these diagrams are validated against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) before rendering. Typical prompts focus on describing the overall system structure.

```text
Use archify to draw an architecture diagram:
React frontend calls a Node.js API backed by PostgreSQL and Redis, deployed on AWS behind CloudFront.

```

See the live demo in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html).

## Workflow Diagrams

Use **Workflow** diagrams to map request lifecycles, approval flows, tool calls, CI/CD pipelines, and operational runbooks. This type emphasizes step order, decision branches, and participant interactions across a business process.

The schema at [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) enforces structure for these diagrams.

```text
Use archify to draw a workflow:
User submits a request → Agent plans → Approval gate (if needed) → Tool call → Trace log → Final reply.

```

Reference implementation: [`examples/workflow-agent-tool-call-rendered.html`](https://github.com/tt-a1i/archify/blob/main/examples/workflow-agent-tool-call-rendered.html).

## Sequence Diagrams

Use **Sequence** diagrams to trace API call chains, request lifecycles, cache fall-backs, async traces, and service interactions. This diagram type focuses on temporal ordering—who calls whom, in what sequence, and what returns between services.

Validation occurs via [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json).

```text
Use archify to draw a sequence diagram:
User opens a page, the frontend calls the API, the API verifies JWT, reads Redis, falls back to PostgreSQL on cache miss, returns JSON, and emits trace.

```

Example output: [`examples/sequence-cache-miss-request.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss-request.html).

## Data Flow Diagrams

Use **Data Flow** diagrams to document data pipelines, ETL/ELT processes, analytics events, PII isolation, warehouse synchronization, and downstream consumers. This type highlights sources, processing stages, storage boundaries, and sensitivity zones handling personally identifiable information.

The corresponding schema resides at [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json).

```text
Use archify to draw a data flow:
Web and mobile emit analytics events → Edge API collects them → Consent gate filters PII → Kafka carries accepted events → Warehouse stores analytics tables → Feature store derives daily features → Dashboards and ML model consume downstream data.

```

Live example: [`examples/dataflow-product-analytics.html`](https://github.com/tt-a1i/archify/blob/main/examples/dataflow-product-analytics.html).

## Lifecycle Diagrams

Use **Lifecycle** diagrams to model state-machine style flows such as order statuses, task progressions, deployment stages, or agent-run states. This type captures wait states, retry paths, transitions, and terminal outcomes like cancellation or completion.

These diagrams conform to [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json).

```text
Use archify to draw a lifecycle diagram:
Agent run starts at Queued, moves through Planning, Executing, and Reviewing. It can pause at Needs Approval, wait at Blocked, retry after Failed, end at Cancelled or Expired, or finish at Completed.

```

Demo file: [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html).

## Schema Validation and CLI Usage

Each diagram type is backed by a dedicated JSON schema that enforces structure and enables validation before rendering. This type-safe foundation ensures that the intermediate representation (IR) is valid before Archify generates the final self-contained HTML/SVG output.

To generate diagrams programmatically, use the CLI entry point at `bin/archify.mjs`:

```bash
npx skills add tt-a1i/archify -g          # install the skill

node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html

```

## Summary

- **Architecture**: Best for high-level infrastructure, cloud resources, and service boundaries.
- **Workflow**: Ideal for approval flows, CI/CD pipelines, and operational runbooks.
- **Sequence**: Perfect for API call chains, cache strategies, and service interactions.
- **Data Flow**: Essential for ETL pipelines, analytics events, and PII handling.
- **Lifecycle**: Suited for state machines, order flows, and agent-run statuses.

Each type validates against its own JSON schema in `archify/schemas/` before rendering to ensure diagram integrity.

## Frequently Asked Questions

### When should I use a Sequence diagram versus a Workflow diagram in Archify?

Use a **Sequence** diagram when you need to show temporal ordering of calls, returns, and interactions between specific services or components. Use a **Workflow** diagram when emphasizing business process steps, approval gates, and operational procedures without strict temporal sequencing.

### Does Archify validate diagram structure before rendering?

Yes. Archify validates all input against dedicated JSON schemas located in `archify/schemas/`. Each diagram type has its own schema file—such as [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) or [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)—ensuring type-safe intermediate representation before HTML/SVG generation.

### How do I generate an Architecture diagram using the Archify CLI?

Invoke the CLI via `bin/archify.mjs` with the render command, specifying the diagram type, input JSON file, and output HTML path:

```bash
node bin/archify.mjs render architecture input.json output.html

```

### Where can I find working examples of each diagram type?

The `examples/` directory in the `tt-a1i/archify` repository contains ready-made demonstrations for all five types, including [`web-app.html`](https://github.com/tt-a1i/archify/blob/main/web-app.html) for Architecture and [`lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/lifecycle-agent-run.html) for Lifecycle diagrams.