Skip to main content

VeriMe Documentation Diagrams

This directory contains documentation about diagrams used in VeriMe documentation. All diagrams are created using Mermaid, which is built directly into Docusaurus for fast, reliable rendering.

Why Mermaid?​

  • ✅ Built into Docusaurus - No external dependencies or services required
  • ✅ Fast rendering - Diagrams render instantly in the browser
  • ✅ Reliable - No network calls to external services
  • ✅ Version controlled - Diagram source is in markdown files
  • ✅ Easy to edit - Simple, readable syntax
  • ✅ Multiple diagram types - Flowcharts, sequence, state, class, and more

Quick Start​

Simply add a code block with the mermaid language identifier to any markdown file:

```mermaid
flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
```

Diagram Location​

Diagrams are embedded directly in markdown files, not stored as separate .mmd files. This approach:

  • Keeps diagrams close to their context
  • Makes them easier to find and edit
  • Simplifies version control
  • Reduces file clutter

Example locations:

  • docs/api-reference/verification-check.md - API flow diagrams
  • docs/architecture/overview.md - System architecture and sequence diagrams
  • docs/guides/adding-diagrams.md - Tutorial and examples

Supported Diagram Types​

Flowcharts​

Show processes, decision trees, and API flows.

Use for:

  • API endpoint logic
  • Decision trees
  • Process workflows
  • Error handling flows

Sequence Diagrams​

Show interactions between actors and systems over time.

Use for:

  • User workflows
  • API call sequences
  • Service interactions
  • Authentication flows

State Diagrams​

Show lifecycle and state transitions.

Use for:

  • Voucher lifecycles
  • Verification states
  • Order workflows
  • State machines

Architecture Diagrams​

Show system structure and component relationships.

Use for:

  • System architecture
  • Component relationships
  • Service boundaries
  • Data flow

VeriMe Brand Colors​

Use these colors consistently across all diagrams:

Standard styling:

style NodeId fill:#f9f9f9,stroke:#141571,stroke-width:2px

CSS classes approach:

classDef primary fill:#f9f9f9,stroke:#141571,stroke-width:2px
classDef data fill:#7FB4F0,stroke:#141571,stroke-width:2px
classDef accent fill:#E79236,stroke:#141571,stroke-width:2px

class Node1,Node2 primary
class Database data

Mermaid Resources​

Official Documentation​

Tools​

Best Practices​

1. Keep Diagrams Focused​

  • One diagram = one concept
  • If a diagram becomes too complex, split it into multiple diagrams
  • Use notes to add context rather than adding more elements

2. Use Consistent Styling​

  • Apply VeriMe brand colors consistently
  • Use the same component shapes for the same types of elements
  • Maintain consistent arrow styles

3. Add Descriptive Labels​

Better than:

4. Choose the Right Diagram Type​

  • Flowcharts - When showing process flow and decisions
  • Sequence - When showing interactions over time
  • State - When showing lifecycle and transitions
  • Graph - When showing structure and relationships

5. Test Before Committing​

  1. Save your markdown file
  2. Run npm run start
  3. Navigate to the page
  4. Verify the diagram renders correctly
  5. Check that colors match VeriMe branding

Common Patterns​

API Decision Flow​

Service Architecture​

Lifecycle State Machine​

Troubleshooting​

Diagram Not Rendering​

  1. Check syntax - Use Mermaid Live Editor to validate
  2. Verify code fence - Must be ```mermaid (lowercase)
  3. Check for special characters - Escape quotes and brackets if needed
  4. Rebuild docs - Clear cache with npm run clear && npm run build

Styling Issues​

  1. Verify hex codes - Must include # prefix
  2. Check node IDs - Must match exactly (case-sensitive)
  3. Test incrementally - Add styling after diagram works
  4. Use classDef - For reusable styles across multiple nodes

Complex Diagrams​

If a diagram is too complex:

  1. Break it into multiple smaller diagrams
  2. Use subgraphs to organize elements
  3. Simplify by removing non-essential details
  4. Consider using multiple pages

Contributing​

When adding or updating diagrams:

  1. Embed in markdown - Don't create separate .mmd files
  2. Test thoroughly - Check rendering in both light and dark mode
  3. Use VeriMe colors - Apply brand colors consistently
  4. Add clear titles - Use descriptive node labels
  5. Document context - Add explanation text around diagrams

Examples​

See these pages for diagram examples:

Support​

For questions or issues: