Create a reviewable Mermaid architecture diagram by stating its boundary and arrow meanings, naming the components, rendering the source, and checking the result against the system with its owners. Keep the source beside a component register and assign responsibility for updates. Mermaid makes relationships editable as text; reviewers establish whether they match the implementation.
This guide provides an original, fictional order-processing example. Use the downloadable Mermaid source as a starting point, then replace it with your own verified components and interactions.
State what the diagram is—and what it leaves out
The example is a logical dependency view of an order service. Solid arrows represent request or data-access relationships. Dashed arrows represent asynchronous event flow. The diagram does not specify network deployment, every response, authorization policy, or transaction ordering.
Put that boundary above the diagram. Without it, a reader may interpret a dependency arrow as a complete sequence of runtime steps or assume that an omitted control does not exist.
Open the full-size architecture diagram. The preview and source below describe the same components and relationships.
flowchart LR
CUSTOMER["Customer browser"] --> GATEWAY["Application API"]
subgraph APP["Order application"]
GATEWAY --> AUTH["Identity service"]
GATEWAY --> ORDERS["Order service"]
ORDERS --> CATALOG[("Catalog data")]
ORDERS --> ORDERDB[("Order records")]
ORDERS -.-> QUEUE["Order event queue"]
QUEUE -.-> WORKER["Fulfillment worker"]
WORKER --> ORDERDB
WORKER --> NOTIFY["Notification adapter"]
end
NOTIFY --> MAIL["Email provider"]
The syntax uses standard flowchart nodes, subgraphs, and connectors described in the Mermaid flowchart documentation. A successful render checks syntax and layout; reviewers must still check the architecture.
Use stable identifiers and readable labels
ORDERDB is the source identifier; “Order records” is the displayed label. Keep identifiers stable when renaming labels so the change remains easy to inspect.
Give each component a name that the intended audience recognizes. If the operations team calls a service “Orders API” and the diagram says “Core Processor,” either align the names or explain the mapping nearby.
Avoid packing configuration details into every node. Put deployment-specific settings in a linked document, particularly if they change more frequently than the logical relationships.
Add a component register beside the picture
For the fictional example:
| Component | Responsibility | Review question |
|---|---|---|
| Application API | Accept application requests | Where are request validation and authorization explained? |
| Identity service | Provide identity-related capabilities | What is the documented trust relationship? |
| Order service | Maintain the order workflow | Which data and events does it own? |
| Order records | Store order state | Which components can read or write it? |
| Event queue | Carry asynchronous order events | What are delivery, retention, and recovery rules? |
| Fulfillment worker | Process order events | How are retries and repeated events handled? |
| Notification adapter | Prepare outbound messages | What happens when the external provider is unavailable? |
The register turns the diagram into questions that reviewers can resolve. It should not imply that the sample has implemented answers to all of them.
Review the failure paths in a separate view
Use the dependency picture to identify where a failure could occur, then document the relevant sequence separately. For example, a worker may receive an event more than once or a notification request may fail after an order state changes.
Ask the owning team to explain the intended behavior and link the relevant runbook or design decision. Do not add a “retry” arrow merely because it looks reassuring; specify what is retried and which side effects must be controlled.
A separate sequence or focused flowchart can explain one failure path more clearly than dozens of additional arrows on the overview.
Publish the source with the reading context
Place the diagram near its purpose statement, legend, component register, and owner. Record when the architecture was last checked against the implementation and what triggered that review.
If you use Diagram Lens, its source editor and reader controls are intended to keep those relationships maintainable in Confluence. Check the installed version and current availability before choosing that workflow for a team.
If the picture outgrows the page, use the large-diagram reading guide. Keep an overview and focused diagrams rather than making every reader navigate the entire system for a small question.
Review a real change, not just the initial image
Suppose your application adds a dedicated inventory service. A useful diagram change includes the new component, revised dependencies, updated register, and a link to the decision that established the new responsibility.
Ask a reviewer to check both the text change and the rendered result. A small source edit can materially change the meaning of an arrow or group boundary.
For a worked evidence audit, inspect the deliberately flawed AI-generated architecture diagram. Its component register and directed-edge comparison show how valid Mermaid syntax can still describe unsupported architecture.
When handing the diagram to another team, include editable source and its legend. An image can communicate today's picture while leaving the next maintainer unable to correct tomorrow's change.
A short review checklist
- The purpose and omitted details are explicit.
- Components match the names used by their owners.
- Arrow direction and meaning are defined.
- Failure behavior is documented where it matters.
- The source and rendered result agree.
- An owner and review date are recorded.
For another editing workflow, see the Mermaid, draw.io, and Gliffy comparison. The tool should make these checks easier; it cannot replace them.