How to Use the Archify Scenario Guide to Pick the Right Diagram Type

Use Archify's built-in scenario guide to match your specific question to one of five diagram types—architecture, workflow, sequence, dataflow, or lifecycle—by reading each recipe's type, useWhen, and avoidWhen fields.

Archify is an open-source diagram generator that ships with a question-first scenario guide mapping concrete user needs to pre-defined recipes. Each recipe includes a type field that specifies which of the five renderers best fits your scenario. This article walks through how to navigate the guide and select the correct diagram type for any architectural question.

Opening the Interactive Scenario Guide

Archify provides two ways to access the scenario guide:

• Web interface: Open docs/guide.html in your browser (source)
• CLI command: Run archify guide from your terminal

The guide displays all 11 recipes in a table with question, title, and type columns. The underlying data lives in archify/recipes/scenarios.mjs, where each recipe object contains the metadata driving the selection process.

Matching Your Question to a Diagram Type

Follow this three-step workflow to pick the right diagram type:

1. Scan the question field — Each recipe poses a specific question like "What does a user call, in what order, and what returns?" Find the one matching your information need.

2. Read the type property — The recipe's type field maps directly to one of five renderers.

3. Validate with useWhen / avoidWhen — Cross-check the contextual cues to confirm your choice.

The Five Diagram Types Defined in Archify

Type	Best For	Typical Use Cases
architecture	Component/service overviews	System boundaries, trust zones, primary data paths
workflow	Process automation	CI/CD pipelines, approval chains, runbooks
sequence	Ordered interactions	API call flows, cache fallback, async round-trips
dataflow	Data movement & lineage	Pipelines, PII handling, producer-consumer relationships
lifecycle	State transitions	Job states, ticket workflows, retry logic

This mapping is hardcoded in scenarios.mjs through the type field on each recipe object.

Using the CLI to Query Recipes Programmatically

The archify.mjs CLI supports direct recipe lookup, returning JSON that includes the diagram type.

List All Recipes as JSON

node archify/bin/archify.mjs guide --json

Query for a Specific Scenario

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" --json

# Returns recipe with "type":"sequence"

Query for Data Streaming Topology

node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

# Returns recipe with "type":"dataflow"

The CLI performs fuzzy matching against recipe questions and titles, making it useful for automated tooling or CI pipelines.

Rendering the Diagram Once You Know the Type

After identifying the correct type, invoke Archify with the corresponding --type flag. The renderer applies style and motion presets defined in the recipe's presentation field.

Example: Sequence diagram for API call flow

node archify/bin/archify.mjs diagram \
  --type sequence \
  --prompt "Use Archify sequence mode to show this request from caller to final response..."

Example: Dataflow diagram for event streaming

node archify/bin/archify.mjs diagram \
  --type dataflow \
  --prompt "Use Archify dataflow mode to draw this event-stream topology..."

Available --type values: architecture, workflow, sequence, dataflow, lifecycle.

Key Source Files for the Scenario Guide

File	Purpose
archify/recipes/scenarios.mjs	Master recipe definitions including type, useWhen, avoidWhen, and presentation fields
docs/guide.html	Generated interactive guide (built from recipe data)
scripts/build-guide.mjs	Build script that injects recipe JSON into guide.html
archify/bin/archify.mjs	CLI entry point for guide and diagram commands
README.md	Quick-reference table for diagram type selection

To understand how recipes translate to rendering behavior, inspect scenarios.mjs directly—the type field is the single source of truth for renderer selection.

Summary

• The scenario guide in scenarios.mjs provides 11 question-based recipes, each with a type field specifying the renderer.
• Five diagram types cover architecture, workflow, sequence, dataflow, and lifecycle visualizations.
• Two access methods: interactive HTML guide or archify guide CLI command.
• Validation fields: Use useWhen and avoidWhen to confirm appropriate type selection.
• CLI integration: Query recipes programmatically with --json output, then render with --type.

Frequently Asked Questions

What file contains the scenario recipe definitions?

The recipe data lives in archify/recipes/scenarios.mjs. Each exports an object with question, type, useWhen, avoidWhen, and presentation properties. The type field drives renderer selection.

How does the CLI figure out which recipe matches my query?

The archify guide command performs fuzzy string matching against recipe question and title fields. It returns the closest match as JSON, including the type value you need for diagram generation.

Can I use the scenario guide without the web interface?

Yes. The archify guide CLI command provides identical functionality. Run archify guide --json to dump all recipes, or pass a search string to find a specific match.

What's the difference between useWhen and avoidWhen?

useWhen lists conditions where the recipe (and its type) is appropriate. avoidWhen warns against misuse—helping you catch mismatches like using sequence diagrams for static topology or architecture diagrams for temporal flows.

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