Topic: ADR template in Miro
ADR Template in Miro — Whiteboard Sessions and the Diagram Handoff
Architecture teams reach for Miro when a decision is too complex to reason through in text alone — when the right move depends on a system diagram, a dependency map, or a real-time collaboration with the distributed team. But Miro is not an ADR store. The decision reasoning that lives on sticky notes and in diagram annotations during a Miro session doesn't survive the session unless it is deliberately handed off to a committed document. This page covers the ADR frame template layout, how to export Miro diagrams into your ADR archive, and the graduated handoff from Miro whiteboard to Markdown.
TL;DR
Miro works best as the RFC-stage visualization surface — diagramming options, mapping constraints, brainstorming with sticky notes — before the decision is made. It is not a durable ADR store. The graduated handoff: run the RFC session in Miro → continue the deliberation in Claude.ai/ChatGPT → commit the canonical ADR in Markdown → commit the relevant Miro frame as a PNG alongside the ADR file. Miro public links break when boards are deleted or workspace subscriptions lapse; always commit the exported PNG to your repository instead of linking to the Miro board from your ADR.
Why architecture teams use Miro for ADR-adjacent work
Miro is a collaborative online whiteboard. Its value in architecture work comes from three capabilities that text-based tools don't provide:
- Real-time distributed diagramming: multiple engineers on the same board simultaneously, drawing C4 diagrams, event storming maps, and system dependency graphs in a session that a remote team can observe and participate in.
- Visual trade-off mapping: sticky note clusters for "arguments for" and "arguments against" each option, dot-sticker voting on approach preference, color-coded constraint maps that show at a glance where organizational friction is concentrated.
- Architecture discovery sessions: event storming (domain modeling), system context mapping, and sequence diagramming — activities where understanding the problem space is a prerequisite for deciding how to approach it.
These activities correspond directly to the ADR's Context section: the background constraints, organizational pressures, and known facts that made a decision necessary. A Miro session that maps the current system architecture, identifies the pain points, and explores the solution space is producing the raw material for an ADR Context section — not a diagram of the decision taken, but a visual record of why the decision needed to be made.
The problem: this raw material stays in Miro unless someone deliberately extracts it. Most Miro sessions end without a committed ADR, and the sticky note reasoning is gone when the next unrelated session covers the same board.
ADR frame template structure
Miro's native template library (miro.com/marketplace) does not include an ADR template. But you can build one using Miro's frame feature — a named rectangular container that organizes content and can be exported as an individual image. The following structure works for a Miro ADR session frame:
Frame header
Name the frame with the ADR identifier and decision statement: ADR-042 · Decision: Use PostgreSQL over MongoDB. This makes the frame immediately identifiable when the board contains multiple ADR-related frames and when you export the frame as PNG for the repository.
Context zone (yellow sticky notes)
Yellow sticky notes cluster: one note per constraint, organizational pressure, or background fact that makes this decision necessary. These map to the ADR's Context section. The convention: each note completes the sentence "This decision is necessary because ___." Examples: "The current MySQL schema has 47 joins in the order query path," "The team has no MongoDB expertise," "We need full-text search within three months." Keep notes to one sentence each — the goal is to enumerate the forcing function, not explain it.
Options zone (one column per option)
Three-column layout, one column per option under consideration. Each column has: a header (the option name: "Option A: PostgreSQL," "Option B: MongoDB," "Option C: DynamoDB"), green sticky notes for reasons to choose this option, and red sticky notes for reasons against. This is the visual trade-off matrix that structures the deliberation. Teams that dot-sticker their preference during the session leave a visible record of which option had the most support before the decision was formally made.
Decision zone (text block)
A large text block containing the single-sentence decision statement: "We will use PostgreSQL for the product catalogue database." Active voice, present tense, naming the chosen option explicitly. This block is the ADR's Decision section distilled to one sentence. It should be filled in after the deliberation — not at the start of the session — to preserve the frame as a record of genuine exploration rather than a post-hoc rationale.
Consequences zone (two sticky clusters)
Two clusters: "We gain" (green border) and "We accept" (red border). Each cluster has sticky notes listing the positive outcomes and the trade-offs accepted respectively. The "We accept" cluster is the most important — an honest ADR Consequences section must include at least one downside. A Miro consequences zone with only green notes is the same problem as an ADR Consequences section with only benefits.
Status and metadata (top-right corner)
A small status badge (text shape with a colored background: blue = Proposed, green = Accepted) and a date stamp. Also useful: the names or avatars of the participants in the session — the record of who was in the room when the decision was made.
Miro export formats — what each contains
Miro offers five export paths. Only one is useful for committing to a code repository:
| Export format | How to trigger | Contains | Useful for ADR archive? |
|---|---|---|---|
| PNG (frame export) | Select frame → right-click → Export as image → PNG | High-resolution raster image of the frame; all visible text, sticky notes, diagrams | Yes — commit to repository alongside ADR Markdown file as a diagram artifact |
| PDF (frame or board) | Export menu → PDF → per frame or full board | Vector-rendered pages; human-readable but not machine-parseable; text is embedded in vector paths in many export configurations | Acceptable as a human-readable backup; not better than PNG for repository use |
| CSV (sticky notes) | Export menu → CSV | Text content of sticky notes with column for color, position, frame name; no structural context (which zone a note was in is position-only, not a semantic label) | Partial — recovers sticky note text but loses the Context / Options / Consequences structure that makes them ADR-relevant |
| Board JSON backup (.rtb) | Settings → Export → Save as backup | Full board in Miro's proprietary JSON format (wrapped in a zip archive); includes all elements with position and style metadata | No — Miro's .rtb format is not ADR-schema-compatible; useful only for Miro-to-Miro backup and migration |
| Public share link | Share button → Anyone with link → Copy link | Live view of the board at the time of access; always current (not a snapshot) | No — ephemeral; breaks when the board is deleted, the workspace subscription lapses, or the board owner leaves the organization |
The durability problem with Miro public links
The most common mistake when incorporating Miro into an ADR workflow is using the public share link as the diagram reference in the ADR. Engineers paste the Miro link into the ADR's Context or Consequences section, commit the ADR, and move on. Six months later:
- The board owner changes jobs and their Miro workspace is deactivated → link returns a "Board not found" error
- The organization downgrades from a paid Miro plan and old boards become view-only or inaccessible → link returns an access-required error
- The board is reorganized and the share link is revoked → link returns a 403
- Miro changes their URL structure → link redirects to the board list instead of the specific board
The result is an ADR with a broken "see the decision diagram" link — exactly the kind of rotting documentation that makes engineers stop trusting the ADR directory. The new engineer who needs to understand why the current architecture was chosen follows the Miro link and gets a 404.
The fix: treat the Miro PNG export as the canonical diagram artifact, not the live board link. Export the ADR frame as PNG at the time of ADR creation, commit the PNG to doc/decisions/images/ (or doc/decisions/diagrams/), and reference it with a standard Markdown image link: . The PNG never breaks because it is in the repository. Its content is frozen at the moment it was exported — it does not update as the board evolves, which is exactly what you want for a decision record.
The Miro board link can appear in the ADR's Context section as a deliberation reference: "See the Miro whiteboard session (link active as of 2026-06-03): https://miro.com/app/board/..." — explicitly noting the date it was active and acknowledging it may no longer resolve. This preserves the audit trail without creating a false expectation of link permanence.
Embedding Miro diagrams in other ADR surfaces
Teams that write ADRs in Confluence, Notion, or Linear can embed Miro boards directly:
- Confluence: the Miro for Confluence app adds a board embed macro. Insert a Miro board by board URL; the embedded view updates live as the board changes. Useful for current-state architecture maps; carries the same durability risk for decision records. Pair with the PNG export committed to git for the canonical archive.
- Notion: paste a Miro board URL into a Notion page → Notion converts it to an embed block. Same live-update behavior, same durability risk. For the canonical ADR in Notion, use the PNG export uploaded to Notion's own file storage (which persists as long as the Notion workspace exists) rather than the Miro embed.
- Linear Documents: Linear does not have a native Miro embed block. Paste the share link as a standard URL. Linear's graduated handoff pattern (draft in Linear, graduate to committed Markdown) naturally addresses the Miro link durability problem — the final committed ADR file uses the PNG export, not the Linear document's Miro link.
The graduated handoff from Miro to committed ADR
The complete workflow that combines Miro's visual strength with the durability of a committed Markdown ADR:
- Phase 1 — Miro RFC session (the visual deliberation). Build the ADR frame with the Context zone (constraints), Options zone (alternatives with sticky note pros/cons), and Consequences zone. Include C4 diagrams or sequence diagrams for each option if the architectural shape differs significantly between them. Run the dot-sticker preference exercise if the team is distributed and real-time consensus is needed.
- Phase 2 — AI-assisted deliberation (the reasoning). Continue the trade-off analysis in Claude.ai or ChatGPT — not in Miro — because the deliberation (the reasoning chain that leads from constraints to decision) is the content most worth preserving, and it needs a durable store. Reference the Miro session context ("we diagrammed three options in Miro; option A uses an event bus, B uses direct calls, C uses a saga orchestrator; the Miro session showed the team prefers B but the latency constraint may rule it out"). The AI chat is where the alternatives are formally evaluated and rejected.
- Phase 3 — commit the canonical ADR. Write the ADR in Markdown, synthesizing the Miro session (Context section raw material) and the AI deliberation (Decision and Consequences sections). Export the ADR frame from Miro as PNG, commit it alongside the ADR file. Reference it in the ADR body with a Markdown image link.
- Phase 4 — quarterly decision harvest (optional). Export the Claude.ai or ChatGPT conversations from Phase 2 and run the WhyChose extractor. The extractor surfaces the decision from the AI chat as a structured record, which can be compared to the manually-written ADR from Phase 3. For engineers who did not write a Markdown ADR in Phase 3, the extractor output is a retrospective starting point.
FigJam vs Miro for architecture decision sessions
FigJam (Figma's collaborative whiteboard) addresses the same diagramming-and-brainstorming use case as Miro. The comparison for ADR-adjacent work:
| Dimension | Miro | FigJam |
|---|---|---|
| Primary audience | Engineering-leaning; strong for technical diagramming, event storming, C4 | Design-leaning; strongest for product teams mixing UX flows with architecture discussions |
| Template library | Larger Miroverse community template ecosystem; more engineering-specific templates | Figma Community templates; more design-process templates (user journey, wireframe-to-diagram) |
| Integration with code workflows | Integrations with Jira, Confluence, GitHub (link cards, not code-level); no native git integration | Integrations with Jira, GitHub (similar depth to Miro); Figma design file links are a strong point for design-engineering handoffs |
| Export formats | PNG, PDF, CSV (stickies), JSON board backup, public link | PNG, PDF, FigJam file export; no sticky note CSV; FigJam JSON is Figma proprietary format |
| ADR frame export | Frame-level PNG export via right-click → Export as image | Section-level export; equivalent workflow, slightly fewer export quality options |
| Public link durability | Same risk — breaks on board deletion, subscription lapse, permission change | Same risk — same solution (export PNG, commit to repository) |
| Free tier | Free tier: 3 editable boards; sufficient for individual ADR sessions | Free tier: unlimited FigJam files with Figma account; broader free access |
For teams already in the Figma ecosystem (product + engineering using Figma for design), FigJam has the friction advantage — one fewer tool to context-switch into. For engineering-first teams doing event storming and technical architecture diagramming, Miro's template ecosystem and engineering-specific diagram types (C4, UML, ERD) are the differentiator. The ADR frame template and graduated handoff workflow described on this page apply identically to FigJam with the same export-PNG-commit-to-repo recommendation.
How WhyChose fits in
Miro captures the visual phase of architecture deliberation — diagrams, spatial grouping, real-time collaboration. But the reasoning phase — the explicit trade-off comparison where alternatives are named and rejected — typically happens in a follow-on AI chat session. When an engineer opens Claude.ai or ChatGPT after the Miro session to reason through the trade-offs more formally ("we mapped three options in Miro today; help me think through the latency and operational complexity trade-offs"), that AI conversation is where the decision reasoning is made permanent.
The WhyChose extractor surfaces decisions from exactly those ChatGPT and Claude.ai conversations — the ones that happen after the Miro session closes and before the ADR is written. The extractor output provides the Decision and Consequences section material that the Miro session started but the AI conversation completed. The Miro PNG export provides the diagram artifacts that the Consequences section references. Combined, the two artifacts produce an ADR that is richer than either could provide alone.
Related questions
Can you use Miro as an ADR tool?
Miro works well as a deliberation surface for the RFC stage — exploring options with a distributed team using diagrams, sticky note clustering, and real-time collaboration. It is not suited as the canonical ADR store: Miro's export formats are not ADR-compatible, Miro public links are ephemeral, and Miro boards are not git-committed alongside the code they document. The recommended pattern: run the RFC session in Miro, export the ADR frame as PNG and commit it to the repository alongside the canonical ADR Markdown file, use the Miro session as deliberation context (the raw material for the ADR Context section) rather than as the ADR itself.
How do you export an ADR from a Miro whiteboard?
There is no one-click Miro export that produces a structured ADR. The practical export path: (1) select the ADR frame you built during the session, (2) right-click → Export as image → PNG, (3) commit the PNG to your repository at doc/decisions/images/NNNN-title.png, (4) reference it in the ADR Markdown file with a standard Markdown image link. The reasoning captured on sticky notes must be manually synthesized into the ADR Context, Decision, and Consequences sections. Miro's sticky note CSV export recovers the text content of individual notes, but the zone structure (Context / Options / Consequences) is not preserved as semantic labels — it is positional data that requires manual interpretation.
How does Miro fit into the RFC-to-ADR workflow?
Miro fits best as the RFC-stage visualization and brainstorming surface: the phase before a decision is made, when the team is exploring options with diagrams and sticky note clusters. An RFC in Miro looks like: one frame per option showing the system diagram for that approach, yellow sticky notes for constraints and organizational pressures, and dot-sticker voting to surface team preference. After the Miro RFC session, the trade-off analysis moves to a written deliberation — an RFC document or an AI-assisted conversation in Claude.ai or ChatGPT — and the ADR is written from that deliberation, with the Miro session providing diagram artifacts and sticky note raw material for the Context section.
What is the difference between using Miro and Confluence for ADR documentation?
Miro is a visual-first whiteboard best for the diagramming and brainstorming phase before a decision is made. Confluence is a structured wiki best for storing the written ADR text, especially for Atlassian-stack teams who want Jira/Bitbucket integration and per-page permissions. Neither replaces git-committed Markdown for the canonical immutable ADR. The complementary pattern: RFC in Miro (visual phase), canonical ADR in Confluence or git-committed Markdown (text phase), Miro frame PNG embedded in the Confluence ADR page as a diagram reference. Confluence's Miro embed macro supports live board views but carries the same durability risk as Miro public links — if the board is deleted, the embed breaks. The committed PNG does not break.
Further reading
- Mermaid diagrams in ADRs — sequence diagrams, C4 models, and flowcharts in Markdown — the text-as-code complement to the Miro PNG export: once the Miro RFC session produces the committed PNG for the repository, Mermaid is the format for the simplified committed-record diagram in the ADR body itself. Mermaid is versioned in git, diffable in PRs, and rendered natively by GitHub and GitLab without any external tool. The two approaches are complementary phases — Miro for the whiteboard exploration, Mermaid for the concise committed representation that future engineers can diff when the ADR is updated.
- ADR vs RFC — what's the difference and when should you use each? — the functional distinction that explains where Miro fits in the ADR process: RFC is a pre-decision document (Miro is the ideal RFC surface — visual, collaborative, exploratory); ADR is a post-decision document (Markdown in git is the ideal ADR surface — immutable, versioned, code-collocated). The RFC → ADR handoff pattern in five steps maps directly to the Miro → committed Markdown workflow described on this page.
- ADR template for Confluence — how to build the canonical ADR text in Confluence after the Miro RFC session is complete: the Confluence page structure, the Status macro, the Miro embed macro (with its durability caveats), and the Jira Issues macro for linking the ADR to triggering tickets. Confluence is the most natural text layer for teams that ran the RFC in Miro and need the ADR close to their Jira Epic.
- Architecture decision record best practices — what actually works after year one — includes the "diagrams as ADR supplements" best practice: when a C4 system context diagram or sequence diagram explains the Consequences section better than prose, commit the PNG alongside the ADR. The Miro frame export workflow described on this page is the concrete implementation of this practice.
- ADR adoption guide — how to introduce ADRs to a resistant team — a specific section on using visual retrospectives to introduce ADRs to teams that already have Miro habits: the retrospective-first approach (draw the diagram of a decision that was made six months ago in Miro, then formalize it as an ADR) often has better uptake than asking engineers to write ADRs without a visual artifact as the starting point.
- ADR template for Notion — the Notion-based ADR workflow for teams that run both Miro and Notion: the Miro embed block in Notion pages, the Notion database schema for ADR properties, and when a Notion page is the right canonical surface vs a committed Markdown file. Notion's Miro embed has the same durability limitation as Confluence's — use committed PNG for the archive artifact.
- ADR storage format comparison — Markdown vs AsciiDoc vs Notion vs Confluence vs SharePoint — the tool-selection guide for where to store the canonical ADR text after the Miro RFC session closes. The decision matrix covers the durability, export, git-integration, and audience dimensions that determine which storage layer fits each team shape.
- The open-source extractor — reads your Claude.ai or ChatGPT conversations.json export and surfaces architecture decisions as structured ADR-compatible records. Use it to harvest the decisions from the AI deliberation conversations that happen after a Miro whiteboard session closes — the extractor output fills the Decision and Consequences sections that the Miro sticky notes started but the AI conversation completed.