Versioning Graph Diagrams
Track changes to graph diagrams with snapshot versioning and lifecycle tagging. Create named snapshots, compare versions, and manage entity lifecycles with active, planned, and deprecated states.
Graph diagrams support version history, allowing you to track changes over time, create named snapshots, and restore previous states. Combined with lifecycle tagging, you can manage entity evolution by marking nodes as active, planned, or deprecated.
Version Storage
Graph diagram versions are stored in the same JSON file as the main diagram:
What Gets Versioned
Version snapshots capture the complete diagram state:
| Component | Versioned |
|---|---|
| Nodes (positions, labels, colours) | Yes |
| Node properties (types, constraints, values) | Yes |
| Node lifecycle status (active, planned, deprecated) | Yes |
| Edges (connections, labels, cardinality) | Yes |
| Edge properties | Yes |
| Tags and filtering state | Yes |
| View settings (zoom, pan) | No |
| Force simulation settings | No |
Creating a Version
Lifecycle Tagging on Graph Nodes
Individual nodes in a graph diagram can carry lifecycle status, providing a visual overlay of architectural intent.
| Status | Meaning | Visual Treatment |
|---|---|---|
| Active | Entity is live in production | Default styling, fully opaque |
| Planned | Entity is approved but not yet implemented | Dashed border or muted styling |
| Deprecated | Entity is being phased out | Faded or strikethrough styling |
Lifecycle status propagates to derived views. An entity marked as deprecated in the graph diagram appears as deprecated in ERD views, graph views, and search views automatically.
Succession Edges
When deprecating a node, assign its replacement using the replaced-by field. This creates traceable succession:
Version Metadata
Each version includes:
| Field | Description |
|---|---|
| ID | Unique identifier (auto-generated UUID) |
| Name | User-provided version name |
| Description | Optional description of changes |
| Timestamp | When the version was created |
| Node Count | Number of nodes in this version |
| Edge Count | Number of edges in this version |
Viewing Version History
The History panel shows all versions in chronological order with the most recent at the top.
Restoring a Version
Comparing Versions
You can compare any two versions to see what changed:
Change Detection
The versioning system detects changes at multiple levels:
| Change Type | Detection |
|---|---|
| Node added | New node ID not in previous version |
| Node removed | Node ID missing from current version |
| Node moved | Position changed beyond threshold |
| Node label changed | Label text differs |
| Lifecycle status changed | Status value changed (e.g., planned to active) |
| Property added | New property ID on existing node |
| Property modified | Property value, type, or constraints changed |
| Edge added/removed | Edge ID presence changed |
| Edge label changed | Edge label text differs |
Version Naming Conventions
Use descriptive names that indicate what changed:
| Good Names | Avoid |
|---|---|
| Added Customer relationships | v2 |
| Refactored Order properties | Update |
| Pre-review baseline | Snapshot 1 |
| After stakeholder feedback | Changes |
| Deprecated legacy payment entities | Cleanup |
Versioning vs Lifecycle Tagging
These two features serve different purposes and work together:
| Feature | Versioning | Lifecycle Tagging |
|---|---|---|
| Purpose | Track change history | Indicate architectural intent |
| Scope | Entire diagram snapshot | Individual node or edge |
| Question answered | What did this look like before? | Is this element live, planned, or retiring? |
| Use case | Undo/restore, audit trail | Migration planning, governance, roadmaps |