Executive Summary

Diagram Recipes: BOTG Technical Playbook Standard

TL;DR

• Six diagram types cover every architectural concern — pick 4–6 per playbook, always include system architecture.
• Each type has a defined purpose: trust zones, critical flows, fallback paths, data relationships, security boundaries, and change-impact mapping.
• Visual semantics are part of the standard: red for dangerous nodes, green for safe — non-negotiable.
• A known set of Mermaid syntax pitfalls will silently break renders; preempt them with the gotchas checklist.
• When a diagram fails, debug at mermaid.live — the CLI hides the error line in stderr.

Context

The BOTG AI knowledge base requires consistent, decision-grade technical diagrams across all playbooks. A standardised set of six Mermaid diagram recipes — rendered automatically via assets/diagram_renderer.py — ensures every playbook communicates architecture, security, and data flow in a uniform visual language. This document is the authoritative reference for authors producing or reviewing those playbooks.

Key Findings

• Six canonical types exist, each scoped to a specific question: What are the trust zones? What is the critical flow? Where does the system degrade? What does the schema look like? Where are the security boundaries? What breaks if I change this file?
• System architecture is mandatory for every playbook; all other types are situational.
• Sequence diagrams outperform flowcharts when event ordering matters (e.g., chat requests, checkout, file uploads) — but colons in message labels will silently break them.
• Security surface diagrams carry intentional visual weight: red/green node styling is a design requirement, not decoration. It makes trust boundaries immediately auditable.
• File dependency maps should show meaningful edges only — exhaustive connection mapping reduces rather than improves clarity.
• Seven documented syntax gotchas (colons, apostrophes, <br> vs <br/>, hyphens in node IDs, ER field type formatting, style ordering, subgraph title quoting) account for the majority of render failures.

Recommendations

1. Enforce the 4–6 diagram minimum per playbook at the review stage; reject submissions missing the system architecture diagram.
2. Distribute the gotchas checklist as a pre-commit reference — syntax errors caught before mmdc run cost nothing; those caught after cost iteration cycles.
3. Standardise the security surface diagram across all playbooks with trust boundaries, not only those flagged as security-sensitive — normalising the visual makes anomalies obvious.
4. Restrict sequence diagrams to the single most important flow per playbook; using them for secondary flows dilutes their signal.

Next Steps

• Embed the gotchas checklist into the PR template for playbook submissions.
• Confirm diagram_renderer.py applies BOTG styling automatically so authors do not manage styles manually.
• Audit existing playbooks for missing system architecture or security surface diagrams and backfill.
• Validate all six recipe templates render cleanly in the current mmdc version and update if syntax has drifted.

Mermaid

Diagram Authoring Pipeline

One developer selects a recipe template, writes Mermaid syntax, and the engine validates and renders it into assets embedded in technical playbooks.

Diagram Request Lifecycle

Shows the authoring and debugging flow from template selection through rendering, including the fallback to mermaid.live when the engine fails.

Auth Security Surface

Highlights trust boundaries between scoped and privileged clients, making RLS policy enforcement and bypass paths immediately visible to developers and auditors.

User Guide

Diagram Recipes User Guide

Quick Start

You have a new playbook to document. Here’s the fastest path from blank page to a rendered diagram:

1. Choose a diagram type from the six options below — every playbook gets at least a system architecture diagram.
2. Copy the matching Mermaid template from the How To sections.
3. Replace the placeholder labels with your real component names.
4. Render it by running assets/diagram_renderer.py — this applies BOTG theming automatically.
5. If it fails, paste your code into mermaid.live to find the exact breaking line.

Aim for 4–6 diagrams per playbook. More than that and the reader stops reading them; fewer and the playbook leaves critical structure invisible.

Features

All six types render with automatic BOTG styling when processed through assets/diagram_renderer.py.

How To: Create a System Architecture Diagram

Use this for: Every playbook, without exception. It shows trust zones at a glance — browser, server, database, and external services.

Layout rule: Client at the top, server middleware in the middle, data and external services at the bottom. Use subgraphs to draw the trust zone boundaries.

[Screenshot: Rendered system architecture diagram showing browser at top flowing down through API routes into the database and external service layers]

Tips:

• Name each subgraph after the real trust zone, not a generic label.
• Every arrow crossing a subgraph boundary is a potential security concern worth noting in your playbook text.

How To: Create a Request Lifecycle Diagram

Use this for: The single most important flow in your app — a chat request, a checkout, a file upload. Reach for a sequence diagram any time order matters more than structure.

[Screenshot: Rendered sequence diagram showing the left-to-right participant lanes and numbered message arrows]

Tips:

• Keep participants to five or fewer — add more and the diagram becomes hard to scan.
• Use -->> (dashed arrow) for responses to visually separate calls from replies.
• Never use a colon inside a message label. Mermaid treats it as a separator and the diagram will break. Write “with” or “plus” instead — for example, POST with auth header rather than POST: auth header.

How To: Create a Retrieval / Fallback Ladder

Use this for: Systems with multi-tier fallbacks — RAG pipelines, cache hierarchies, retry chains. This diagram surfaces degradation paths that are easy to miss in code review.

[Screenshot: Rendered fallback ladder showing diamond decision nodes branching into fallback paths that reconverge at the result node]

Tips:

• Only create this diagram if your system genuinely has fallback tiers. Don’t invent complexity.
• Label the decision diamonds with the real condition your code checks.

How To: Create a Data Model Diagram

Use this for: Any schema with three or more related tables where relationships matter to the reader.

[Screenshot: Rendered ER diagram with entity boxes, field lists, and relationship lines connecting them]

Tips:

• Keep field names short — long names overflow the entity box.
• Quote relationship labels that contain spaces or special characters.
• Field types must be single words: uuid, text, int, jsonb, vector. Never write varchar(255) — Mermaid’s ER parser will reject it.

How To: Create an Auth / Security Surface Diagram

Use this for: Any codebase with trust boundaries worth highlighting — row-level security (RLS), service-role keys, signed URLs, or multi-tenant isolation.

The red/green color coding is intentional and part of the diagram’s message. Dangerous paths are red; enforced policies are green.

[Screenshot: Rendered security diagram with the privileged client node highlighted in red and the RLS policy node in green]

Tips:

• The dashed arrow (-.->) on the bypass path is deliberate — it signals “this route skips a control.”
• Apply style rules after the node has been defined in the diagram, not before, or the renderer will ignore them.
• This diagram doubles as an audit artifact. Name nodes after real functions and files so reviewers can trace them.

How To: Create a File Dependency Map

Use this for: Most playbooks. Shows developers exactly which files are affected when they change something.

Layout rule: Group by architectural layer — pages → components → API routes → libraries. Show meaningful dependencies only; don’t try to draw every import.

[Screenshot: Rendered file dependency map with four horizontal layer bands and arrows flowing downward through them]

Tips:

• If a file has more than five outgoing arrows, consider splitting the diagram into two focused views.
• This diagram is especially useful during onboarding — link it directly from your README.

FAQ

Do I need all six diagram types in every playbook? No. Every playbook needs a system architecture diagram. Beyond that, pick 3–5 types that genuinely fit your system. Don’t create a fallback ladder if your app has no fallbacks, or a data model diagram if you only have one table.

Can I add more than six diagram types? The six types cover the vast majority of what technical playbooks need. If you find yourself reaching for something outside this set, check whether one of the six can be adapted before inventing a new type.

How do I apply BOTG theming? Run your diagram source through assets/diagram_renderer.py. Theming is applied automatically — you don’t need to add style rules manually for the standard palette.

What file formats does the renderer produce? The renderer generates both SVG and PNG files. SVG is preferred for documentation that renders in a browser; PNG works better in environments that don’t support inline SVG.

Can I put a diagram inside the diagram — nesting subgraphs? Mermaid supports nested subgraphs in flowcharts, but deeply nested layouts tend to produce cramped output. Prefer a flat structure with clearly named subgraphs over deep nesting.

Where do generated diagram files go? Output lands in the generated/ directory as *.svg and *.png files, which your playbooks can then reference directly.

Troubleshooting

The renderer produces no output and exits silently. Run the renderer from the command line and check stderr — error messages are suppressed in normal output. Then paste your Mermaid source into mermaid.live, which highlights the exact line causing the failure.

My sequence diagram breaks with a cryptic parse error. The most common cause is a colon (:) inside a message label. Mermaid uses colons as separators in sequence diagrams. Replace every colon in your labels with “with,” “plus,” or a dash.

A node label with an apostrophe breaks the diagram. Wrap the label in double quotes inside the brackets: A["it's fine"] instead of A[it's fine].

Line breaks inside node labels aren’t rendering. Use <br/> with the closing slash. Plain <br> without the slash is not supported.

My style rule is being ignored. Check that the style line appears after the node it targets, not before. Mermaid processes style rules in order and will silently skip one that references a node it hasn’t seen yet.

A node ID with a hyphen is causing render issues. Hyphens in node IDs are not safe across all Mermaid renderers. Use underscores instead: my_node not my-node.

The ER diagram rejects a field type. All ER field types must be a single word. Replace varchar(255) with text, and timestamp with time zone with a custom short alias like timestamptz.

A subgraph title with spaces isn’t displaying correctly. Quote the title: subgraph Auth["Auth and Security"]. Unquoted titles with spaces can confuse the parser.

Wiki

Diagram Recipes

Overview

Diagram Recipes defines the six core diagram types used across technical playbooks in the Boots On The Ground (BOTG) AI knowledge base. Each diagram type serves a distinct purpose, and every playbook should include 4–6 of them. All diagrams are rendered with BOTG-themed styling via assets/diagram_renderer.py.

A system architecture diagram is mandatory for every playbook. The remaining five types are selected based on what the codebase actually needs to communicate.

Key Concepts

System Architecture

When to use: Every playbook, without exception. Gives the reader an immediate map of trust zones.

Layout rule: Client at the top → server/API middleware in the middle → data and external services at the bottom. Use subgraphs to draw boundaries.

The subgraph structure makes security perimeters immediately readable to both developers and auditors.

Request Lifecycle

When to use: For the single most important flow in the application — chat requests, checkout, file upload, etc. Sequence diagrams are preferred over flowcharts whenever ordering matters more than structure.

Standard participants: User → Client → API route → Database → External service.

The flow always progresses through authentication, state validation, external calls, result persistence, and response delivery.

Tip: Never use : inside message labels — Mermaid uses it as a separator. Substitute “with” or “plus”.

Retrieval / Fallback Ladder

When to use: Only when the system has genuine multi-tier fallbacks — RAG pipelines, cache layers, retry chains. Makes hidden degradation paths visible.

Skip this diagram for systems with a single straight-line retrieval path — it adds noise without value in that context.

Data Model

When to use: When the schema contains 3 or more related tables and those relationships are meaningful to the reader.

Tips:

• Quote relationship labels.
• Keep field names short.
• All field types must be a single word: uuid, text, int, vector, jsonb. Do not write varchar(255).

Auth / Security Surface

When to use: Whenever the codebase has meaningful trust boundaries — RLS policies, service-role keys, signed URLs, multi-tenant isolation.

Signature element: Dangerous nodes are styled red; safe/policy-enforcing nodes are styled green. This visual language is intentional and consistent across all BOTG playbooks.

The dashed bypass edge and red node together communicate risk without requiring any prose explanation.

File Dependency Map

When to use: Most playbooks. Helps developers understand the impact radius of any change before they make it.

Layout rule: Group by architectural layer — pages → components → API routes → lib. Show only meaningful edges, not every possible connection.

Mermaid Syntax Gotchas

These issues cause silent or cryptic render failures. Address them before submitting any diagram.

Debugging tip: If mmdc fails on a diagram, paste the source into mermaid.live. It surfaces the exact failing line — the CLI renderer hides this in stderr.

Renderer Integration

Diagrams are processed by assets/diagram_renderer.py, which applies BOTG-themed styling automatically. The pipeline flow is:

1. Developer authors Mermaid syntax, referencing templates from diagram_recipes.md.
2. The renderer parses and validates syntax.
3. The Mermaid engine generates SVG output (PNG also available).
4. Generated files are consumed by technical playbooks in the docs/ layer.

The recipe document and renderer script are the two root dependencies for all diagram output. Changes to either propagate to every generated asset.

Related Topics

• BOTG Technical Playbooks
• assets/diagram_renderer.py
• Mermaid.js documentation
• Row-Level Security (RLS) patterns
• RAG retrieval architecture

References

• Source: diagram_recipes.md — canonical definition of all six diagram types and syntax rules
• Renderer: assets/diagram_renderer.py — applies BOTG theming during SVG/PNG generation
• Live validator: mermaid.live — recommended debugging tool for syntax errors

Tech Spec

Diagram Recipes — Technical Specification

Context

The Diagram Recipes system is a standardised library of six Mermaid diagram types used across all Boots On The Ground (BOTG) AI technical playbooks. Diagrams are rendered via assets/diagram_renderer.py, which applies BOTG visual theming automatically. The goal is to give engineers and auditors a shared visual vocabulary — trust zones, data flows, change impact — without requiring bespoke diagramming per playbook.

The six types are: System Architecture, Request Lifecycle, Retrieval / Fallback Ladder, Data Model, Auth / Security Surface, and File Dependency Map.

Goals & Non-Goals

Goals

• Define a canonical syntax template and usage rule for each of the six diagram types.
• Prevent the most common Mermaid render failures via a documented gotcha list.
• Enforce a consistent layout convention (client → server → data; layers → libraries) across all playbooks.
• Make security boundaries immediately visible through red/green node styling.

Non-Goals

• Does not replace prose documentation — diagrams supplement, not substitute.
• Does not cover diagram types outside the six defined here (e.g. Gantt, pie charts).
• Does not govern playbook prose style or non-diagram assets.
• Does not define a CI lint pipeline for Mermaid syntax (noted as an open question).

Architecture

Key components:

Data & Schema

No runtime database is involved. The system operates on file-based inputs and outputs.

Diagram type registry (logical, enforced by convention):

Recommended total per playbook: 4–6 diagrams.

API Contracts

Renderer CLI — assets/diagram_renderer.py

The renderer is invoked as a script; there is no HTTP API.

python assets/diagram_renderer.py \
    --input  <path/to/source.md> \
    --output <path/to/generated/> \
    [--format svg|png|both]       # default: both
    [--theme botg]                 # default: botg

Inputs

Outputs

• One .svg and/or .png per fenced mermaid block found in the input file.
• Files are named <source_filename>_diagram_<index>.<ext>.
• Non-zero exit code + stderr message on any mmdc parse failure.

Error handling

If mmdc fails on a block, the renderer logs the offending block index to stderr and continues processing remaining blocks. Partial output is written. Callers should treat a non-zero exit code as a warning requiring human review, not a hard build failure (until a lint gate is added — see Open Questions).

Diagram Authoring Contracts

Request lifecycle — sequence flow

Syntax rules (enforced by convention, caught by mermaid.live on failure)

Security surface styling contract

Dangerous nodes (privileged clients, policy bypasses) must use:

style NodeId fill:#DC3545,color:#fff

Safe / policy-enforcing nodes must use:

style NodeId fill:#28A444,color:#fff

This is a visual contract, not optional decoration.

Rollout

Risks

Open Questions

1. Lint gate in CI — Should mmdc failures on changed markdown files block merge, or remain advisory? A hard gate prevents broken diagrams reaching docs but may slow authoring iteration.

2. Mandatory diagram set — Should playbooks covering auth surfaces be required to include a Security Surface diagram in addition to the mandatory System Architecture diagram?

3. PNG vs SVG as canonical format — Playbooks currently reference both. Should one be designated canonical for embedding, with the other as an export-only artefact?

4. Versioning of diagram_recipes.md — As Mermaid releases new syntax, who owns updating the templates and gotcha list, and what signals a breaking change to existing playbooks?

5. mermaid.live as fallback debug surface — Should the renderer emit a mermaid.live-encoded URL on failure to accelerate debugging, or is this out of scope for the renderer’s responsibility?