illustrate-complexitylisted

# Illustrate Complexity with Mermaid Diagrams **Use a Mermaid diagram whenever it communicates structure, flow, or relationships more clearly than prose.** The test: if the structure takes more than a paragraph to explain, and you keep wanting to say "and then" or "which connects to" or "if ...", it should be a diagram. Don't diagram for the sake of diagramming - use diagrams when they earn their keep. This applies wherever you are explaining something, not only when you are planning. ## When to Diagram - **Architecture & component relationships** - what depends on what, how things connect - **Sequences of interactions** - API calls, user flows, event chains, multi-step processes - **Data models & entity relationships** - schemas, table relationships, domain models - **State machines & decision logic** - status transitions, branching workflows - **Class/module structure** - inheritance hierarchies, interface contracts, module boundaries ## Choosing the Right Diagram Type Pick the diagram type that matches what you're communicating: | What you're showing | Diagram type | Mermaid syntax | |---|---|---| | Component dependencies, system topology, task breakdowns | **Flowchart** | `graph TD` or `graph LR` | | Request/response flows, API call sequences, multi-actor interactions | **Sequence diagram** | `sequenceDiagram` | | Database schemas, domain models, data relationships | **ER diagram** | `erDiagram` | | Inheritance, interfaces, module contracts | **Class diagram** | `c