# Archify Diagram Types Explained: 5 Use Cases for Architecture, Workflow, Sequence, Data Flow, and Lifecycle Diagrams

> Discover Archify's 5 diagram types: architecture, workflow, sequence, data flow, and lifecycle. Learn specific use cases to improve your technical communication and system visualization.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: use-case-guide
- Published: 2026-09-01

---

**Each of Archify's five diagram types—architecture, workflow, sequence, data flow, and lifecycle—serves a distinct technical communication purpose, from high-level system maps to exact call ordering and data lineage tracing.**

The `tt-a1i/archify` repository provides five typed renderers, each with a dedicated JSON schema and explicit guidance on when to use (and when to avoid) each format. This guide breaks down the specific use cases for every Archify diagram type, grounded in the actual source code and schema definitions.

---

## Architecture Diagram Use Cases

The **architecture** diagram type creates bounded, high-level system maps. According to the source code in [`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html), this renderer includes explicit `useWhen` and `avoidWhen` fields that guide users toward appropriate scenarios.

**Use this diagram type for:**

- Onboarding new team members to a codebase or service landscape
- Design-review and architecture-review meetings
- Mapping core runtime components, primary request/data paths, external dependencies, and trust boundaries

**Avoid when** you need exact call order, state transitions, or row-level data lineage—these belong to sequence, lifecycle, or data flow diagrams instead.

```javascript
// Rendering an Architecture diagram
archify.render({
  diagram_type: "architecture",
  meta: { title: "System Overview" },
  components: [{ id: "web", label: "Web Server" }],
  connections: [{ from: "web", to: "db" }],
});

```

The architecture schema emphasizes **components** and **connections** without imposing procedural or temporal structure.

---

## Workflow Diagram Use Cases

The **workflow** diagram type extends architectural concepts with **lanes**, **phases**, and **groups** to capture procedural execution. The JSON schema at [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) formalizes these structures.

**Use this diagram type for:**

- Describing end-to-end processes, pipelines, or runbooks (release delivery, incident response, agent-tool orchestration)
- Visualizing lanes, phases, and groups that structure a procedural flow

**Avoid when** the focus is static component relationships rather than procedural steps.

```javascript
// Rendering a Workflow diagram with lanes and phases
archify.render({
  diagram_type: "workflow",
  meta: { title: "Release Delivery" },
  lanes: [{ id: "ci", label: "CI" }],
  phases: [{ id: "build", label: "Build" }],
  nodes: [{ id: "compile", lane: "ci", phase: "build", label: "Compile Code" }],
  edges: [{ from: "compile", to: "test" }],
});

```

See [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) for a concrete implementation showing agent-tool call orchestration with defined lanes and routing rules.

---

## Sequence Diagram Use Cases

The **sequence** diagram type focuses strictly on **temporal ordering** of calls, messages, or state transitions. The schema at [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) defines **participants** and ordered **messages**.

**Use this diagram type for:**

- Showing exact call order, message passing, or state-transition sequences
- Debugging cache-miss handling, API request chains, or state machines

**Avoid when** you need a higher-level structural map without step-by-step ordering.

```javascript
// Rendering a Sequence diagram
archify.render({
  diagram_type: "sequence",
  meta: { title: "Cache Miss Flow" },
  participants: ["Client", "Cache", "DB"],
  messages: [
    { from: "Client", to: "Cache", label: "GET /item" },
    { from: "Cache", to: "DB", label: "MISS → QUERY" },
  ],
});

```

The example at [`examples/sequence-cache-miss.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss.html) demonstrates cache-miss handling with precise message ordering between Client, Cache, and Database participants.

---

## Data Flow Diagram Use Cases

The **data flow** diagram type treats the system as a graph of **data movement**, emphasizing sources, transformations, and sinks. The schema at [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) captures field-level propagation.

**Use this diagram type for:**

- Tracing data lineage and field-level propagation
- Documenting analytics data pipelines and ETL jobs

**Avoid when** the concern is architectural boundaries or procedural steps rather than data movement itself.

```javascript
// Rendering a Data Flow diagram
archify.render({
  diagram_type: "dataflow",
  meta: { title: "Analytics Pipeline" },
  nodes: [{ id: "source", label: "Event Source" }],
  edges: [{ from: "source", to: "transform", label: "raw events" }],
});

```

The product analytics example at [`examples/dataflow-product-analytics.html`](https://github.com/tt-a1i/archify/blob/main/examples/dataflow-product-analytics.html) illustrates how raw events flow through transformation stages to consumption endpoints.

---

## Lifecycle Diagram Use Cases

The **lifecycle** diagram type models **state phases and transitions** over time for components or services. The schema at [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) defines stages and valid transitions between them.

**Use this diagram type for:**

- Depicting component lifecycles, deployment phases, or state changes over time
- Documenting startup/shutdown sequences or version upgrade procedures

**Avoid when** the primary need is a static architecture view or a procedural workflow without explicit state modeling.

```javascript
// Rendering a Lifecycle diagram
archify.render({
  diagram_type: "lifecycle",
  meta: { title: "Agent Run Lifecycle" },
  stages: ["Init", "Run", "Shutdown"],
  transitions: [{ from: "Init", to: "Run" }, { from: "Run", to: "Shutdown" }],
});

```

The agent run example at [`examples/lifecycle-agent-run.html`](https://github.com/tt-a1i/archify/blob/main/examples/lifecycle-agent-run.html) shows state progression through initialization, execution, and termination phases.

---

## Summary

- **Architecture** ([`docs/start.html`](https://github.com/tt-a1i/archify/blob/main/docs/start.html)): High-level system maps with trust boundaries—best for onboarding and design reviews.
- **Workflow** ([`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)): Procedural flows with lanes and phases—best for pipelines and runbooks.
- **Sequence** ([`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)): Temporal call ordering—best for debugging request chains and state machines.
- **Data Flow** ([`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)): Data lineage and transformations—best for analytics and ETL pipelines.
- **Lifecycle** ([`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)): State transitions over time—best for deployment and operational phases.

Each renderer includes explicit guidance (via schema constraints and documentation) on appropriate versus inappropriate use, helping teams select the most expressive visual language for their technical communication needs.

---

## Frequently Asked Questions

### When should I use an architecture diagram versus a workflow diagram in Archify?

Use an **architecture** diagram when you need a static, bounded map of system components, trust boundaries, and primary data paths—ideal for onboarding and design reviews. Use a **workflow** diagram when you need to show procedural execution with ordered steps, lanes, and phases—ideal for release pipelines and runbooks. The architecture type has no concept of temporal ordering; workflow adds explicit execution structure.

### Can Archify sequence diagrams show asynchronous message patterns?

Yes. The sequence renderer at [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) supports any ordered message pattern between participants. While the cache-miss example shows synchronous request-response, the schema imposes no synchrony constraints—you can model fire-and-forget, callback-based, or message-queue patterns by ordering messages appropriately and annotating them with async indicators in labels.

### What makes data flow diagrams different from architecture diagrams with data paths?

**Data flow** diagrams emphasize **row-level lineage and transformation semantics**—they trace how specific data elements propagate, split, merge, and transform through a pipeline. **Architecture** diagrams with data paths only show high-level "this connects to that" relationships without transformation detail or field-level tracking. The data flow schema includes explicit support for transformation nodes and labeled edge data types.

### How do lifecycle diagrams handle invalid state transitions?

The lifecycle schema at [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) explicitly defines valid **transitions** as a whitelist. Any state change not listed in the `transitions` array is considered invalid. The renderer validates diagrams against this schema—you cannot define a transition from "Shutdown" back to "Run" unless explicitly permitted in your JSON definition.