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

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). 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 consumes 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:

# 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:

   # 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 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:

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:

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:

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.

Summary

• The Archify scenario guide resides in 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). This bilingual markdown file encodes the "question → renderer → evidence" mappings that both the CLI and the generated guide.html page consume. The build script 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).

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