Archify Diagram Types and Scenario Guide Logic: A Complete Technical Breakdown

Archify converts natural-language descriptions into typed, self-contained diagrams by matching user input against a static diagram-type registry and a recipe-driven recommendation engine.

The Archify repository implements a structured approach to diagram generation that balances flexibility with discipline. At its core, the system uses a diagram-type taxonomy (DIAGRAM_TYPE_LABELS) to categorize visual output, while a scenario-guide recommendation engine ensures users receive the most appropriate diagram for their specific situation. This article examines the source code implementation of both systems and how they interact to produce bounded, reviewable diagrams.

Diagram Type Definitions in site-copy.mjs

The foundation of Archify's type system lives in scripts/site-copy.mjs. This file exports DIAGRAM_TYPE_LABELS, a static map that enumerates every supported diagram family.

Each entry in DIAGRAM_TYPE_LABELS contains:

• User-facing label — the display name shown in dropdowns and navigation
• Icon reference — visual identifier for the UI
• Short description — context explaining when to use this type
• Preset name — the runtime identifier used to load correct templates and validation rules

The supported diagram types include:

• workflow — process flows and state machines
• architecture — component relationships and system topology
• sequence — time-ordered interactions between entities
• signal-flow — event propagation and async tracing patterns
• blueprint — structural templates and design patterns
• editorial — narrative and explanatory visuals

This registry acts as the single source of truth. Both the CLI and web interface validate user selections against these keys before proceeding.

Scenario Guide Recommendation Engine

The Scenario Guide is Archify's intelligent assistant for diagram selection. Unlike manual type selection, the guide interprets natural-language descriptions and recommends the optimal diagram type automatically.

User Input Processing

The guide interface is defined in scripts/guide-template.html. When a user describes their situation—such as "Show an API request with JWT auth, a Redis cache miss, and async tracing"—the page collects this input and passes it to the recommendation logic.

Recipe Matching via chooseRecipe()

The core matching algorithm lives in scripts/build-guide.mjs. The exported function chooseRecipe() implements the following steps:

1. Parses the natural-language description for keywords and structural patterns
2. Queries the recipe catalog at archify/skill-release.json
3. Scores each recipe against the input based on evidence requirements and constraint matching
4. Returns the best-fit recipe with complete metadata

Each recipe in skill-release.json declares:

• diagram_type — the preferred type from DIAGRAM_TYPE_LABELS
• evidence_checklist — required data points that must be present
• usage_constraints — situations where this recipe should not apply
• prompt — a copy-ready template for CLI or LLM consumption

This bounded recipe approach guarantees that generated diagrams remain reviewable and traceable. The engine explicitly surfaces avoidance rules rather than silently failing.

Runtime Glue and Preset Loading

Once a diagram type is selected—whether by user choice or guide recommendation—the runtime must instantiate the correct environment.

scripts/start-template.html handles this initialization:

• Reads diagram_type from URL query parameters
• Looks up the corresponding preset via data-preset attributes
• Loads CSS/JS bundles specific to that diagram family
• Wires interactive features (navigation bar, export menu, motion controller) based on preset capabilities

The same preset system is used by the CLI. When a user runs archify --type <type>, the command validates against DIAGRAM_TYPE_LABELS, loads the matching Mermaid template, and applies type-specific validation rules.

Practical Usage Examples

CLI Workflow Generation

Generate a CI pipeline diagram directly from the terminal:

archify \
  --type workflow \
  --prompt "Show a CI pipeline that builds, tests, and deploys a Node.js service." \
  --output demo-workflow.html

The --type flag maps directly to DIAGRAM_TYPE_LABELS keys. The CLI validates the prompt against the recipe catalog and emits a self-contained HTML file.

Programmatic Guide Integration

Use the recommendation engine in your own tooling:

import { chooseRecipe } from './scripts/build-guide.mjs';

const description = 'Show an API request with JWT auth, a Redis cache miss, and async tracing.';

const { recipe, diagram_type, prompt } = await chooseRecipe(description);

console.log(`Recommended diagram type: ${diagram_type}`);
console.log(`Copy-ready prompt: ${prompt}`);

The returned diagram_type can be fed back into the CLI, while prompt provides a refined, evidence-backed input for LLM-based generation.

Key Implementation Files

File	Purpose
scripts/site-copy.mjs	Central DIAGRAM_TYPE_LABELS registry
scripts/guide-template.html	Scenario Guide UI and input collection
scripts/build-guide.mjs	chooseRecipe() implementation and recipe matching
scripts/start-template.html	Runtime preset loading and feature enablement
archify/skill-release.json	Bounded recipe catalog with evidence requirements

Summary

• Diagram types are centrally defined in DIAGRAM_TYPE_LABELS (site-copy.mjs), providing a consistent taxonomy across CLI and web interfaces
• Scenario guide logic uses chooseRecipe() (build-guide.mjs) to match natural-language input against the skill-release.json recipe catalog
• Bounded recipes ensure every recommendation includes evidence checklists, usage constraints, and a copy-ready prompt
• Preset loading (start-template.html) dynamically instantiates the correct runtime environment based on the selected diagram_type
• Both pathways—manual selection and guided recommendation—converge on the same validation and rendering pipeline

Frequently Asked Questions

What diagram types does Archify support?

Archify supports six core diagram types defined in DIAGRAM_TYPE_LABELS: workflow, architecture, sequence, signal-flow, blueprint, and editorial. Each type has dedicated presets, validation rules, and interactive features. The registry lives in scripts/site-copy.mjs and is referenced by both the CLI and web interface.

How does the Scenario Guide choose between diagram types?

The guide calls chooseRecipe() from scripts/build-guide.mjs, which parses the user's natural-language description and matches it against the recipe catalog in archify/skill-release.json. The engine scores recipes based on keyword presence, evidence requirements, and constraint satisfaction, then returns the highest-scoring match with its associated diagram_type.

Can I use the Scenario Guide logic in my own application?

Yes. Import chooseRecipe() directly from scripts/build-guide.mjs and pass it a description string. The function returns a structured object containing the selected diagram_type, full recipe metadata, and a prompt string ready for CLI or LLM consumption.

What makes Archify recipes "bounded"?

Each recipe in skill-release.json includes an evidence checklist (required data points) and usage constraints (situations to avoid). This design ensures generated diagrams are reviewable against objective criteria and prevents inappropriate type selection. The constraints are surfaced to users rather than enforced silently.

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