How to Create Custom Recipes for Recurring Diagram Patterns in Archify

Custom recipes in Archify are JavaScript modules that define reusable diagram templates by binding a technical question to visual styling, required evidence, and a copy-ready LLM prompt.

Archify uses a recipe-driven architecture to generate architecture diagrams. Recipes live in archify/recipes/ and are catalogued in archify/recipes/scenarios.mjs. This guide shows you how to create, register, and publish your own custom recipes for any recurring diagram pattern.

Understanding the Recipe Schema

Each recipe is a plain JavaScript object with a strict schema enforced by the Archify loader. The core fields are:

• id – unique kebab-case identifier
• type – diagram mode: static, interactive, sequential, event-stream, or architecture
• title / question / summary – what the diagram explains
• useWhen / avoidWhen – guidance for when to apply this recipe
• include – array of evidence items the user must gather
• presentation – visual tuning: preset, motion, views
• prompt – the complete LLM prompt users copy and run
• en / zh – bilingual UI strings

Inspect existing recipes in archify/recipes/scenarios.mjs to see the schema in practice:

// https://raw.githubusercontent.com/tt-a1i/archify/main/archify/recipes/scenarios.mjs
export const SCENARIO_RECIPES = [
  // ... existing recipe objects
];

Step 1: Create Your Recipe File

Create a new .mjs file in archify/recipes/. Name it descriptively, e.g., cache-miss-pattern.mjs.

Structure your export to match this complete example:

// archify/recipes/cache-miss-pattern.mjs

export const cacheMissPattern = {
  id: "cache-miss-fallback",
  type: "event-stream",
  title: "Cache Miss & Fallback Flow",
  question: "How does a request fall back from Redis to the database when the cache misses?",
  summary: "Request checks Redis; on miss, queries database, populates cache, returns result.",
  useWhen: [
    "Explaining cache-miss handling",
    "Documenting fallback strategies",
    "Onboarding new team members on caching layers"
  ],
  avoidWhen: [
    "No caching layer exists",
    "Cache is strictly pass-through"
  ],
  include: [
    "Request trace ID",
    "Cache key format",
    "Hit/miss determination logic",
    "Database query shape",
    "Cache population strategy"
  ],
  presentation: {
    preset: "default",
    motion: "sequential",
    views: 2  // before-fallback and after-fallback states
  },
  en: {
    title: "Cache Miss & Fallback Flow",
    question: "How does a request fall back from Redis to the database when the cache misses?"
  },
  zh: {
    title: "缓存未命中与回退流程",
    question: "请求在 Redis 缓存未命中时如何回退到数据库？"
  },
  prompt: `Generate a sequence diagram showing this cache-miss flow:

Participants: Client, API Gateway, Redis Cache, PostgreSQL Database

Flow:
1. Client → API Gateway: request with trace ID
2. API Gateway → Redis Cache: GET key "user:{id}"
3. Redis Cache → API Gateway: nil (cache miss)
4. API Gateway → PostgreSQL: SELECT * FROM users WHERE id = ?
5. PostgreSQL → API Gateway: user record
6. API Gateway → Redis Cache: SET key "user:{id}" EX 300
7. API Gateway → Client: response

Label all arrows with data payload samples.`
};

Key formatting rules for prompt:

• Use triple-backtick code fences with language hints
• Prefer AsciiDoc PlantUML or Mermaid syntax for universal compatibility
• Include concrete examples (IDs, key patterns, field names) so the LLM generates specific output

Step 2: Register in the Central Catalog

Open archify/recipes/scenarios.mjs and import your new recipe:

// archify/recipes/scenarios.mjs

// Existing imports
import { apiGatewayPattern } from "./api-gateway-pattern.mjs";
import { authFlowPattern } from "./auth-flow-pattern.mjs";

// Your new import
import { cacheMissPattern } from "./cache-miss-pattern.mjs";

export const SCENARIO_RECIPES = [
  apiGatewayPattern,
  authFlowPattern,
  // Add your recipe here
  cacheMissPattern
];

The SCENARIO_RECIPES array is consumed by:

• scripts/build-start.mjs – generates docs/data/start-recipes.json
• scripts/build-guide.mjs – generates docs/data/guide-recipes.json
• The CLI (archify command) – loads recipes for interactive selection

Step 3: Rebuild Static Assets

Run the build scripts to regenerate the JSON data files that power the web UI:

# Regenerate start page recipe data

node scripts/build-start.mjs

# Regenerate guide page recipe data

node scripts/build-guide.mjs

These scripts parse SCENARIO_RECIPES, validate the schema (throwing on missing required fields), and write optimized JSON to docs/data/.

Step 4: Test in the Web UI

Launch the local interface to verify your recipe renders correctly:

# Serve docs/ directory (Python example)

cd docs && python -m http.server 8000

Then open:

• http://localhost:8000/start.html – recipe chooser with search/filter
• http://localhost:8000/guide.html – detailed recipe view with prompt copying

Verify:

Check	What to confirm
Title appears	Both en.title and zh.title render correctly
Question clarity	The question field is interrogative and specific
Evidence checklist	include items display as clickable checklist
Presentation controls	preset, motion, views populate the UI controls
Prompt copy	One-click copy button outputs the full prompt text

Step 5: Publish Your Custom Recipe

Commit and push your changes:

git add archify/recipes/cache-miss-pattern.mjs
git add archify/recipes/scenarios.mjs
git commit -m "feat(recipes): add cache-miss-fallback pattern"
git push origin main

If GitHub Pages is enabled, the site rebuilds automatically. Your custom recipe for recurring diagram patterns becomes available to all Archify users.

Advanced Recipe Patterns

Parameterized Recipes with Placeholders

For highly reusable patterns, use template syntax in prompt:

prompt: `Generate a ${diagramType} diagram for service ${serviceName} showing:
- Request rate: ${requestsPerSecond} rps
- P99 latency budget: ${p99Latency}ms
- Failure mode: ${failureScenario}`

Document these parameters in include so users know what values to substitute.

Multi-View Presentations

Set views: 2 or higher to generate comparable diagram states:

presentation: {
  preset: "dark",
  motion: "none",  // static comparison
  views: 2
}

The UI renders side-by-side panels with synchronized zoom/pan.

Summary

• Recipes are JavaScript modules in archify/recipes/ exporting a schema-compliant object
• Register via scenarios.mjs import and push to SCENARIO_RECIPES
• Rebuild with build-start.mjs and build-guide.mjs to update UI data
• Test locally at start.html and guide.html before committing
• Bilingual support requires en and zh sub-objects for all user-facing strings

Frequently Asked Questions

What happens if my recipe is missing a required field?

The build scripts throw a validation error with the specific missing field and the recipe id. Run node scripts/build-start.mjs to catch schema violations before committing.

Can I override an existing recipe without modifying core files?

Yes. Create a recipe with the same id and import it after the original in scenarios.mjs. Later entries overwrite earlier ones. For permanent forks, rename the id to avoid collisions.

How do I add a new diagram type not in the current five modes?

Archify's type values are hardcoded in the UI components. Adding a new mode requires updating docs/js/diagram-renderers/ and the schema validator in scripts/lib/validate-recipe.mjs. Start with the closest existing type and customize presentation.preset instead.

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