ER modeling for code reviewers
Reading crow's-foot like a database engineer.
TL;DR
If your diagram has a clear direction of time, reach for a sequence. If it has decision points, use a flowchart. If you find yourself drawing both, your diagram is doing too much — split it.
Why this matters
The single biggest mistake we see in code review is teams reaching for whichever diagram type they remember the syntax for. The result is a flowchart pretending to be a sequence diagram, or vice versa, and the reader spends 30 seconds decoding the metaphor before they even read the content.
The right diagram type makes the rest of the work easier. The wrong one makes everything harder.
A worked example
Suppose you're documenting an OAuth2 authorization-code flow. Each step is a message between actors, and the order is critical:
sequenceDiagram autonumber participant U as User participant W as Web app participant A as API participant D as Database U->>W: Click class="code-str">"Save" W->>A: POST /diagrams A->>D: INSERT INTO diagrams D-->>A: id = 4f2… A-->>W: 201 Created W-->>U: ✓ Saved
Now compare with the equivalent in a flowchart — same information, much harder to read because the time axis is gone:
Three rules of thumb
- Direction of time matters? Sequence diagram.
- Branching with decisions? Flowchart.
- Hierarchical relationships? Class or ER diagram.