If direction TB inside a flowchart LR does not produce the arrangement you expected, inspect the connections crossing the subgraph boundary. You may have valid syntax and still encounter a layout limitation.
Mermaid documents that when a subgraph's internal nodes connect to nodes outside the group, its local direction is ignored and the parent direction is inherited. See the official subgraph direction documentation.
This example includes that kind of connection:
Removing outside --> A gives you a useful comparison. Render both versions in the same viewer so you can isolate the effect of the boundary-crossing edge.
If the diagram's meaning is that the caller reaches the service as a whole, you can express the connection using the group ID:
This changes the endpoint from an internal step to the service boundary. Use it only when that is an accurate description of the system. Compare the rendered result in your target viewer; the complete graph and its layout engine still influence placement.
Before editing a diagram, write down what each cross-boundary arrow means. Does it represent a network request, a dependency, or a sequence of actions? A group-level arrow can communicate a system relationship, but it may lose the information that a request enters a particular validation step.
For a security review, that entry point may matter more than vertical alignment. Keep the node-level edge if removing it would hide an important fact. For a product overview, the group-level relationship may be sufficient.
An overview can show the caller, service, and database as a small architecture diagram. A separate diagram can explain validation and processing inside the service. This gives each diagram a specific question to answer and reduces the number of layout constraints competing on the page.
Keep the diagrams under descriptive headings such as “System boundaries” and “Request processing.” Readers can then choose the level of detail they need without untangling every implementation step in one picture.
Keep the viewer consistent during this experiment. Comparing two tools at the same time introduces another variable and makes the result harder to interpret.
Preview the examples in mdview.io. If the diagram does not render at all, use the subgraph troubleshooting guide to check fences, group endings, and identifiers first.