Archify's Five Diagram Types: When to Use Each One

Archify supports five distinct diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each designed for specific technical visualization needs with dedicated JSON schemas for validation.

Archify is an open-source diagram generation tool from the tt-a1i/archify repository that transforms structured text prompts into self-contained HTML/SVG visualizations. Understanding Archify's five diagram types helps you select the right view for system documentation, API design, or process modeling. Each type is backed by a strict JSON schema that enforces structure before rendering.

Overview of Archify's Diagram System

Archify generates diagrams through a type-safe pipeline. According to the project README (lines 52–60), the tool validates input against specific schemas before producing output. This validation layer prevents malformed diagrams and ensures consistency across exports.

The five schemas reside in archify/schemas/:

• architecture.schema.json for system overviews
• workflow.schema.json for process flows
• sequence.schema.json for interaction timelines
• dataflow.schema.json for data pipelines
• lifecycle.schema.json for state machines

The Five Diagram Types Explained

Architecture Diagrams

Architecture diagrams visualize high-level system components, cloud resources, databases, caches, and security boundaries. Use this type when documenting infrastructure layouts or deployment topologies.

The schema at archify/schemas/architecture.schema.json enforces component hierarchies and connection types. Typical prompts describe service relationships and deployment targets.

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

Reference implementation: examples/web-app.html

Workflow Diagrams

Workflow diagrams map request lifecycles, approval flows, CI/CD pipelines, and operational runbooks. Choose this type when illustrating multi-step processes with decision branches.

The archify/schemas/workflow.schema.json schema validates participant nodes, step ordering, and conditional gates. This suits agent tool-calling sequences and human-in-the-loop approvals.

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

Sequence diagrams track API call chains, request lifecycles, cache fall-backs, and async service interactions. Use this when detailing temporal ordering between actors.

The schema at archify/schemas/sequence.schema.json manages lifelines, activation boxes, and return messages. This type excels at debugging distributed system traces.

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.

Reference implementation: examples/sequence-cache-miss-request.html

Data Flow Diagrams

Data Flow diagrams illustrate ETL/ELT processes, analytics pipelines, PII isolation boundaries, and warehouse synchronization. Select this type when tracing data lineage from source to consumer.

The archify/schemas/dataflow.schema.json schema validates sources, processing stages, sensitivity labels, and downstream consumers. Critical for compliance documentation and analytics architecture.

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.

Reference implementation: examples/dataflow-product-analytics.html

Lifecycle Diagrams

Lifecycle diagrams model state-machine flows for orders, tasks, deployments, or agent runs. Use this when documenting states, transitions, retries, and terminal conditions.

The schema at archify/schemas/lifecycle.schema.json enforces state definitions, transition events, and retry paths. Essential for systems with complex state management.

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.

Reference implementation: examples/lifecycle-agent-run.html

Generating Diagrams with the CLI

Archify provides a unified CLI through bin/archify.mjs for rendering, validation, and schema checking. Install the skill and invoke renders directly:

npx skills add tt-a1i/archify -g
node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json workflow.html

The CLI validates input JSON against the appropriate schema (e.g., workflow.schema.json) before generating the self-contained HTML output. This ensures type safety without manual schema checking.

Summary

• Architecture diagrams visualize system infrastructure and component relationships using architecture.schema.json.
• Workflow diagrams map process steps and approval gates using workflow.schema.json.
• Sequence diagrams detail temporal interactions and API calls using sequence.schema.json.
• Data Flow diagrams trace data lineage and ETL processes using dataflow.schema.json.
• Lifecycle diagrams model state machines and transitions using lifecycle.schema.json.

Frequently Asked Questions

How does Archify validate diagram input?

Archify validates all input against dedicated JSON schemas stored in archify/schemas/. Each diagram type has its own schema file (e.g., sequence.schema.json) that enforces required fields, data types, and structural relationships before rendering occurs.

Can I use Archify without installing the CLI?

Yes. While bin/archify.mjs provides the command-line interface, you can also use Archify as a skill in compatible AI agents. The archify/SKILL.md file defines the skill specification for Claude/Opencode integration, allowing natural language prompts to generate diagrams directly.

What output formats does Archify produce?

Archify generates self-contained HTML/SVG files that render in any modern browser. The output is a single file with embedded styles and scripts, making it suitable for documentation sites, wikis, or email attachments without external dependencies.

Where can I find example implementations?

The examples/ directory contains ready-made HTML and JSON IR (Intermediate Representation) files for all five diagram types. Files like examples/web-app.html and examples/lifecycle-agent-run.html demonstrate valid schema usage and rendering results.

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