# How to Create Custom Recipes for Recurring Diagram Patterns in Archify

> Learn to create custom recipes for recurring diagram patterns in Archify. Define reusable templates using JavaScript modules for efficient diagram generation and analysis.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-05

---

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

```javascript
// 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:

```javascript
// 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:

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/docs/data/start-recipes.json)
- **`scripts/build-guide.mjs`** – generates [`docs/data/guide-recipes.json`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

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

```bash

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

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

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/start.html) and [`guide.html`](https://github.com/tt-a1i/archify/blob/main/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.