The Five Diagram Types Supported by Archify: A Complete Technical Guide

Archify supports five distinct diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each backed by dedicated JSON schemas that enforce structure before rendering.

Archify is an open-source diagram generation tool hosted at tt-a1i/archify that transforms text descriptions into technical visualizations. Understanding the diagram types supported by Archify is essential for selecting the right abstraction for your system, whether you're modeling cloud infrastructure, API interactions, or state-machine workflows. Each type is defined in the project's README.md (lines 52‑60) and validated against specific JSON schemas located in the archify/schemas/ directory.

The Five Supported Diagram Types

Architecture Diagrams

Architecture diagrams visualize high‑level system components, cloud resources, databases, caches, services, and security boundaries. These diagrams are ideal for showing how frontend applications interact with backend APIs and data stores.

Typical prompt: “Describe the system structure”

The structure is enforced by archify/schemas/architecture.schema.json. You can view a live implementation in examples/web-app.html, which renders a React frontend calling a Node.js API backed by PostgreSQL and Redis on AWS.

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

Workflow Diagrams

Workflow diagrams capture request lifecycles, approval flows, tool calls, CI/CD pipelines, and runbooks. These focus on participants, step order, and key branches within a process.

Typical prompt: “Describe participants, step order, and key branches”

Validation occurs against archify/schemas/workflow.schema.json. The repository provides a rendered example at examples/workflow-agent-tool-call-rendered.html showing a user request flowing through an agent planning phase, approval gates, and tool execution.

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

Sequence Diagrams

Sequence diagrams illustrate API call chains, request lifecycles, cache fall‑backs, async traces, and service interactions. This diagram type emphasizes temporal ordering—who calls whom, in what sequence, and what returns.

Typical prompt: “Describe who calls whom, in what order, and what returns”

The schema at archify/schemas/sequence.schema.json governs these diagrams. See examples/sequence-cache-miss-request.html for a demonstration of JWT verification, Redis reads, and PostgreSQL fallbacks.

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.

Data Flow Diagrams

Data flow diagrams map data pipelines, ETL/ELT processes, analytics events, PII isolation, warehouse synchronization, and downstream consumers. These diagrams trace how data moves from sources through processing stages to storage and consumption points.

Typical prompt: “Describe sources, processing stages, storage, sensitivity boundaries, and consumers”

Structure is validated via archify/schemas/dataflow.schema.json. The example at examples/dataflow-product-analytics.html shows analytics events flowing from web/mobile apps through consent gates and Kafka to data warehouses.

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.

Lifecycle Diagrams

Lifecycle diagrams model state‑machine style flows such as order statuses, task management, deployment stages, or agent‑run lifecycles. These include wait states, retry paths, and terminal outcomes.

Typical prompt: “Describe states, transition events, retry paths, and terminal outcomes”

The corresponding schema is archify/schemas/lifecycle.schema.json. Reference examples/lifecycle-agent-run.html for a state machine showing agent runs progressing through Queued, Planning, Executing, and Reviewing states with failure and cancellation branches.

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.

Schema Validation and Type Safety

Each of the five diagram types relies on a dedicated JSON schema to enforce structure and enable validation before rendering. According to the tt-a1i/archify source code, these schemas prevent invalid intermediate representations from reaching the rendering stage:

• Architecture: archify/schemas/architecture.schema.json
• Workflow: archify/schemas/workflow.schema.json
• Sequence: archify/schemas/sequence.schema.json
• Data Flow: archify/schemas/dataflow.schema.json
• Lifecycle: archify/schemas/lifecycle.schema.json

This type‑safe foundation ensures that the skill validates input JSON IR before producing the final self‑contained HTML/SVG diagram, as defined in archify/SKILL.md.

Rendering Diagrams via the CLI

You can generate any of the five diagram types using the unified CLI entry point at bin/archify.mjs. First install the skill globally, then invoke the render command with the diagram type, input JSON file, and output HTML path:

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

The CLI supports validation, checking, and demo modes, making it suitable for integration into documentation pipelines or CI/CD workflows.

Summary

Archify provides five specialized diagram types for technical documentation:

• Architecture: For system components, cloud resources, and security boundaries.
• Workflow: For approval flows, CI/CD pipelines, and tool-call sequences.
• Sequence: For API call chains, cache fallbacks, and service interactions.
• Data Flow: For ETL/ELT pipelines, analytics events, and PII isolation.
• Lifecycle: For state machines with wait, retry, and terminal states.

Each type is backed by a strict JSON schema in archify/schemas/ and includes working examples in the examples/ directory.

Frequently Asked Questions

What is the difference between Workflow and Sequence diagrams in Archify?

Workflow diagrams focus on business processes and approval gates, showing participants and decision branches, while Sequence diagrams emphasize the temporal order of API calls and service interactions. According to the tt-a1i/archify source code, Workflow uses archify/schemas/workflow.schema.json and is suited for runbooks, whereas Sequence uses archify/schemas/sequence.schema.json for technical request tracing.

How does Archify validate diagram input before rendering?

Archify validates input JSON against type‑specific schemas located in archify/schemas/ before rendering. This ensures that only well‑structured intermediate representations (IR) proceed to the HTML/SVG generation stage, preventing malformed diagrams from being produced.

Can I generate Architecture diagrams for AWS deployments?

Yes. The Architecture diagram type is specifically designed for cloud deployments. You can describe AWS resources like CloudFront, EC2, RDS, and ElastiCache in your prompt, and the schema at archify/schemas/architecture.schema.json will validate the structure. See examples/web-app.html for a working AWS example.

Where can I find example files for each diagram type?

Working examples are located in the examples/ directory of the repository. Key files include web-app.html (Architecture), workflow-agent-tool-call-rendered.html (Workflow), sequence-cache-miss-request.html (Sequence), dataflow-product-analytics.html (Data Flow), and lifecycle-agent-run.html (Lifecycle).

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