Diagrams as Code with Mermaid

Class and ER Diagrams for Schemas

Quick orientation: classDiagram models object structure — class attributes, methods, visibility, and type relationships in code. erDiagram models database schemas — tables, columns, primary/foreign keys, and crow's-foot cardinality. The same system often needs both: your User class might expose a logout() method the database has no concept of, while the users table carries created_at columns the domain model treats as plumbing. Don't force one diagram to do both jobs.

classDiagram

Keyword is classDiagram — no direction argument, layout is automatic. Define members inside curly braces or with colon notation:

classDiagram
    class User {
        +int id
        +String email
        -String passwordHash
        +login() bool
        +logout()
    }

The parser spots methods by () — no parentheses means attribute. Return types trail the closing paren: login() bool.

Visibility modifiers:

Append $ for static and * for abstract: getInstance()$, validate()*.

Relationship types:

Arrowhead points toward the parent: Animal <|-- Dog means Dog inherits from Animal.

Add multiplicity labels in quotes and a verb label after a colon:

Order "1" --> "*" LineItem : contains

Mark a class as an interface with a stereotype inside the class block:

class Publishable {
    <<interface>>
    publish()
    unpublish()
}

---

erDiagram

Switch keyword to erDiagram. Entity names are conventionally uppercase. Attribute blocks use type name [constraint] syntax:

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

Supported constraint tags: PK, FK, UK. Combine when needed (int id PK, FK) and add a trailing comment in double quotes: int id PK "auto-increment".

Cardinality is where most people stumble. Each relationship token has three parts:

ENTITY_A [left-marker][line][right-marker] ENTITY_B : "label"

Line type: -- for identifying (solid), .. for non-identifying (dashed).

Cardinality markers:

Read each side independently. USER ||--o{ ORDER : "places" — || on the User side (exactly one), o{ on the Order side (zero or more). One User places zero or more Orders.

The label after : is required — omitting it causes a parse error. Quote any label with spaces.

Test your cardinality recall before moving on:

---

Which one for which job?

• classDiagram: documenting code — domain models, service interfaces, library APIs.
• erDiagram: documenting storage — database schemas, migrations, data dictionaries.

They can and should coexist in the same docs. Different audiences, different jobs — don't force one to serve both.

---

Keeping both honest as the model changes

Diagrams drift. A few habits help:

1. Co-locate with the code they describe. An erDiagram lives in the same directory as your migrations. When a migration changes, the diagram is right there.

db/
├── migrations/
│   ├── 001_create_users.sql
│   └── 002_create_posts.sql
└── schema.md   ← erDiagram lives here

2. Keep entities flat. Show only columns worth explaining to a newcomer — audit timestamps and soft-delete flags can usually stay out.

3. Prefer two focused diagrams over one comprehensive one. When an entity grows past ~8 attributes, split into a relationship view and a full-attribute reference.

4. Use subgraphs in classDiagram to mark service boundaries — same technique as the flowchart submodule. Wrap related classes in a subgraph to show module ownership without drawing a line for every dependency.

5. Mermaid won't catch logical errors. You can write contradictory cardinality and it'll render both arrows without complaint. Cross-check tokens against your actual FK constraints before publishing.

---

Quick check

1. Write a classDiagram with Post, Author (one-to-many association), Comment (composition), and a Publishable interface that Post realizes.

2. Write the matching erDiagram with posts, users, and comments tables — mark PKs and FKs.

3. Express "a post has zero or more comments; a comment belongs to exactly one post" as a relationship token — write it from memory, then verify against the table.

State diagrams and Gantt charts are next — a shift from modeling structure to tracking flow over states and work over time.