Tame the spaghetti: flowchart mastery

A subgraph is three things: the keyword, an ID with an optional display title, and an end. Everything declared between them lives inside the box. Edges work exactly as before - including edges that cross the box wall, and edges attached to the subgraph ID itself.

flowchart LR
  subgraph src[Sources]
    ev[App events]
    crm[CRM export]
  end
  subgraph plat[Platform]
    ing[Ingestion] --> qa{Quality checks}
    qa -->|pass| dw[(Warehouse)]
  end
  subgraph cons[Consumers]
    bi[Dashboards]
    ml[ML features]
  end
  ev -->|stream| ing
  crm -.->|nightly| ing
  dw --> bi
  dw --> ml

• Always give the ID: subgraph src[Sources]. The ID (src) is how you draw edges to the whole zone later - src --> plat connects box wall to box wall.
• Declare inside, connect anywhere. A node's home is the subgraph where it is first declared. Cross-zone edges (like ev --> ing) are fine and normal.
• Nesting works: a subgraph inside a subgraph draws boxes within boxes - handy for a "Platform" zone containing "Streaming" and "Batch" sub-zones.

Each subgraph can set its own flow with a direction statement on its first line - a top-down zone inside a left-right diagram, for example:

• The catch (docs say so too): if any node inside the subgraph links to a node outside it, the subgraph's own direction is ignored and it inherits the parent flow. Design zones as units first, wire them second.
• When it shines: a wide LR pipeline with one tall TB zone for a decision ladder or an approval chain.

Subgraphs are a grouping tool, and groupings are claims: "these things belong together". Good claims to make:

• Ownership - one zone per team or system boundary. The best default for architecture diagrams.
• Lifecycle stage - raw / staged / served zones in a data platform.
• Trust boundary - inside the VPC vs outside; great for security conversations.

Bad claim: grouping by "stuff that happened to fit there". If you cannot name the zone in two words, it is not a zone. And 3-5 zones is the sweet spot - seven subgraphs is spaghetti with extra steps.

A classDef names a reusable style. A class statement (or the ::: shorthand right on a node) applies it. One definition, any number of nodes - exactly like CSS.

flowchart LR
  ev[App events]:::stream -->|stream| ing[Ingestion]
  crm[CRM export]:::batch -.->|nightly| ing
  ing --> dw[(Warehouse)]
  dw --> bi[Dashboards]
  class dw storage
  linkStyle 1 stroke:#F59E0B,stroke-width:3px
  classDef stream fill:#D6246E,color:#FFEFF5,stroke:#8E1146
  classDef batch fill:#FFEFF5,color:#8E1146,stroke:#D6246E
  classDef storage fill:#8E1146,color:#FFEFF5,stroke:#8E1146

Class names should name MEANINGS (stream, batch, storage, deprecated), never looks (pinkBox, dark2). If a color means two things in one diagram, it means nothing.

Mermaid v11.3+ added a second way to pick shapes: the @{ } attribute syntax. Instead of memorizing bracket gymnastics, you name the shape - and the catalog grew to 30+ shapes (see flowchart.html#expanded-node-shapes in the docs).

flowchart LR
  raw@{ shape: cyl, label: "Raw zone" } --> job@{ shape: rect, label: "Transform job" }
  job --> marts@{ shape: cyl, label: "Marts" }
  job --> rules@{ shape: hex, label: "Quality rules" }

• Handy names: cyl (database), diam (decision), stadium (start/end), hex (preparation), circle, rounded, rect.
• When to use which style: brackets for the daily six shapes (they type faster), @{ } when you need a shape brackets cannot make, or when generating mermaid programmatically.
• Quote the label inside @{ } - it is already a habit from Session 1, and here it is required whenever the label has spaces.

The click statement attaches a link (or a JavaScript callback) to a node. The pattern for links: click nodeId "https://..." "tooltip", with an optional _blank target at the end to open a new tab.

• Links: click dw "https://example.com/warehouse" "Open the docs" - the node becomes a hyperlink.
• Callbacks: click dw call myFunction() runs page JavaScript - for self-hosted pages and internal tools.
• The GitHub caveat: GitHub strips click interactions when rendering fences, for security. Clicks work in mermaid.live, self-hosted pages (like this one), and most docs sites - treat them as a bonus layer, never as the only way to reach the information.

The split signal is not a node count - it is a question count. A good diagram answers one question ("how does data flow through Nova?"). When yours starts answering three, split it:

• Overview diagram: zones only, maybe 8-12 nodes, the map of maps.
• Detail diagrams: one per zone, as deep as needed. Each lives next to the code it describes.
• Link them: click links where supported, plain markdown links under the fence everywhere else. The overview links down; each detail links back up.

Practical threshold: past roughly 20 nodes, start looking for the seam. Past 30, you are overdue.

You cannot move boxes by hand, but you can nudge the layout engine, in escalating order:

• Reorder declarations. Mermaid lays nodes out roughly in source order - moving the line that declares a node often untangles a crossing wire. Free, try it first.
• Flip direction. LR to TD (or the reverse) re-deals the whole hand. Also free.
• Invisible edges: a ~~~ b draws nothing but tells the engine "keep these ranked apart". The precision tool for two stubborn nodes that refuse to line up.
• Longer arrows: extra dashes (---->) request extra rank distance, as in Session 1.