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

> Effortlessly pick the right diagram type with Archify's scenario guide. Match your question to architecture, workflow, sequence, dataflow, or lifecycle diagrams using type, useWhen, and avoidWhen fields.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html) in your browser ([source](https://github.com/tt-a1i/archify/blob/main/docs/guide.html))
- **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

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

```

### Query for a Specific Scenario

```bash
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

```bash
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**

```bash
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**

```bash
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`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html) | Generated interactive guide (built from recipe data) |
| `scripts/build-guide.mjs` | Build script that injects recipe JSON into [`guide.html`](https://github.com/tt-a1i/archify/blob/main/guide.html) |
| `archify/bin/archify.mjs` | CLI entry point for `guide` and `diagram` commands |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/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.