ERD & UML diagrams

How to draw and read the two diagram families software teams still use: entity-relationship diagrams for data (Chen, crow's foot, IDEF1X, and how each mark becomes a PostgreSQL constraint) and UML 2.5.1 for code (class, sequence, state machine, activity, use case, component and deployment diagrams), with the TypeScript each class-diagram symbol becomes and the Mermaid, PlantUML, DBML and D2 that draw them from text. Schema design itself is in DB design & schemas; system-level views (C4) are in Software architecture; the structures these diagrams usually depict are in Design patterns.

Which diagram

Pick the diagram from the question you need answered, and draw one question per diagram.

The strongest case against all of this: most teams don't use UML, and do fine. In Marian Petre's ICSE 2013 interview study of 50 professional developers, 35 used no UML at all, 11 used it selectively, 3 generated code from it, 1 drew it after the fact, and none used it wholeheartedly. The selective users drew class, sequence and activity diagrams, informally, to think and to explain. That is the defensible use: Martin Fowler's three modes are UML as sketch (to communicate; incomplete on purpose), as blueprint (complete enough to code from) and as programming language (executable models). Sketch by default, blueprint only at boundaries that are expensive to change (public APIs, schemas, protocols), and treat the third as a historical curiosity.

ERD levels

The same model is drawn at three levels of detail for three audiences. Most arguments about "the ERD" are two people looking at different levels.

Say every relationship as two sentences, one per direction, with "each", a verb and a quantity: "each customer places zero or more orders" and "each order is placed by exactly one customer". If either sentence sounds wrong to the domain expert, the diagram is wrong.

ER notations

Look across vs look here. In crow's foot, UML and Chen's 1:N, the mark at an entity's end tells how many of that entity relate to one instance on the other end: read from the far entity, across the line. Chen's (min,max) is the opposite: the pair beside an entity says how many times that entity takes part in the relationship. Customer (0,N) and Order (1,1) say the same thing as crow's foot ||──o<, written on the other ends. Translating between the two families without flipping the ends is the most common ERD error there is.

Chen introduced the model in "The Entity-Relationship Model: Toward a Unified View of Data" (ACM TODS, March 1976). Gordon Everest drew the "inverted arrow", now called crow's foot, the same year, for maximums only; the circle and bar for minimums came later, and Information Engineering (James Martin and Clive Finkelstein) spread the full notation. Richard Barker's variant shipped with Oracle's CASE*Method (1990). IDEF1X became FIPS 184 in December 1993 and was withdrawn as a federal standard on September 2, 2008; IEEE 1320.2 carries it on.

Crow's foot

• The far end of the line answers the sentence: in customer ||──o< order, the o< at the order end reads "each customer places zero or many orders"; the || at the customer end reads "each order belongs to exactly one customer".
• Physical ERDs (ERwin, Mermaid, PlantUML) draw identifying relationships solid and non-identifying ones dashed. In Barker notation a dashed half means optional instead. Say which convention a diagram uses.
• Attributes go in the box, one per line, keys marked PK, FK, UQ. Foreign key columns belong on logical and physical diagrams only: in a conceptual model the line is the relationship.

Chen

Chen is verbose, and that is its use: relationship attributes, ternary relationships and weak entities are first-class, so it is the best notation for arguing about a conceptual model before tables exist. Nobody draws a 40-table physical schema in it.

Supertypes & subtypes

Enhanced ER (EER) adds specialization: a supertype with subtypes that inherit its attributes and relationships, drawn as lines from the supertype to a circle and on to each subtype.

Crow's foot tools draw subtypes as boxes nested in the supertype or joined by an "is a" line; UML uses generalization (hollow triangle) with {disjoint, complete} or {overlapping, incomplete}. The tables follow one of Fowler's three mappings:

Polymorphic references to "any subtype" are covered in DB design & schemas.

From ERD to tables

CREATE TABLE orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  -- ||..o{ : mandatory parent, non-identifying
  customer_id bigint NOT NULL REFERENCES customers,
  -- |o..o{ : optional parent
  ship_address_id bigint REFERENCES addresses,
  status text NOT NULL DEFAULT 'pending',
  placed_at timestamptz NOT NULL DEFAULT now()
);
 
-- ||--|{ : identifying; the parent's key is in the PK
CREATE TABLE order_items (
  order_id bigint REFERENCES orders ON DELETE CASCADE,
  line_no int,
  product_id bigint NOT NULL REFERENCES products,
  quantity int NOT NULL CHECK (quantity > 0),
  unit_price_cents int NOT NULL,
  PRIMARY KEY (order_id, line_no)
);

A foreign key enforces the parent side of a relationship. It can't enforce a minimum of one on the child side (|{: every order has at least one item), nor a mandatory 1:1 in both directions: those need a deferred constraint trigger or application code, and the diagram should say which.

UML at a glance

UML is an OMG standard: Booch, Rumbaugh and Jacobson merged their methods at Rational in 1994–96; OMG adopted UML 1.1 in November 1997, UML 2.0 in 2005, and the current version, 2.5.1, in December 2017 (ISO/IEC 19505:2012 is UML 2.4.1). UML 2.5 defines 14 diagram types.

Shared notation, valid on any diagram:

Class diagrams

Members

An attribute and a navigable association end are the same thing in the UML metamodel (a property). Convention: draw a line to classes that appear on the diagram, and write an attribute for value types (string, Money, OrderId). Drawing both is the same fact twice.

Relationships

• A composite's end has multiplicity 1 or 0..1, never more: a part has at most one owner.
• Don't draw aggregation. It has no defined semantics, so every reader supplies their own. Use composition when ownership matters, a plain association otherwise.
• Multiplicities are written at the far end and read across, like crow's foot: Order "*" → "1" Customer is "each order has one customer; each customer has many orders". Write one on every end: a missing one reads as 1 to some people and "unknown" to others.
• Navigability arrows say who holds the reference. Draw them when the direction is a design decision (it usually is), not on every line.
• Dependency stereotypes: «use», «create», «call», «instantiate», «import» (packages).
• Interfaces can be drawn as a class box with «interface», or as a ball (lollipop) the class provides and a socket (half circle) a class requires.

UML to TypeScript

The diagram above as code. TypeScript's types are structural, so a class that never says implements still satisfies an interface it matches: draw realization only for contracts you declare on purpose.

// «enumeration»: a union of literals (or an enum)
type OrderStatus =
  | "Pending" | "Paid" | "Shipped" | "Canceled";
 
// «interface»: no runtime trace; checked by shape
interface PaymentGateway {
  charge(m: Money): Receipt;
}
 
// realization: `implements` makes the contract explicit
class StripeGateway implements PaymentGateway {
  constructor(private readonly apiKey: string) {}
  charge(m: Money): Receipt {
    return callStripe(this.apiKey, m);
  }
}
 
class OrderLine {
  constructor(
    private qty: number,
    private unitPrice: Money,
    readonly product: Product, // association, 1
  ) {}
  subtotal(): Money {
    return times(this.unitPrice, this.qty);
  }
}
 
class Order {
  // composition: created here, never handed out to keep
  readonly #lines: OrderLine[] = []; // 1..* {ordered}
  private status: OrderStatus = "Pending";
 
  private constructor(
    private readonly id: OrderId, // {readOnly}
    private customer: Customer, // association, 1
  ) {}
 
  // underlined in UML: a static (class-scope) member
  static create(c: Customer): Order {
    return new Order(newId(), c);
  }
 
  // derived (/total): computed, not stored
  get total(): Money {
    return sum(this.#lines.map((l) => l.subtotal()));
  }
 
  add(p: Product, qty: number): void {
    this.#lines.push(new OrderLine(qty, p.price, p));
  }
 
  // dependency «use»: a parameter, not a field
  pay(gw: PaymentGateway): void {
    // the 1..* lower bound is an invariant to check
    if (this.#lines.length === 0) throw new Error("empty");
    gw.charge(this.total);
    this.status = "Paid";
  }
}

Sequence diagrams

• One diagram per scenario; the happy path first, then one diagram per interesting failure.
• Name participants after roles in the design (:OrderService), not after deployment units, unless the diagram is about deployment.
• Leave out getters and trivial calls. A sequence diagram that shows every line of code is the code, drawn worse.
• Async is the point of most sequence diagrams worth drawing: show who waits, who doesn't, and where a reply can be lost.

State machine diagrams

The UML state machine is David Harel's statechart (1987) with object-oriented semantics. XState implements statecharts for TypeScript with the same vocabulary (entry/exit actions, guards, delayed transitions, parallel states, history). A plain reducer is enough until timers, nesting or parallel regions appear; the Recipes show one.

Activity diagrams

• Semantics are token flow, like a Petri net: a join waits for a token on every incoming flow, a merge passes each token straight through. A merge where a join was meant runs the next step twice.
• Every decision's guards must cover every case, and must not overlap; add [else].
• For processes owned by the business (approvals, handoffs, SLAs), BPMN 2.0 (OMG 2011, ISO/IEC 19510:2013) has richer events and gateways and is what business analysts read. Activity diagrams fit software workflows; a plain flowchart fits a slide.

Use case diagrams

The diagram is a table of contents. The requirements live in the written use cases: goal, actors, preconditions, a numbered main success scenario and its extensions (Alistair Cockburn's format; a template is in the Recipes). Two smells: a use case per screen or per CRUD operation (functional decomposition, not goals), and «include»/«extend» chains deeper than one level.

Component & deployment diagrams

C4 covers the same ground with fewer rules: a container diagram is roughly a component diagram plus a deployment diagram, drawn as labeled boxes with a legend. Use the UML forms when your tools and readers already speak UML, or when interface wiring (ball and socket) is the point. A deployment diagram in PlantUML is in the Recipes.

Other UML diagrams

Diagrams as code

GitHub renders fenced mermaid blocks in Markdown, issues and pull requests; PlantUML and D2 need a CI step, a server or an editor plugin. Render to SVG on the command line:

npx -p @mermaid-js/mermaid-cli mmdc -i erd.mmd -o erd.svg
java -jar plantuml.jar -tsvg deploy.puml
d2 --layout elk arch.d2 arch.svg
npx -p @dbml/cli dbml2sql schema.dbml --postgres -o out.sql

Diagrams from existing code and schemas:

Common mistakes

Recipes

ERD in Mermaid

Renders on GitHub as-is. Relationship tokens are the crow's foot ends; -- is identifying (solid), .. non-identifying (dashed).

erDiagram
  CUSTOMER ||..o{ ORDER : places
  CUSTOMER ||..o{ ADDRESS : has
  ADDRESS |o..o{ ORDER : "ships to"
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||..o{ ORDER_ITEM : "sold as"
 
  CUSTOMER {
    bigint id PK
    text email UK
    text name
  }
  ORDER {
    bigint id PK
    bigint customer_id FK
    bigint ship_address_id FK "nullable"
    text status
  }
  ORDER_ITEM {
    bigint order_id PK, FK
    int line_no PK
    bigint product_id FK
    int quantity
  }

Class diagram in Mermaid

$ after an operation marks it static, * abstract; cardinalities go in quotes beside the arrow.

classDiagram
  class PaymentGateway {
    <<interface>>
    +charge(m: Money) Receipt
  }
  class Order {
    -OrderId id
    -OrderStatus status
    +total() Money
    +add(p: Product, qty: number) void
    +pay(gw: PaymentGateway) void
    +create(c: Customer)$ Order
  }
  class OrderStatus {
    <<enumeration>>
    Pending
    Paid
    Shipped
    Canceled
  }
  Order "*" --> "1" Customer
  Order "1" *-- "1..*" OrderLine : lines
  OrderLine "*" --> "1" Product
  Order ..> PaymentGateway : «use»
  StripeGateway ..|> PaymentGateway

Sequence diagram in Mermaid

+ and - after an arrow open and close the target's activation bar.

sequenceDiagram
  participant B as Browser
  participant A as CheckoutApi
  participant S as OrderService
  participant G as Gateway
  participant Q as Queue
  B->>+A: POST /checkout
  A->>+S: placeOrder(cart)
  S->>S: validate(cart)
  S->>+G: charge(total)
  G-->>-S: result
  alt approved
    S-)Q: OrderPlaced
  else declined
    S-)Q: PaymentFailed
  end
  S-->>-A: order
  A-->>-B: 201 Created

State machine in Mermaid

stateDiagram-v2
  [*] --> Pending
  Pending --> Pending: pay [declined] / retry
  Pending --> Paid: pay [approved]
  Pending --> Canceled: cancel, after(30 min)
  Paid --> Shipped: ship
  Paid --> Canceled: cancel / refund
  Shipped --> Delivered: deliver
  Delivered --> [*]
  Canceled --> [*]
  Paid: Paid (entry / reserveStock)

State machine as a reducer

One case per state, one if per outgoing arrow; anything unhandled is ignored. Effects (refund, reserve stock, restart the 30-minute timer) run outside, from the old and new state.

type State =
  | "Pending" | "Paid" | "Shipped"
  | "Delivered" | "Canceled";
 
type Ev =
  | { type: "pay"; approved: boolean }
  | { type: "ship" | "deliver" | "cancel" | "timeout" };
 
export function next(s: State, e: Ev): State {
  switch (s) {
    case "Pending":
      // [declined]: self-transition, timer restarts
      if (e.type === "pay") return e.approved ? "Paid" : s;
      if (e.type === "cancel" || e.type === "timeout") {
        return "Canceled";
      }
      return s;
    case "Paid":
      if (e.type === "ship") return "Shipped";
      if (e.type === "cancel") return "Canceled"; // refund
      return s;
    case "Shipped":
      return e.type === "deliver" ? "Delivered" : s;
    default:
      return s; // final states accept nothing
  }
}

At least one child in PostgreSQL

|{ ("one or many") as a deferred constraint trigger: checked at commit, so the order and its items can be inserted in either order inside one transaction.

CREATE FUNCTION order_has_items() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  IF NOT EXISTS (
    SELECT 1 FROM order_items WHERE order_id = NEW.id
  ) THEN
    RAISE EXCEPTION 'order % has no items', NEW.id;
  END IF;
  RETURN NULL;
END $$;
 
CREATE CONSTRAINT TRIGGER order_needs_items
  AFTER INSERT ON orders
  DEFERRABLE INITIALLY DEFERRED
  FOR EACH ROW EXECUTE FUNCTION order_has_items();

Deleting the last item of an existing order needs a second trigger, on order_items for DELETE, that runs the same check against OLD.order_id.

ERD in DBML

For dbdiagram.io; @dbml/cli turns it into PostgreSQL DDL and back.

Table customers {
  id bigint [pk, increment]
  email text [unique, not null]
  name text
}
 
Table orders {
  id bigint [pk, increment]
  customer_id bigint [not null, ref: > customers.id]
  ship_address_id bigint [ref: > addresses.id]
  status text [not null, default: 'pending']
}
 
Table order_items {
  order_id bigint [ref: > orders.id]
  line_no int
  product_id bigint [not null, ref: > products.id]
  quantity int [not null]
 
  indexes {
    (order_id, line_no) [pk]
  }
}

ERD in PlantUML

Information Engineering notation; * marks a mandatory attribute by convention, -- separates the key.

@startuml
hide circle
skinparam linetype ortho
 
entity customers {
  * id : bigint <<PK>>
  --
  * email : text <<UQ>>
  name : text
}
 
entity orders {
  * id : bigint <<PK>>
  --
  * customer_id : bigint <<FK>>
  ship_address_id : bigint <<FK>>
}
 
customers ||..o{ orders : places
@enduml

Deployment diagram in PlantUML

@startuml
node "app-1" <<device>> {
  node "Bun 1.3" <<executionEnvironment>> {
    artifact "api.js" as api
  }
}
node "db-1" <<device>> {
  database "PostgreSQL 18" as pg
}
queue "orders" as q
 
api --> pg : TCP 5432
api --> q : AMQP
@enduml

Tables in D2

customers: {
  shape: sql_table
  id: bigint {constraint: primary_key}
  email: text {constraint: unique}
}
orders: {
  shape: sql_table
  id: bigint {constraint: primary_key}
  customer_id: bigint {constraint: foreign_key}
}
orders.customer_id -> customers.id

Use case template

Cockburn's fields, trimmed. The extensions are where the requirements hide.

Use case:     Place order
Primary actor: Customer
Scope:        Shop (the system)       Level: user goal
Stakeholders: Customer wants the goods at the shown price;
              Shop wants payment before shipping.
Precondition: the cart holds at least one item
Guarantees:   success: order Paid, stock reserved
              minimal: no charge without an order
Trigger:      Customer chooses "Check out"
 
Main success scenario
  1. Customer confirms the cart and shipping address.
  2. System prices the order and shows the total.
  3. Customer pays (include: Pay).
  4. System reserves stock and confirms the order.
 
Extensions
  2a. Customer enters a coupon (extend: Apply coupon).
  3a. Payment is declined: System keeps the order Pending
      and offers to retry; after 30 minutes it is Canceled.
  4a. An item went out of stock: System refunds and
      notifies the Customer.

Review checklist

[ ] title, scope, date and the question it answers
[ ] one notation; legend if anything is non-standard
[ ] every line labeled; every end has a multiplicity
[ ] cardinalities read aloud as two sentences each way
[ ] ERD level stated: conceptual, logical or physical
[ ] minimums of one: enforced, or not drawn as one
[ ] composition only where lifetimes are shared
[ ] sequence: one scenario; async drawn as async
[ ] state machine: states are waits, not steps
[ ] source stored next to the code, rendered in CI

References

• OMG UML 2.5.1 specification (opens in a new tab): the normative text, notation annexes included
• Chen: The Entity-Relationship Model, Toward a Unified View of Data (ACM TODS, 1976) (opens in a new tab): the original ER paper
• FIPS PUB 184: Integration Definition for Information Modeling (IDEF1X) (opens in a new tab): the IDEF1X standard, 1993
• Marian Petre: UML in Practice (ICSE 2013) (opens in a new tab): how 50 professional developers did and didn't use UML
• Martin Fowler: UmlMode (opens in a new tab): sketch, blueprint, programming language
• uml-diagrams.org (opens in a new tab): every UML 2.5 diagram and element with examples
• David Harel: Statecharts, a visual formalism for complex systems (1987) (opens in a new tab): the basis of UML state machines
• XState documentation (opens in a new tab): statecharts in TypeScript
• OMG BPMN 2.0 (opens in a new tab): business process notation
• C4 model (opens in a new tab): system context, container, component and code views
• Mermaid: entity relationship diagrams (opens in a new tab), class diagrams (opens in a new tab), sequence diagrams (opens in a new tab) and state diagrams (opens in a new tab): syntax references
• GitHub Docs: creating diagrams (opens in a new tab): where Mermaid renders on GitHub
• PlantUML (opens in a new tab) and its layout engines (opens in a new tab): Graphviz, Smetana and the rest
• DBML documentation (opens in a new tab): syntax for dbdiagram.io and @dbml/cli
• D2 documentation (opens in a new tab): the D2 language, SQL tables and sequence diagrams
• Pyreverse (opens in a new tab): UML from Python code