Help & Documentation

Learn how to use StructureGram

Diagram Versioning Overview

StructureGram's diagram versioning system allows you to save and manage multiple snapshots of your diagrams, making it safe to experiment with changes while preserving important configurations.

What is Diagram Versioning?

Diagram versioning creates immutable snapshots of your complete diagram state at a specific point in time. Each version captures:

  • Node positions and sizes - Where everything is placed on the canvas
  • Link vertices and label positions - Custom routing and label placements
  • Presentation settings - Hidden entities, custom colors, and styling
  • Scope configuration - Which entities are included in the diagram
  • Snapshot settings - Active date or date range for temporal views
  • Layout settings - Layout engine, routing algorithm, and viewport position
  • Legend visibility - Whether the legend is shown and where it's positioned

Think of versions as "checkpoints" or "save points" - you can always return to any saved version later.

Why Use Versioning?

Safe Experimentation

Try different layouts, hiding entities, or rearranging relationships without fear of losing your current configuration. If you don't like the changes, simply restore a previous version.

Track Evolution

Keep a history of how your diagram evolved over time. This is particularly useful for complex ownership structures that change as you refine your understanding.

Compare Approaches

Save multiple versions to compare different ways of presenting the same information. You might have one version optimized for presentation and another for detailed analysis.

Create Variants

Use the "Promote to Diagram" feature to create entirely new diagrams based on saved versions, allowing you to maintain multiple variations of similar structures.

Team Collaboration

Since any team member can save and restore versions, the system supports collaborative diagram development without worrying about who made the last change.

Working Copy vs. Versions

StructureGram uses a "Git-like" mental model:

  • Working Copy (Editable): The current diagram you see and edit. This is what you modify day-to-day, saved with Ctrl+S or "Save Layout"
  • Versions (Immutable Snapshots): Named copies stored separately that never change once saved

When you work on a diagram:

  1. You're always editing the working copy
  2. Pressing Ctrl+S saves your changes to the working copy
  3. Creating a version takes a snapshot of the working copy
  4. The version is frozen - it never changes
  5. You can restore any version to become the new working copy

Version Limitations

To keep the system performant and manageable:

  • Maximum 15 versions per diagram
  • When you save a 16th version, the oldest version is automatically deleted
  • Versions cannot be renamed or edited - they're immutable by design
  • Version names are simple text (no tags, categories, or long descriptions)

When to Create a Version

Good times to save a version:

  • ✅ Before major changes - Save a version before rearranging large sections
  • ✅ After completing a layout - Capture a "clean" state you might want to return to
  • ✅ Before presentations - Save the presentation-ready version
  • ✅ Before changing scope - Save before adding or removing entities from the diagram
  • ✅ Milestone configurations - Capture important states in your workflow

Avoid creating versions for:

  • ❌ Every small edit - Use normal "Save Layout" (Ctrl+S) for incremental changes
  • ❌ Experimental tweaks - Make changes first, create version only if you want to keep both states

Scope Immutability

One of the most important aspects of versioning is scope immutability. When you save a version:

  1. The system captures which entities are in the diagram at that moment
  2. That entity list is frozen with the version
  3. If you later add or remove entities from the diagram, old versions still show their original entity list
  4. Restoring a version also restores its scope (entity list)

Example:

  • You create an ownership diagram with 5 companies
  • You save "Version 1: Original Structure"
  • You add 3 more companies to the diagram
  • You save "Version 2: Expanded"
  • Version 1 still shows exactly 5 companies (immutable)
  • Version 2 shows all 8 companies
  • Restoring Version 1 shows the 5-company diagram, not the current 8-company state

This ensures versions are true historical snapshots, not references to current data.

Next Steps