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

Archify's interactive scenario guide maps concrete design intents to specific diagram renderers through a short questionnaire, delivering pre-validated scenario recipes with copy-paste CLI prompts.

The tt-a1i/archify repository ships with an interactive decision-support tool that eliminates guesswork when selecting between Architecture, Workflow, Sequence, Data-flow, and Lifecycle renderers. Instead of memorizing renderer capabilities, you answer intent-oriented questions and receive a guaranteed-compatible diagram type with a matching visual preset.

Accessing the Interactive Scenario Guide

You can engage with the scenario guide through two interfaces: a generated web page or the zero-dependency CLI.

Web Interface: Navigate to the hosted guide at https://tt-a1i.github.io/archify/guide.html or open the source file directly in the repository at docs/guide.html. This generated page presents a short questionnaire that filters the available scenario recipes based on your answers.

CLI Interface: For terminal-centric workflows, invoke the guide logic directly from bin/archify.mjs:

node bin/archify.mjs guide "<scenario-name>" --json

This command returns a JSON recipe specifying the recommended renderer and a ready-to-use prompt, as documented in archify/SKILL.md.

How the Decision Flow Works

The guide implements a question-first narrowing algorithm. When you use the web interface, the system presents targeted questions such as:

• "Do you need to model system boundaries?"
• "Are you visualising ordered events?"
• "Do you need to show data-flow relationships?"

Each answer filters the set of available scenario recipes until the guide presents a shortlist of pre-validated options. This logic is compiled into docs/guide.html by the build script located at scripts/build-guide.mjs, which processes the scenario-recipe JSON source into the interactive HTML interface.

Selecting and Using Scenario Recipes

Once the questionnaire is complete, the guide displays scenario recipes that match your requirements. According to the repository's README, each recipe includes four components:

• A description of the specific problem it solves
• The recommended renderer (e.g., architecture, workflow, sequence, data-flow, or lifecycle)
• A ready-to-copy prompt for the zero-dependency CLI
• A link to a live proof artifact demonstrating the output

For example, selecting a recipe for a "service dependency map" yields a configuration targeting the Architecture renderer with presets optimized for dependency visualization.

CLI Workflow for Automated Selection

You can bypass the interactive web flow and retrieve recipe data programmatically. The following example demonstrates choosing a diagram type for service dependency mapping:

# Query the guide for a specific scenario

node bin/archify.mjs guide "service dependency map" --json

The command outputs structured JSON:

{
  "renderer": "architecture",
  "prompt": "... (copy-paste into archify render) ..."
}

This allows you to integrate diagram-type selection into automated pipelines or shell scripts without manual web interaction.

Rendering the Final Diagram

After selecting a scenario recipe, feed the generated prompt to the appropriate renderer. The guide ensures the selected diagram type supports the required evidence contract and automatically applies the correct visual preset.

# Render using the Architecture renderer as suggested by the guide

archify render --type architecture --input my-deps.json --output deps.svg

The --type parameter accepts the renderer identifier returned by the guide (one of: architecture, workflow, sequence, data-flow, lifecycle). The resulting diagram conforms to the constraints validated by the scenario recipe selected in the previous steps.

Summary

• Archify's scenario guide bridges the gap between design intent and technical implementation, residing in docs/guide.html and built by scripts/build-guide.mjs.
• Dual interfaces support both interactive web users (https://tt-a1i.github.io/archify/guide.html) and CLI automation (node bin/archify.mjs guide).
• Five renderers are available: Architecture, Workflow, Sequence, Data-flow, and Lifecycle.
• Scenario recipes provide renderer recommendations, copy-paste prompts, and proof artifacts.
• Zero-dependency CLI commands documented in archify/SKILL.md allow headless operation for CI/CD pipelines.

Frequently Asked Questions

Where is the scenario guide source code located?

The interactive guide is generated from source data in the repository. The build script at scripts/build-guide.mjs compiles scenario recipes into the HTML interface found at docs/guide.html. You can view the raw recipes in the repository structure or use the hosted version at https://tt-a1i.github.io/archify/guide.html.

Can I use the scenario guide without opening a web browser?

Yes. The zero-dependency CLI supports headless operation. Run node bin/archify.mjs guide "<scenario>" --json to receive a JSON payload containing the recommended renderer and prompt. This approach is fully documented in archify/SKILL.md and requires no browser dependencies.

What diagram types can the scenario guide recommend?

The guide selects between five typed renderers: Architecture, Workflow, Sequence, Data-flow, and Lifecycle. Each renderer corresponds to a specific subdirectory in archify/renderers/ with its own README documenting supported evidence contracts and visual presets.

How do I render a diagram after the guide selects a type?

Use the archify render command with the --type flag set to the renderer identifier returned by the guide. For example, if the guide recommends the Architecture renderer, execute archify render --type architecture --input <file> --output <file.svg>. The guide-provided prompt ensures the input data structure matches the renderer's expectations.

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