497: Diagrams we love

What It Covers

Joel Kenville and Adji Slater of Thoughtbot explore five diagram types — flowcharts, denormalized control flow trees, sequence diagrams, state machine diagrams, and dependency graphs — examining how each one surfaces hidden complexity, exposes untested code paths, and improves communication across development and design disciplines.

Key Questions Answered

• •Denormalized Control Flow Trees: Convert standard control flow diagrams into trees by never merging branches back together. Each downstream decision point gets duplicated across every branch. This makes combinatorial path explosions visually obvious — two independent inline conditionals in Ruby produce four distinct code paths, revealing untested scenarios that a classic merged flowchart would obscure entirely.
• •Flowcharts as Test Maps: Structure flowcharts with a single entry state at the top and all terminal states at the leaf nodes. Every leaf node maps directly to a required unit test. This technique works in commit messages using ASCII art flowchart tools, giving reviewers an immediate visual inventory of what test coverage the code demands.
• •Sequence Diagrams for Multi-Party Auth Flows: Use sequence diagrams specifically when three or more actors exchange messages — client, server, and a third-party OAuth provider. Diagramming each round trip explicitly uncovers overlooked server-client exchanges that developers mentally glossed over, answering the concrete question: how did the server know that client action occurred?
• •State Machine Diagrams Across Disciplines: Map UI components as state machines — listing every state, every user action, and every transition arrow — to force conversations about error states, loading states, and blur events before writing code. Sitting with a designer to build this collaboratively converts vague product requirements into a structured, shared decision record that resolves edge cases upfront.
• •LLM-Generated Mermaid Diagrams as Code Lenses: Prompt an LLM to generate Mermaid diagrams scoped by model and depth — for example, an ERD starting from the User model at depth two, or a call graph tracing a function three levels deep. GitHub natively renders fenced Mermaid blocks in PRs with pan and zoom, making complex changes scannable without prose explanation.