Mermaid reusable diagram components: snippets and templates

Teams that diagram frequently discover they're repeating the same patterns: the same authentication flow in five documents, the same microservice architecture in ten Readmes, the same database schema in three design docs. Like code, diagrams benefit from the DRY principle—write once, reuse everywhere.

Mermaid diagrams are text, so they're perfect for templating. A shared library of diagram components—subgraphs, flowchart patterns, sequence templates—saves your team time and ensures consistency across all your documentation.

Why reusable diagram components matter

When diagrams are scattered across Notion, GitHub, Confluence, and design docs with no shared source:

• Inconsistency — the auth flow looks different in every document
• Maintenance debt — update the pattern once, update it in 20 places
• Lost context — new contributors can't find example diagrams to copy
• Duplicated effort — teams reinvent the wheel repeatedly

A centralized diagram library flips this:

• Single source of truth — one auth flow diagram, used everywhere
• Fast onboarding — new contributors copy a template and tweak it
• Consistency — all flowcharts follow the same node style and naming
• Collaboration — teams review and refine patterns together

Creating reusable flowchart patterns

Start by identifying the flowcharts your team repeats most. Common ones:

• Decision flows — "should we cache this?"
• Error handling — "retry logic for API calls"
• Approval workflows — "PR → review → merge"
• State machines — "user signup → activation → onboarding"

Here's a template for a generic approval workflow:

flowchart TD
    A["📥 Request created"]
    B{"Assigned\nreviewer?"}
    C["⏳ Waiting for review"]
    D{"Approved?"}
    E["❌ Rejected"]
    F["✅ Approved"]
    G["🚀 Applied"]
    
    A --> B
    B -->|no| A
    B -->|yes| C
    C --> D
    D -->|no| E
    E --> A
    D -->|yes| F
    F --> G

This pattern can be forked for code reviews, design reviews, access requests, or feature approvals. The core flow stays the same; only the labels change.

Key for reuse: use descriptive node IDs and avoid text repetition in edge labels. This makes copy-paste-and-edit faster.

Building a sequence diagram library

Sequence diagrams are even more reusable because they model interactions, not specific tools. A generic "request-response" template applies to REST, gRPC, GraphQL, webhooks, and more:

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database
    
    C->>S: request (auth token)
    S->>S: validate token
    S->>DB: query
    DB-->>S: result
    S->>S: transform
    S-->>C: response (200)

Reuse this for:

• OAuth flows — Client = third-party app, Server = your auth service
• GraphQL queries — Client = frontend, Server = API gateway, DB = data layer
• Webhook processing — Client = external service, Server = your webhook handler

Here's a more specific template for async job processing:

sequenceDiagram
    participant C as Client
    participant Q as Job Queue
    participant W as Worker
    participant DB as Database
    
    C->>Q: enqueue job
    Q-->>C: job ID (async)
    Q->>W: deliver job
    W->>DB: process + update
    DB-->>W: ack
    W->>Q: mark complete
    C->>Q: poll status (optional)
    Q-->>C: complete

Template this, and every async job doc in your codebase can start from the same structure.

Building reusable architecture blocks

Complex systems repeat: API gateways, microservices, databases, caches, message queues. Instead of redrawing, create named subgraph templates:

graph LR
    subgraph A["🔐 Authentication"]
        Auth["OAuth/OIDC<br/>Server"]
        Cache["Token<br/>Cache"]
    end
    
    subgraph B["📡 API"]
        GW["API<br/>Gateway"]
        Rate["Rate<br/>Limiter"]
    end
    
    subgraph C["💾 Data"]
        DB["PostgreSQL"]
        Idx["Search<br/>Index"]
    end
    
    User["👤 Client"]
    User -->|login| Auth
    Auth -->|validate| Cache
    User -->|request| GW
    GW -->|rate-limit| Rate
    GW -->|query| DB
    DB -->|sync| Idx

Save this as a base template for your microservice architecture. Each team can:

1. Copy the template
2. Rename the subgraphs (replace "Authentication" with your service name)
3. Add service-specific details inside each subgraph
4. Keep the overall structure consistent

Creating a team diagram repository

The best teams maintain a docs/diagrams/ directory with templates:

docs/
  diagrams/
    flowchart-approval.mmd           # Generic approval workflow
    flowchart-error-handling.mmd     # Retry + circuit breaker
    sequence-api-request.mmd         # Request-response template
    sequence-async-job.mmd           # Queue → worker
    architecture-base.mmd            # Service layout template
    api-auth-flow.mmd                # OAuth/JWT flow
    database-schema.mmd              # ER diagram template
    cicd-pipeline.mmd                # Build → test → deploy
    README.md                        # How to use these templates

Include a README.md that explains each template:

# Diagram Templates

## Flowchart Approval
Use for any sequential approval process (PR reviews, design reviews, etc.).
**Base template:** `flowchart-approval.mmd`

1. Copy the template into your doc
2. Replace stage names (e.g., "Request" → "Design Review")
3. Adjust decision logic if needed

**Examples:**
- docs/feature-gates.md
- docs/access-requests.md
- docs/vendor-evaluation.md

Collaboration workflow with reusable components

On MermaidCreator, teams can:

1. Create a diagram in the visual editor
2. Export as Mermaid to get the source code
3. Commit it to docs/diagrams/ with a descriptive name
4. Link to it in team docs (raw GitHub links work)
5. Fork it by copy-pasting the Mermaid into a new diagram and tweaking labels/colors

Example: a team member needs an API flow diagram. Instead of starting blank:

1. Find docs/diagrams/sequence-api-request.mmd in GitHub
2. Copy the Mermaid source
3. Paste into MermaidCreator
4. Tweak labels for their use case
5. Export and commit to their PR

This saves 10–15 minutes per diagram.

Standardizing diagram style across your library

Make all diagrams look cohesive by establishing conventions:

• Node naming — use consistent prefixes for node types (e.g., Auth_, DB_, Queue_)
• Icon/emoji usage — 🔐 for auth, 💾 for data, 🚀 for deployment (see examples above)
• Color scheme — if using Mermaid themes, standardize on one theme repo-wide
• Text length — keep node labels under 20 chars to prevent layout issues
• Hierarchy — use subgraphs for logical grouping (systems, layers, swimlanes)

Using templates in documentation

Link templates from your docs so readers know they exist:

### Authentication Flow

See the [authentication flow diagram](../diagrams/api-auth-flow.mmd) 
for how tokens are issued and validated.

For variations on this pattern, check [our diagram library](../diagrams/README.md).

This trains your team to look for patterns instead of redrawing.

Common templates by diagram type

Type	Template	Reuse Count
Flowchart	Approval workflow, error handling, state machine	5–10 per workflow type
Sequence	API request, async job, webhook	3–8 per interaction pattern
Architecture	Microservice layout, API gateway + services	1–2 per project (cloned frequently)
ER	Core schema + extensions	1–2 per database design
Gantt	Sprint planning, project timeline	1–2 per release cycle
State	User lifecycle, order status	1–3 per domain entity

FAQ

Should we version control diagram templates?
Yes. Keep them in git so your team can review and improve them together. Link to specific commits or branches in documentation.

Can we enforce a template in pull requests?
Not natively in Mermaid, but you can use a GitHub Action to check that PRs modifying architecture include a diagram, or that diagrams match a naming convention.

How do we know when to extract a new template?
If the same diagram pattern appears in 3+ places, extract it. If your team keeps copy-pasting the same Mermaid, it's a template.

Can templates include variables (like placeholders)?
Not natively. Mermaid is static text, so variables must be replaced manually. If you need dynamic templates, consider a templating engine (Handlebars, etc.) as a pre-build step—but keep it simple for now.

Start building your diagram library today. Use the MermaidCreator editor to draft your first template, then commit it to a docs/diagrams/ folder so your team can discover and reuse it.