# Documentation Diagramming Mermaid JS

> Imported TRAE skill from documentation/Diagramming_Mermaid_JS.md Use when this capability is needed.

- Skill: `tomevault-io/documentation-diagramming-mermaid-js` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-diagramming-mermaid-js`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-diagramming-mermaid-js/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-diagramming-mermaid-js

---


# Skill: Diagramming with Mermaid.js

## Purpose
To create complex diagrams (flowcharts, sequence diagrams, gantt charts, etc.) directly within Markdown files using a simple, text-based syntax. This ensures documentation and diagrams stay in sync with the code and are easily versionable via Git.

## When to Use
- When documenting system architecture, data flows, or complex logic
- When explaining authentication sequences (OAuth2, JWT)
- When defining project timelines or state machines
- To avoid using external binary image files for diagrams that change frequently

## Procedure

### 1. Basic Flowchart Syntax
Flowcharts represent processes or workflows.

```mermaid
graph TD
    A[Start] --> B{Is logged in?}
    B -- Yes --> C[Dashboard]
    B -- No --> D[Login Page]
    D --> B
```

### 2. Sequence Diagrams
Perfect for showing interactions between different services or components over time.

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant AuthServer
    participant Database

    User->>Frontend: Click Login
    Frontend->>AuthServer: POST /auth/login
    AuthServer->>Database: Query User
    Database-->>AuthServer: User Data
    AuthServer-->>Frontend: JWT Token
    Frontend-->>User: Show Dashboard
```

### 3. Entity Relationship (ER) Diagrams
Useful for documenting database schemas.

```mermaid
erDiagram
    USER ||--o{ POST : writes
    USER {
        string username
        string email
        string password
    }
    POST {
        string title
        string content
        datetime created_at
    }
```

### 4. State Diagrams
Best for documenting complex UI states or business logic transitions.

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Search clicked
    Loading --> Success: Data fetched
    Loading --> Error: Fetch failed
    Success --> Idle: Clear search
    Error --> Loading: Retry
```

## Best Practices
- **Keep it Simple**: Don't try to fit too much information into a single diagram. Break complex systems into multiple smaller diagrams.
- **Direction Matters**: Use `TD` (Top-Down) or `LR` (Left-to-Right) consistently based on what makes the flow easier to read.
- **Use meaningful labels**: Instead of `A --> B`, use `Start --> Process`.
- **Git Versioning**: Since Mermaid is text, you can see exact changes in diagrams during code reviews (diffs). Always prefer Mermaid over embedded screenshots of diagrams.

---
> Source: [Ditto190/crispy-nextjs-turborepo-monorepo](https://github.com/Ditto190/crispy-nextjs-turborepo-monorepo) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->