mermaid-builder

Mermaid Builder

Core Philosophy

Correctness: Follow Mermaid syntax rules strictly
Clarity: Diagrams communicate complex ideas simply
Simplicity: Avoid overloading with unnecessary detail
Modularity: Break complex diagrams into subgraphs

Critical: Label Quoting Rule

RULE: Wrap labels in double quotes if they contain spaces, special characters, or punctuation.

%% CORRECT - labels with spaces quoted
flowchart LR
    A["User Login"] --> B["Process Request"]
    C["Pay $100?"] --> D["Confirm (Yes/No)"]

%% WRONG - will fail to render flowchart LR A[User Login] --> B[Process Request]


**Must quote:** Spaces, special chars (`$%&`), punctuation (`:,;`), operators (`()[]`)
**Optional:** Simple alphanumeric (`Login`, `Process`, `Node1`)

**When in doubt, use quotes. It never hurts.**

## Quick Reference

### Flowchart Shapes

| Syntax | Shape |
|--------|-------|
| `["Text"]` | Rectangle |
| `("Text")` | Rounded |
| `{"Text"}` | Diamond (decision) |
| `[("Text")]` | Cylinder (database) |
| `(("Text"))` | Circle |

### Arrow Types

| Syntax | Type |
|--------|------|
| `-->` | Solid arrow |
| `---` | Solid line |
| `-.->` | Dotted arrow |
| `==>` | Thick arrow |
| `-->|Label|` | Arrow with label |

### Diagram Types

| Type | Declaration | Use Case |
|------|-------------|----------|
| Flowchart | `flowchart TD` | Processes, workflows, decisions |
| Sequence | `sequenceDiagram` | Component interactions, API flows |
| Class | `classDiagram` | OOP structure, models |
| State | `stateDiagram-v2` | State transitions |
| Gantt | `gantt` | Timelines, scheduling |
| ER | `erDiagram` | Database schema |
| Pie | `pie` | Proportional data |

**Directions:** `TB`/`TD` (top-down), `BT` (bottom-up), `LR` (left-right), `RL` (right-left)

See [references/diagram-examples.md](references/diagram-examples.md) for complete examples of each diagram type.

## Minimal Examples

### Flowchart

```mermaid
flowchart TD
    Start["Start"] --> Check{Valid?}
    Check -->|Yes| Process["Process"]
    Check -->|No| Error["Error"]
    Process --> End["End"]

Sequence

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

ER Diagram

erDiagram
    USER ||--o{ ORDER : "places"
    USER { int id PK string email }
    ORDER { int id PK int user_id FK }

Subgraphs for Organization

flowchart TD
    subgraph "Frontend"
        A["UI"]
    end
    subgraph "Backend"
        B["API"]
        C[("DB")]
    end
    A --> B --> C

Styling

flowchart TD
    A["Success"] --> B["Error"]

    classDef successStyle fill:#C8E6C9,stroke:#388E3C
    classDef errorStyle fill:#FFCDD2,stroke:#D32F2F

    class A successStyle
    class B errorStyle

Common Errors to Avoid

Error	Wrong	Correct
Unquoted spaces	`A[User Login]`	`A["User Login"]`
Invalid arrow	`A -> B`	`A --> B`
Unquoted special	`A[Cost: $100]`	`A["Cost: $100"]`
Missing bracket	`A["Node --> B`	`A["Node"] --> B`

Validation Checklist

Labels with spaces are quoted
Labels with special characters quoted
Brackets properly matched
Arrow syntax correct (--> not ->)
Node IDs unique and meaningful
Comments explain complex sections
Previewed without errors

Data Lineage Patterns

See references/data-lineage.md for:

ETL pipeline patterns
Multi-layer data architecture
Cross-system data flows
Database schema lineage
Streaming data lineage
Column-level lineage

Resources

Remember: The quoting rule is the #1 cause of Mermaid rendering failures. When in doubt, quote it.