# How to Use the Archify Scenario Guide to Choose a Diagram Type

> Confused about which diagram type to use? The Archify scenario guide helps you choose the right one by mapping architectural questions to specialized diagram renderers. Learn more.

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

---

**The Archify scenario guide is an interactive decision tree that maps 11 common architectural questions to one of five specialized diagram renderers based on required evidence types.**

The `tt-a1i/archify` repository ships with a bilingual scenario guide that eliminates guesswork when selecting visualization strategies. Whether you browse the interactive web interface or query the zero-dependency CLI, the guide ensures you pick the correct renderer—Architecture, Data-flow, Lifecycle, Sequence, or Workflow—by matching your specific question to the required evidence contract defined in the source code.

## What Is the Archify Scenario Guide?

The scenario guide is a **question-first decision tool** baked into both the static site generator and the command-line interface. At its core, the guide references a single source of truth: [[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md). This file encodes 11 pre-defined recipes that pair architectural questions (for example, "What is the data-flow between Service A and Service B?") with the appropriate renderer and its mandatory evidence (nodes, edges, traces).

According to the repository structure, [`scripts/build-guide.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-guide.mjs) consumes [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) around line 50 to generate the browsable HTML interface. This ensures the web UI and CLI remain synchronized—both parse the same recipe definitions rather than maintaining duplicate logic.

## Accessing the Scenario Guide

You can interact with the scenario guide through two equally authoritative interfaces.

### Web Interface (guide.html)

Visit the public documentation page at `https://tt-a1i.github.io/archify/guide.html`. The page renders interactive cards, each displaying:

- A short, copy-ready architectural question
- The **recommended renderer** (e.g., Data-flow)
- Required evidence (nodes, edges, traces)
- Optional motion/views and a ready-to-copy LLM prompt

Clicking a card reveals the exact JSON source for the scenario and a live preview of the generated diagram.

### CLI Command (archify guide)

For terminal-centric workflows, install the CLI (zero dependencies) and query the guide programmatically:

```bash

# Query the guide for a specific scenario

archify guide "data flow between services" --json

```

The command outputs a JSON object containing:
- `renderer`: The chosen diagram type (e.g., `"dataflow"`)
- `prompt`: A copy-ready prompt for LLM integration
- `proof`: The generated SVG/PNG path or a named view URL to the Proof Lab

## Selecting the Right Diagram Type

Follow this evidence-based workflow to select the correct renderer:

1. **Identify your architectural question.** The guide covers 11 common patterns, from microservice communication to deployment lifecycles.

2. **Query the guide.** Use either the web interface or the CLI to retrieve the scenario definition:

   ```bash
   # List all available scenarios

   archify guide --list --json
   
   # Get a specific scenario

   archify guide "microservice communication" --json > scenario.json
   ```

3. **Inspect the evidence contract.** Each scenario in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) specifies exactly which evidence types (nodes, edges, traces) the renderer requires. The guide visually highlights the renderer that satisfies this contract for your specific question.

4. **Copy the prompt.** The JSON output includes a ready-to-copy prompt you can feed directly to an LLM or the Archify web UI to generate the diagram.

## Rendering and Validating Your Diagram

Once you have the scenario JSON, generate the static artifact and verify its integrity against the Proof Lab.

**Render the diagram:**

```bash
archify render scenario.json   # Creates scenario.svg

```

**Validate against the Proof Lab:**

Every scenario links to a Proof Lab entry at `https://tt-a1i.github.io/archify/gallery.html`. Validate your artifact using the SHA-256 digest and receipt:

```bash
archify verify --artifact scenario.svg --receipt receipt.json

```

This guarantees that the diagram you generated locally matches the scenario recommended by the guide.

## Programmatic Integration

Embed the scenario guide into Node.js automation pipelines using child process execution:

```javascript
const { execSync } = require('child_process');

// Query the guide and parse the JSON output
const raw = execSync('archify guide "data flow between services" --json', {
  encoding: 'utf8',
});
const result = JSON.parse(raw);

console.log('Renderer:', result.renderer);   // → "dataflow"
console.log('Prompt:', result.prompt);       // Ready-to-copy LLM prompt
console.log('Proof:', result.proof);         // SVG path or view URL

```

This pattern allows CI/CD systems to automatically select diagram types based on commit messages or architectural decision records stored in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).

## Summary

- The **Archify scenario guide** resides in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) and provides 11 question-to-renderer mappings.
- Access the guide via `https://tt-a1i.github.io/archify/guide.html` or the `archify guide` CLI command.
- The guide selects from five renderers: Architecture, Data-flow, Lifecycle, Sequence, and Workflow based on evidence requirements (nodes, edges, traces).
- Use `archify render scenario.json` to generate diagrams and `archify verify` to validate against the Proof Lab.
- Both web and CLI interfaces consume the same source file, ensuring consistent recommendations across environments.

## Frequently Asked Questions

### What file contains the scenario definitions in Archify?

The scenario definitions live in [[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md). This bilingual markdown file encodes the "question → renderer → evidence" mappings that both the CLI and the generated [`guide.html`](https://github.com/tt-a1i/archify/blob/main/guide.html) page consume. The build script [`scripts/build-guide.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-guide.mjs) reads this file to produce the interactive web interface.

### How do I validate that my generated diagram matches the guide's recommendation?

Run `archify verify --artifact <file.svg> --receipt receipt.json`. This command compares your generated SVG against the Proof Lab records at `https://tt-a1i.github.io/archify/gallery.html`, checking the SHA-256 digest and validation receipts to ensure the artifact matches the scenario's evidence contract.

### Can I use the scenario guide without installing the CLI?

Yes. Visit `https://tt-a1i.github.io/archify/guide.html` to browse the 11 pre-defined recipes interactively. The web interface provides the same JSON source and renderer recommendations as the CLI, allowing you to copy prompts and view live previews without installing `archify-cli`.

### Which diagram renderer should I choose for microservice communication patterns?

Query the guide with `archify guide "microservice communication" --json`. For service-to-service interaction questions, the guide typically recommends the **Data-flow** renderer, which requires edge and trace evidence to visualize request paths between nodes. The exact recommendation depends on whether you need to show state transitions (Lifecycle), temporal ordering (Sequence), or dependency hierarchies (Architecture).