Versioning

Archflow's versioning system lets you create, compare, and merge snapshots of your architecture at different points in time.

How Versioning Works

Each project can have multiple versions. A version captures the complete state of:

• Systems and their properties (including resource requirements)
• Connections between systems
• System hierarchy and nesting
• Diagrams and element placements
• Workflows and business processes
• Deployments and infrastructure
• Custom documentation pages

When you clone a version, every entity is duplicated with an origin tracking ID that links it back to the original --- enabling diffing and merging later.

Versions Page

Navigate to Versions in the project sidebar to see all versions. Each version card shows:

• Version name and description
• Active badge on the current working version
• Parent version --- which version it was cloned from
• Creation date
• Actions menu (edit, activate, delete)

Version Picker

The version picker dropdown appears in the project header, next to the page title. It displays the current version name (e.g., "main") and allows you to switch between versions.

Cloning a Version

Creating a new version is a clone operation that duplicates the entire architecture state:

1. Click New Version on the Versions page (or use the version picker)
2. Provide a version name (e.g., "v2.0 - Microservices Migration")
3. Optionally add a description
4. Choose whether to set as active --- this makes the new version your current working version
5. Click Clone

The clone dialog shows real-time streaming progress as each entity type is copied:

• Preparing → Systems → Connections → Workflows → Deployments → Diagrams → Relationships → Documentation

Each phase shows a progress indicator so you can track the operation.

Switching Versions

Use the version picker dropdown or the Activate action on a version card. When you switch:

• The Systems list updates to show systems in the selected version
• Connections reflect the relationships in that version
• Diagrams show the architecture as it appeared in that version
• Workflows and Deployments update to match the version
• Archie provides context based on the selected version

Comparing Versions (Diff)

Compare two versions to see what changed:

1. Navigate to the Versions page
2. Select two versions to compare
3. View a three-way diff showing:
   • Added entities --- new systems, connections, or other elements
   • Removed entities --- elements that were deleted
   • Changed entities --- elements with modified properties, shown with field-level diffs

The diff view groups changes by entity type (systems, connections, workflows, deployments, diagrams) and highlights specific field changes for each modified entity.

Overview diagrams and visual-only state fields are excluded from the diff to reduce noise.

Merging Versions

Merge changes from one version into another:

1. From the diff view, click Merge
2. Review the merge plan showing all changes that will be applied
3. The merge summary bar shows:
   • Number of conflicts (if any)
   • Auto-resolved changes
   • Manual resolution progress
4. Resolve any conflicts, then confirm the merge

The merge system uses origin entity tracking to match entities across versions, ensuring accurate three-way diffs even when entities have been modified in both versions.

Version Lineage

Versions track their parent --- which version they were cloned from. This creates a lineage tree showing how your architecture evolved over time. View the lineage from the Versions page to understand the branching history of your project.

Version-Aware Features

Several Archflow features are version-aware:

• Export --- Export a specific version of your project
• Documentation --- Generate documentation for a specific version
• Diagrams --- View diagrams as they appeared in previous versions
• Import --- Imported data is associated with the current version
• Archie --- AI analysis uses the selected version's data

What Gets Versioned

Best Practices

• Clone before major changes --- Create a version before significant architecture modifications
• Use meaningful names --- "v2.0 - Microservices Migration" is more useful than "Version 5"
• Add descriptions --- Note what's different or what you're exploring in this version
• Use the "main" version --- The default version serves as your current working state
• Compare before merging --- Always review the diff before merging changes back
• Keep lineage clean --- Clone from the version that makes the most sense as a starting point