How to run an architecture review on a shared whiteboard

Run a design review on a live whiteboard from start to finish: an agenda, private brainstorming, dot voting, decision cards and action items, then turn the board into a Mermaid diagram and a written record.

Updated November 19, 2026 · 3 min read

Architecture reviews go wrong in familiar ways: the loudest idea wins, decisions live in someone's memory, and the diagram on the board never makes it into the docs. A shared whiteboard with a little structure fixes all three. This guide walks through a one-hour review on a Flowgraph Studio whiteboard, from an empty board to a diagram and a decision record.

The shape of the session

flowchart LR
  prep[Prepare the board] --> ideas[Private round:<br/>everyone adds notes]
  ideas --> vote[Dot vote on<br/>the options]
  vote --> decide[Decision cards and<br/>action items]
  decide --> out[Diagram, summary,<br/>design document]

Each step uses one feature, and nothing has to be copied by hand afterwards.

1. Prepare the board

In Projects, choose New whiteboard and start from the Architecture review template. It lays out named frames: Goal, Current design, Constraints, Risks, Alternatives, Decision, Actions, and a Parking lot, each with a note on what goes in it. (The other templates are design critique, technical brainstorming, and option comparison, all on the Templates page too.)

Before the meeting:

  • Add the current design. Add diagram places one of your diagrams on the board as a snapshot. Choose Editable shapes instead to get boxes and arrows you can annotate and rearrange.
  • Add the material. Paste screenshots, or use Add PDF pages to place up to 20 pages of a document as images to mark up.
  • Set the agenda. Put the frames in order; you'll present them one by one.
  • Share it. Share invites people by email as Can edit or Can view. For a wider audience, a view-only link lets anyone watch the board live without an account, for 1, 7, or 30 days.

2. Collect ideas without anchoring

Start a private round on the Alternatives frame. While it runs, the notes each person adds are visible only to them; when time is up, you reveal everyone's at once. Nobody gets anchored by the first idea on the board.

Run a shared timer everyone sees, and use Present to walk through the agenda frames; others can choose Follow along to see each one in turn. For bigger groups, breakouts send each group to its own frame and Bring everyone back gathers them again.

3. Converge with a dot vote

Select the options and start a dot vote. While it's open, each person sees only their own dots and how many people have voted, so early votes don't sway the rest. When you close it, everyone sees the totals and who voted for what. Votes aren't anonymous, which keeps the discussion honest.

4. Record the decision where everyone can see it

Facilitate adds two kinds of cards to the board:

  • Decision cards: the question, the decision, why, the trade-offs, an owner, a date, and a status (proposed, accepted, rejected, or superseded).
  • Action items: the task, an owner, a due date, and a status.

A decision record usually ends up looking like this:

flowchart TB
  Q{{"Queue or direct calls<br/>between checkout and fulfilment?"}}
  Q -->|chosen| A["Use a queue<br/>absorbs sale spikes"]
  Q -.->|rejected| B["Direct HTTP calls<br/>simpler, but couples uptime"]
  A --> T1[Load-test the queue<br/>owner: Sam, due Friday]
  A --> T2[Add a dead-letter queue<br/>owner: Priya]

Comments with @mentions and quick reactions keep side discussions on the board instead of in chat. Activity shows who added, edited, or deleted what during the session.

5. Turn the board into lasting artifacts

The whiteboard is the working surface; three outputs make the result last:

  • A real diagram. Convert to diagram makes an editable flowchart from the whole board, one frame, or a selection: shapes and sticky notes with text become nodes, attached arrows become connections, and frames become groups. You see what was left out, and the Mermaid code, before saving. For a hand-drawn sketch, Pro's Read with AI writes the flowchart from a picture of it.
  • A session summary. Download the agenda, decisions, actions, vote results, and open comment threads as Markdown, or the board as a PDF with one page per frame. Decisions also download as Markdown and actions as CSV for your tracker.
  • A design document. In a design document, Add decisions and actions from a whiteboard brings the board's decision cards and action items into the Decisions and Next actions sections.

Tips for a good review

  • Send the board a day ahead with the current design on it. Reviews go faster when people arrive with questions.
  • Write the decision as a sentence, not a box label: "Use a queue between checkout and fulfilment" is a decision; "Queue" is not.
  • Give every action an owner and a date, or it isn't an action.
  • Keep the parking lot. Good ideas outside the agenda deserve a place that isn't the meeting.

Whiteboards are in beta and free on every plan; live sessions hold up to 10 people at once. Once the decision is in a diagram, keep it up to date with version history and reviews.

More guides