Five Diagram Types in Archify: When to Use Each One

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 before rendering. Typical prompts focus on describing the overall system structure.

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.

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 enforces structure for these diagrams.

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.

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.

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.

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.

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.

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.

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.

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:

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 or 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:

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 for Architecture and lifecycle-agent-run.html for Lifecycle diagrams.

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