How to version and approve an architecture diagram
Put a diagram through versioning and formal approval so the picture and the decision behind it stay together.
When this is useful
- An architecture change needs sign-off before implementation starts.
- Someone asks what the architecture looked like when a decision was taken.
- Two people are working on alternative designs for the same thing.
Before you start
- A diagram, and knowledge of who approves architecture changes in your organisation.
Step 1: Work on a branch for a substantial change
Branches let an alternative design be developed without disturbing the agreed one — the same reason branches exist for code.
Diagram ▸ Branches
Step 2: Check the history
Version history is what answers "what did this look like before?", which is usually the first question asked when something goes wrong.
Diagram ▸ Version history
Step 3: Submit for approval
The approval workflow records a decision against a version. This is the step that turns a diagram into a governed artefact: the sign-off attaches to a specific state, not to "the architecture".
Diagram ▸ Approval workflowDiagram ▸ Team & collaborators
What happens next
An approved version is a defensible reference point. Later changes are visible as changes against it rather than as a diagram that has always looked this way.
For teams that want architecture in the same review process as code, storing diagrams in GitHub is the next step.
Example
A platform change developed on a branch, reviewed against the approved version, and signed off with the approval recorded against that exact revision — which settled a question about scope four months later in one click.
Tips
- Approve versions, not diagrams. An approval that does not name a version tells you nothing a year later.
- Keep the branch until the change is approved. Merging early loses the ability to show what was proposed.
Limitations
- Versioning, branches and approvals are each separately enabled.
- An audit log records activity; confirm its scope with your administrator if you need it for compliance.