Keep architecture diagrams up to date: versions, comparisons and reviews
Stop architecture diagrams going stale: version history with named checkpoints, side-by-side and overlay comparisons that mark what changed, and owners with review status that flags a diagram when it changes or is due.
A diagram is only useful while it's true. The usual failure is quiet: someone edits the system, nobody edits the diagram, and six months later a new engineer learns the wrong architecture from it. Flowgraph Studio gives each diagram three safeguards: a history of every version, a comparison that shows exactly what changed, and an owner with a review status.
Version history
Open Version history (the clock in the top bar) to see earlier versions of a diagram or explainer, each with a preview. A version is kept:
- every few minutes while you edit,
- before each AI change,
- and whenever you choose Save version, which you can name, such as "Agreed in the 12 May review".
Restore brings back that version's code and style; the version it replaces stays in history, and undo reverses the restore. Open as a copy makes it a new diagram instead, leaving the current one untouched.
Versions are kept for 7 days on Free, 90 days on Pro, and a year on Pro Max, up to 200 versions per diagram.
Compare two versions
Compare with current shows two versions side by side, with what changed marked on both drawings and listed beside them:
| Mark | Meaning |
|---|---|
| + Added | A node, connection, or group that's new |
| − Removed | Something that's gone, with its connections |
| ~ Changed | A new label, shape, or group membership |
| ↻ Reconnected | A connection moved to a different node |
Click a change to zoom both sides to it. Changes to layout and styling (moved nodes, a new theme) are listed separately and can be hidden, so a tidy-up doesn't drown out a real change.
For example, between these two versions of a checkout flow:
flowchart LR
web[Web] --> api[API] --> pay[Payments]
api --> db[(Orders DB)]flowchart LR
web[Web] --> api[API] --> pay[Payments service]
api --> q[Order queue] --> worker[Fulfilment] --> db[(Orders DB)]the comparison reports that Payments was renamed to Payments service, the queue and the fulfilment worker were added with their connections, and the API's direct connection to the database was removed.
What is compared, and how:
- Flowcharts, state, ER, and class diagrams are compared by structure: nodes, connections, and groups, matched by their ids.
- Sequence diagrams are compared by participants and messages: messages are lined up in order, so a reworded message shows as changed and a message moved to other participants as reconnected.
- Other types are compared line by line.
Two views help with big diagrams: Move together pans and zooms both sides at once, and Overlay lays one version over the other with a slider to fade between them. Comparing never changes either version.
Owners and review status
Signed in, open Review status (the badge in the top bar of a diagram or design document) to set an owner, mark it as a draft or as needing review, and choose how often it should be reviewed again.
stateDiagram-v2
state "Needs review" as NeedsReview
state "Changed since review" as ChangedSinceReview
state "Due for review" as Due
[*] --> Draft
Draft --> NeedsReview: ready for review
NeedsReview --> Reviewed: Mark as reviewed
Reviewed --> ChangedSinceReview: its content changes
Reviewed --> Due: review interval passes
ChangedSinceReview --> Reviewed: Mark as reviewed
Due --> Reviewed: Mark as reviewed- Mark as reviewed records the diagram as it is at that moment.
- If its content changes later, it shows Changed since review, and Compare with reviewed version marks exactly what changed. Moving nodes around doesn't count as a change.
- Needs review in the Projects sidebar lists every diagram waiting for a review, changed since one, or due for another, with a count; each card shows its status.
Owners and reviewers are names you type, and reminders appear in the app only, so nobody gets surprise emails.
A routine that keeps diagrams honest
- Give every important diagram an owner and a review interval: monthly for systems that change often, quarterly for the rest.
- Save a named version at every decision point ("After the queue migration").
- Check Needs review at the start of each sprint or planning session.
- Review with the comparison open: confirm each change is real, then Mark as reviewed.
Diagrams that live in a repository can be checked automatically too: see rendering and validating diagrams in CI. Writing up a reviewed design? See design documents.
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.