Share a mermaid architecture diagram with notes as a link
A diagram alone gets misread. A diagram with its assumptions, failure paths, and one code sample gets understood. Here is a complete example, how to preview it locally, and how to publish it as a link when you are ready.
Updated
What does a good architecture note look like?
Short. One mermaid diagram of the flow, a list of assumptions the diagram relies on, a table of what happens when each part fails and who notices, one concrete payload, and a line about what is out of scope. This fictional note explains outbound webhook delivery to people outside the repository.
architecture-webhook-flow.md
2,389 characters · fictional example, same file as the download
Architecture note: outbound webhook delivery
Audience: the integrations team and the customer success lead · Scope: how an event leaves Ledger API and reaches a customer, after the retry work ships.
The flow
Assumptions
- Customer endpoints are HTTPS and answer within 10 seconds. Anything slower is treated as a failure.
- Events are small (under 64 KB) and carry no secrets; the payload is signed with the account's webhook secret, not encrypted.
- A single Postgres database is fine for the current volume (~40k events/day). The queue table lives beside the events, so enqueueing is transactional with the event itself.
Failure paths
| Failure | What happens | Who notices |
|---|---|---|
| Endpoint returns 5xx or times out | Attempt marked failed, rescheduled with backoff (1 min → 12 h) | Nobody, by design |
| Endpoint returns 4xx | Attempt marked dead immediately — retrying a bad request is pointless | Account owner email |
| 5 consecutive failures | dead + owner email; replayable from the dashboard | Account owner |
| Scheduler down | Attempts pile up as pending; alert fires when the oldest due attempt is over 5 minutes old | On-call |
| Customer endpoint not idempotent | Possible double-processing on retry | Customer — mitigated by the Idempotency-Key header |
What the customer receives
POST /hooks/ledger HTTP/1.1
Host: customer.example
Content-Type: application/json
Idempotency-Key: evt_01J9X4K2P7
X-Ledger-Signature: sha256=3b1f…
{"id":"evt_01J9X4K2P7","type":"payment.settled","data":{"amount":12900,"currency":"EUR"}}
Verifying the signature is three lines in most languages:
const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(header.slice(7)))) throw new Error('bad signature');
Out of scope
Fan-out to multiple endpoints per account, and event ordering guarantees. Both are tracked separately.
How do I preview the document before sharing it?
Open it in the markdown viewer — the link loads this example; for your own file, drag it onto the viewer or paste the text. Rendering happens in the browser with the File API; the file is not uploaded. Check that the diagram compiles (a mermaid syntax error renders as a message in place of the diagram), that the table columns line up, and that the code block has a language tag so it is highlighted.
How do I share the diagram as a link?
Click Open in editor above, or paste your document into the homepage editor. Pick an expiry — 30 days is the default; never for a document you will link from a README — and click Share Markdown. The page you get renders the diagram as an SVG with the notes around it, and the sidebar lists the headings. From Cursor or Claude Code with the MCP server connected, the same thing is one sentence:
Share architecture-webhook-flow.md as a permanent link and give me the URL.Keep the edit token the assistant reports. When the architecture changes, ask it to update the share, and the link everyone bookmarked shows the new diagram.
How do I write the diagram itself?
A fenced code block tagged mermaid. Flowcharts read left to right for pipelines and top to bottom for hierarchies; sequence diagrams are better when the order of calls matters, as in the implementation plan example. Label the edges with what crosses them ("insert pending attempt"), not just arrows.
```mermaid
flowchart LR
E[Domain event] --> D[Dispatcher]
D -->|insert pending attempt| Q[(delivery_attempts)]
S[Scheduler] -->|select due| Q
S -->|POST| C[Customer endpoint]
```More diagram syntax: the mermaid timeline examples and the diagram section of the markdown cheat sheet.
What should I know before sharing?
- The link is public to anyone who has it. Redact hostnames and secrets you would not put in a slide deck.
- Expiry deletes the page at its URL; it does not recall a copy someone saved.
- Images referenced by absolute URL load from wherever they are hosted; relative image paths do not resolve.
- 120,000 characters per share — plenty for a note, not for a whole design system.
FAQ
How can I share a mermaid diagram with explanatory text?
Write the diagram in a ```mermaid fence inside a markdown document, with the assumptions and failure paths as ordinary headings and tables around it. Paste the document into the Docs MD editor and click Share Markdown. The link renders the diagram as an SVG next to the text. No account is needed.
Can I send an architecture diagram as a link without requiring an account?
Yes. Neither the sender nor the reader needs an account. The share is a public URL; choose an expiry of 1, 7, or 30 days, or never, and keep the edit token if you expect to revise the diagram.
How do I preview an AI-generated markdown architecture document before sharing it?
Open it in the markdown viewer: drag the .md file in or paste the text. The viewer renders mermaid, tables, and highlighted code in your browser and does not upload anything. Sharing is a separate button.
Which mermaid diagram types render on a share page?
Flowcharts, sequence diagrams, class and ER diagrams, state diagrams, gantt charts, timelines, pie charts, and the other types supported by current mermaid. A diagram with a syntax error shows the error message instead of the picture, so preview first.
Does GitHub render mermaid too? Why share a link instead?
GitHub renders mermaid fences in README files, issues, and pull requests. A share link is for readers who are not in the repository — a client, another team, a stakeholder without a GitHub account — or for a document that should not live in the repo at all.