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

> Explore Archify diagram types and scenario guide logic. Learn how Archify transforms natural language into typed diagrams using a registry and recommendation engine.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-31

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) | Scenario Guide UI and input collection |
| `scripts/build-guide.mjs` | `chooseRecipe()` implementation and recipe matching |
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | Runtime preset loading and feature enablement |
| [`archify/skill-release.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.