Architecture Versioning
Clone, compare, activate, and merge complete architecture baselines
Versions let a team preserve an agreed architecture baseline, explore changes in a candidate, and merge reviewed work without overwriting the starting point. Open History → Versions.
Selected And Active Versions
The version selector controls the model most project pages read. Confirm it before editing, analyzing, documenting, publishing, or using Archie.
An active version is the project's working baseline. A selected inactive version can be used for inspection or candidate work without immediately replacing that baseline.
Clone A Version
- Choose New Version.
- Name the intent, such as “Checkout resilience proposal.”
- Add a description and choose whether it should become active.
- Start the clone and follow its progress.
Cloning preserves origin mappings between related resources. Those mappings are what make later three-way comparison and merge possible.
The clone operation includes systems, relationships, workflows, deployments, Views, Context Map evidence, Behavior Model and workflow links, Capability Map, Data Model, Architecture Documents and View references, and architecture profiles.
Compare Versions
Select a source and target to review additions, removals, and field-level changes. The comparison registry covers:
| Resource family | Examples |
|---|---|
| Structure | Systems, hierarchy, resource requirements, and Relationships |
| Visual and runtime model | Views, Deployments, and Workflows |
| Semantic model | Capability Map, Data Model, and Behavior Model |
| Strategic context | Context relationships and Context Map layout state |
| Documentation | Architecture Documents and architecture profiles |
Purely presentational or volatile fields can be normalized or omitted to keep the diff focused on architectural meaning.
Merge
From a comparison, open the merge plan and review automatically resolvable changes and conflicts. Resolve every conflict deliberately before confirming the merge.
Origin tracking identifies corresponding resources across the lineage even when both branches changed. Always inspect the target again after a large merge before activating or publishing it.
Lineage
Each cloned version records its parent. The lineage view explains where a candidate originated and which baseline should be used for a meaningful three-way comparison.
Architecture Simulations can materialize an inactive candidate version. That candidate then follows the same comparison, activation, and merge process as a manually cloned version.
Project-Scoped Data Outside A Version
Project settings, sharing and group membership, account preferences, provider credentials, MCP tokens, source evidence, publication URLs, and guest tokens are not architecture-version content.
Practices
- Clone before a major redesign or migration.
- Name versions after intent, not sequence numbers alone.
- Keep a candidate inactive until its evidence has been reviewed.
- Compare before merge and validate again after merge.
- Avoid editing the wrong version by checking the selector when changing surfaces.
- Use Architecture Simulations for a durable what-if process rather than creating throwaway versions.