Write a design document from your diagrams and decisions
Assemble an architecture brief, design review, decision record, or handover notes from your diagrams, explainers, whiteboard decisions and notes, then export it as Markdown or PDF without inventing anything.
Most design documents are written after the real work: the diagrams exist, the decisions were made on a whiteboard, the notes sit in a chat thread. A Flowgraph Studio design document collects that material into a structured write-up, keeps each diagram as it was when you added it, and leaves the gaps visibly empty instead of filling them with guesses.
Pick the kind of document
In Projects, choose New design document and a template:
| Template | Sections |
|---|---|
| Architecture brief | Problem, goals and scope, constraints, proposed architecture, alternatives, decisions, open questions and risks, next actions, references |
| Design review | Context, proposal, options considered, trade-offs, questions for reviewers, decision, next actions |
| Decision record | Context, decision, alternatives considered, consequences, diagrams |
| Handover notes | Purpose, how it works, operations, known issues, open questions, owners and next actions |
Every template ends with References: the diagrams and versions the document was made from.
Where the content comes from
flowchart LR
subgraph sources [What you already have]
D[Diagrams]
P[Prism explainers]
W[Whiteboard decision cards<br/>and action items]
N[Pasted notes]
end
D -->|copied as captured| DOC[Design document]
P -->|copied as captured| DOC
W -->|Decisions and Next actions| DOC
N -->|Decision:, Risk:, Action: …| DOC
DOC --> MD[Markdown]
DOC --> PDF[PDF]Notes, sorted by their first word
When you start a document you can pick diagrams and paste notes. Lines that begin with a label go to the matching section:
Context: checkout times out during flash sales
Goal: keep checkout under 300 ms at 10× traffic
Constraint: must stay in the EU region
Option: queue between checkout and fulfilment
Decision: use a queue; fulfilment reads from it
Risk: queue backlog during a sale
Action: Sam to load-test the queue by Friday
We also talked about caching product pages
Context, Goal, Constraint, Option, Decision, Risk, Question and Action lines are placed in the matching section when the template has one; the last line has no label, so it's kept as written under Notes, along with any labelled line whose section the template doesn't have. Nothing else is filled in for you: an empty section shows "To be completed" in the export. That is deliberate. A design document that confidently states decisions nobody made is worse than one with a visible gap.
Diagrams and explainers, captured as they are
In any section, Add a diagram or explainer places a copy of a diagram, or of a Prism explainer, as it is at that moment. Editing the document never changes the diagram. If the diagram changes later, the document says so ("The diagram has changed since"), and Update to current replaces the copy when you're ready. That's how a design review stays true to what was reviewed.
Decisions from a whiteboard
If the decisions were made on a whiteboard, Add decisions and actions from a whiteboard brings the board's decision cards and action items into the Decisions and Next actions sections, under a line naming the board:
From the whiteboard "Checkout review":
- Use a queue (accepted)
Question: Queue or direct calls?
Why: Absorbs sale spikes
Priya, 2026-11-18
Anything already written in those sections stays. A decision record, which has no actions section, gets one before References.
Export it
- Markdown downloads the document: sections as headings, diagrams as
mermaidcode blocks (which GitHub, GitLab, and many wikis draw), Prism explainers as their words (overview, numbered parts, takeaway, and sources), and the list of references. Copy Markdown copies it to paste into a wiki or a pull request. - PDF opens the print dialog with the document laid out for paper, diagrams drawn as on the canvas; choose "Save as PDF" there. Text stays text, so it's searchable.
A design document is saved in its project like a diagram, with version history and a review status of its own.
A workflow that works
sequenceDiagram
actor A as Author
participant W as Whiteboard
participant D as Design document
actor R as Reviewers
A->>W: Run the review session
W-->>A: Decision cards and action items
A->>D: New design document (Design review)
A->>D: Add the diagrams and the board's decisions
A->>D: Fill the remaining sections
D-->>R: Share the PDF or the Markdown
R-->>A: Comments
A->>D: Mark as reviewed- Write the problem first. If you can't fill Problem and Goals, the design isn't ready for review.
- Keep diagrams as captured until the review ends, then update them together, so reviewers' comments match what they saw.
- Mark it as reviewed (Review status, in the top bar) once it's agreed. If its content changes later, it shows "Changed since review"; see keeping diagrams up to date.
Running the review itself? See how to run an architecture review on a shared whiteboard.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.