Mermaid Diagram

Step 2: Read Documentation

Select the appropriate diagram type. Use built-in Mermaid knowledge first; if external documentation is needed and your environment provides it, fetch the up-to-date syntax reference.

Step 3: Generate Mermaid Code & Save Files

Generate the Mermaid code and save two files:

File 1: figures/<diagram-name>.mmd

The .mmd file contains only raw Mermaid code, no markdown fences.

File 2: figures/<diagram-name>.md

The .md file wraps the same Mermaid code in a mermaid code block for preview rendering, plus a short title and description.

Naming convention: use a descriptive kebab-case name derived from the request, such as auth-flow, system-architecture, or database-er.

Step 4: Verify Mermaid Syntax (MANDATORY)

Codex MUST verify the generated Mermaid code by running the Mermaid CLI (mmdc).

if command -v mmdc >/dev/null 2>&1; then
    mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent
    echo "Syntax valid — PNG rendered to figures/<diagram-name>.png"
else
    npx -y @mermaid-js/mermaid-cli@latest -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent
    echo "Syntax valid — PNG rendered to figures/<diagram-name>.png"
fi

If verification fails:

1. Read the error carefully
2. Fix the syntax issue in both .mmd and .md
3. Re-run verification
4. Repeat up to MAX_ITERATIONS

Step 5: Codex STRICT Visual Review & Scoring (MANDATORY)

After successful rendering, Codex MUST read the generated PNG and perform a strict review:

## Codex's STRICT Review of <diagram-name>

### What I See
[Describe the rendered diagram in detail]

### Files Generated
- `figures/<diagram-name>.mmd`
- `figures/<diagram-name>.md`
- `figures/<diagram-name>.png`

### STRICT VERIFICATION CHECKLIST

#### A. File Correctness
- [ ] `.mmd` contains valid Mermaid syntax
- [ ] `.md` wraps the Mermaid code in ```mermaid fences
- [ ] `.mmd` and `.md` contain identical Mermaid code
- [ ] Diagram renders without errors

#### B. Arrow Correctness Verification
- [ ] Every arrow points to the correct target

#### C. Block Content Verification
- [ ] Every block label is correct
- [ ] Every block contains the intended content

#### D. Completeness
- [ ] All required components are present
- [ ] All required connections are present
- [ ] Labels are meaningful and match the request

#### E. Visual Quality
- [ ] Layout is clean and readable
- [ ] Colors are professional
- [ ] Text is readable at normal zoom
- [ ] Spacing is balanced
- [ ] Data flow is understandable within 5 seconds

### Issues Found
1. [issue] -> [fix]

### Score: X/10

### Verdict
- [ ] ACCEPT
- [ ] FIX

If the verdict is FIX, apply corrections to both .mmd and .md, re-render, and re-review until ACCEPT or MAX_ITERATIONS is reached.

Step 6: Final Output Summary

When accepted, present:

Mermaid diagram generated successfully.

Files:
  figures/<diagram-name>.mmd
  figures/<diagram-name>.md
  figures/<diagram-name>.png

To re-render manually:
  mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png

Architecture Diagram Best Practices

When generating architecture-beta diagrams, apply these layout techniques for complex diagrams:

Use Junctions for Layout Control

Think of the diagram as an invisible grid. Use junction nodes as virtual anchor points on that grid to precisely control placement. This is especially useful when a direct edge produces unexpected positioning.

Instead of connecting services directly: