How do you keep auth flow diagrams readable when edge cases pile up?

Keep the main diagram focused on the normal path and the few decisions that change it. If several failures lead to the same outcome, group them into one branch and point to a note or specification that explains the individual causes. A flowchart is an overview, not necessarily the place to spell out every rule.

I’d make a small companion diagram or failure card for each case that needs its own explanation. Link it from the exact point where the exception begins, using a consistent label so someone can move between the overview and the details.

For each case, capture what triggers it, what the service does, and how the flow ends or recovers. That gives engineers useful debugging context without making the normal path unreadable.

For the concurrent-login race, consider a sequence diagram instead of forcing it into a flowchart. Parallel lifelines make the timing and interaction between requests easier to see. A small state-and-trigger table can also clarify cases like an expired refresh token, especially when the key question is what state the service ends up in.

A layered setup works well if people need both the overview and the branches nearby. Keep the core path clean, then add separate scenario frames for things like an identity-provider outage or a refresh failure. You can show a short marker at the branch point in the main view and put the actual steps in the relevant frame.