An API spec explains what a request accepts and returns. To understand what happens next, someone may need to look across several services. An order might check stock, take payment, save the order, and send a confirmation. A diagram helps someone follow that flow.
Mermaid lets you write diagrams as text. You can keep those files in your repo and review diagram changes in the same pull request as the code.
Start with a question
Before drawing, decide what you want someone to understand. Which services take part in placing an order? In what order do they communicate? What happens if the payment fails? These questions need different levels of detail, and trying to answer all of them in one diagram can make it harder to read.
Name the diagram after what it explains, such as “Order payment flow,” and add a short note about its scope. This helps readers understand what the diagram covers and what you have left out.
Choose the view that helps
A flowchart shows the main steps and decisions. For an order, that might mean checking stock, taking payment, and choosing what happens when either step fails. Here is a simplified example:
flowchart TD
A[Check stock] --> B{Available?}
B -->|Yes| C[Take payment]
B -->|No| F[Order cannot proceed]
C --> D{Payment successful?}
D -->|Yes| E[Save order and send confirmation]
D -->|No| FThe text defines the steps and their connections. A Mermaid renderer turns it into a diagram, so you can change the flow by editing the text.
A sequence diagram is useful when the order of calls and responses matters. It can show the order service requesting a payment and waiting for the result before continuing. A state diagram answers a different question: which states can an order move through? Those might include pending, paid, cancelled, and refunded.
You may need more than one diagram for a feature. Keep each focused on a question rather than adding every detail to the same view.
Add the explanation the diagram needs
A box labeled “Payments” does not explain much by itself. Use clear names and label important connections. “Request payment” tells a reader more than an unlabeled arrow.
Add a short explanation beside the diagram for details that are awkward to draw. You could write: “This diagram shows a successful card payment. Refunds and payment retries are covered separately.” Notes can also explain why a step exists. If stock is reserved before payment, describe the reason and what happens to that reservation when payment fails.
The diagram shows the flow, while the notes explain the decisions behind it. Keep both focused on what someone needs to understand.
Review it when the flow changes
Keeping a diagram in Git gives you a history of its changes, but someone still needs to check whether it describes the current behavior. If an order starts using an event queue instead of service directly, review the diagram in the same pull request. Check whether its arrows, labels, and notes need updating.
Add a simple question to your review process:
Does this change affect a flow shown in our diagrams?
You do not need to draw every internal function. Include the steps someone needs to understand the behavior, and link to other details where useful.
Explore Mermaid diagrams in UIGraph
You can reference a Mermaid diagram in your UIGraph YAML file and sync it using the CLI. This lets your team maintain the file in the repo and explore the diagram in UIGraph. You can also add sync to your CI/CD workflow to publish updates when it runs.
The diagram still needs to reflect the behavior you want to explain. Sync publishes the content your team maintains. It does not make an outdated diagram accurate.
Pick one flow, give it a clear scope, and update the diagram when the flow changes.
