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

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

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

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

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

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

// 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 shows state progression through initialization, execution, and termination phases.

---

Summary

• Architecture (docs/start.html): High-level system maps with trust boundaries—best for onboarding and design reviews.
• Workflow (archify/schemas/workflow.schema.json): Procedural flows with lanes and phases—best for pipelines and runbooks.
• Sequence (archify/schemas/sequence.schema.json): Temporal call ordering—best for debugging request chains and state machines.
• Data Flow (archify/schemas/dataflow.schema.json): Data lineage and transformations—best for analytics and ETL pipelines.
• Lifecycle (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 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 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.

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