Mermaid Class Diagrams and ER Diagrams: A Beginner's Guide

Class diagrams and entity-relationship (ER) diagrams are essential tools for software architects and database designers. They visualize the structure of a system, showing how entities relate to one another. Mermaid makes creating these diagrams surprisingly simple, turning complex visual modeling into readable text.

This guide walks you through both diagram types from the ground up, with practical examples you can use immediately.

Why Use Mermaid for Structural Diagrams?

Traditional modeling tools like Enterprise Architect or Visio are powerful but cumbersome for quick documentation. Mermaid offers a lightweight alternative:

• Version control friendly: Diagrams live as text in your repository
• Fast iteration: Rename a class or add a field in seconds
• Documentation-native: Embed diagrams directly in READMEs and wikis
• Collaboration-ready: Review diagram changes in pull requests just like code

Class Diagrams in Mermaid

Class diagrams model the static structure of a system—classes, their attributes, methods, and the relationships between them.

Basic Syntax

A class diagram starts with the classDiagram keyword:

classDiagram
    class User {
        +String id
        +String email
        +String name
        +login()
        +logout()
    }

Visibility Modifiers

Mermaid follows standard UML visibility notation:

Relationships Between Classes

classDiagram
    User "1" --> "*" Order : places
    Order "1" --> "*" OrderItem : contains
    Customer --|> User : inherits

Cardinality

Multiplicity labels define how many instances participate in a relationship:

classDiagram
    Company "1" --> "1..*" Employee : hires
    Department "1" --> "0..*" Project : manages

A Complete Example

classDiagram
    direction LR
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +fetch()
    }
    class Cat {
        +String color
        +climb()
    }
    Animal <|-- Dog
    Animal <|-- Cat

Entity-Relationship Diagrams in Mermaid

ER diagrams model the logical structure of databases—entities, their attributes, and the relationships between them.

Basic Syntax

An ER diagram starts with the erDiagram keyword:

erDiagram
    CUSTOMER {
        string id PK
        string email
        string name
    }
    ORDER {
        int id PK
        date created_at
        float total
    }
    CUSTOMER ||--o{ ORDER : places

Attribute Types and Keys

Relationship Cardinality

Mermaid ER diagrams use Crow's Foot notation:

A Complete Database Schema Example

erDiagram
    USER {
        int id PK
        string email UK
        string password_hash
        datetime created_at
    }
    PROFILE {
        int id PK
        int user_id FK
        string bio
        string avatar_url
    }
    POST {
        int id PK
        int author_id FK
        string title
        text content
        datetime published_at
    }
    COMMENT {
        int id PK
        int post_id FK
        int author_id FK
        text body
        datetime created_at
    }
    USER ||--o| PROFILE : has
    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : receives
    USER ||--o{ COMMENT : writes

Best Practices

1. Start simple: Model the core entities first, then add attributes and relationships
2. Use consistent naming: Stick to either snake_case or CamelCase across the diagram
3. Label relationships clearly: A named association (places, manages) is clearer than an unnamed line
4. Control direction: Use direction LR or direction TB to keep diagrams readable
5. Group related classes: Use namespaces or color coding for large diagrams

Common Pitfalls

• Over-modeling early: Don't add every field on the first draft. Start with keys and critical fields
• Ignoring cardinality: Wrong multiplicity leads to incorrect database schemas
• Tangled layouts: Large diagrams without direction control become unreadable
• Missing keys: Always mark primary keys explicitly to keep the schema clear

Conclusion

Class diagrams and ER diagrams are foundational to good software and database design. Mermaid removes the friction of traditional modeling tools, letting you focus on structure rather than layout. Whether you are sketching a new microservice architecture or documenting an existing database, Mermaid's text-based approach keeps your diagrams maintainable and reviewable.

Need to export your Mermaid diagrams for a presentation or document? Use Mermaid2img to generate high-quality PNG, SVG, or PDF files in one click.