A Mermaid subgraph groups related flowchart nodes. When it fails, first separate a syntax error from an unexpected layout: a diagram that renders in an inconvenient arrangement needs a different investigation from a diagram that cannot parse.
Use explicit group IDs such as client and backend, and keep display labels separate. Each subgraph needs a matching end. Lowercase end is reserved here, so use a label such as End for an ordinary node. The official flowchart reference documents the syntax.
The opening fence must identify the diagram as Mermaid. A plain code fence can display the source as text even when the diagram itself is valid. Verify the opening and closing fences before editing nodes or connections.
If the article contains several diagrams, isolate the failing block in a new document. This gives you a short example to compare with the original and prevents a different broken block from confusing the investigation.
Give separate services separate node IDs. In this example the labels can match, but the identifiers should differ:
A quick review technique is to list the intended nodes in plain text: production API, staging API, production database, staging database. Then compare that list with the diagram's identifiers. This catches copy-and-paste mistakes without guessing at layout settings.
Record the first addition that changes the result. If one particular label causes trouble, temporarily replace it with a short word. If an external connection changes the arrangement, investigate the connection rather than repeatedly rewriting the group.
Subgraph direction has a documented limitation involving links between internal nodes and the outside graph. See why Mermaid subgraph direction is not working for a focused example and alternatives.
Treat an architectural diagram as an explanation. Decide whether the important information is group membership, service-level connectivity, or exact visual order. If a single diagram is trying to communicate all three, an overview plus a separate detail diagram may be easier to maintain.
Once you find a working version, retain the small example alongside the complete diagram. Preview both in mdview.io when editing. If a later change breaks the large diagram, the small example helps you determine whether the problem is in your recent edit or in the rendering environment.