Specification Baselines
A Specification Baseline is a named, point-in-time snapshot of an item’s complete specification. Baselines let you preserve exactly what was agreed and documented at a specific milestone — a sprint boundary, a design review, a release — and compare it against the current state of the architecture at any later point.
Baselines are created per model item. Each baseline captures that item’s properties, narrative, diagrams, and all the versions of its dependencies at the moment the snapshot was taken.
Creating a Baseline
The baseline controls appear at the top of the Specification tab for any model item.
To create a baseline:
- Open the Specification tab for the item
- Click Create Baseline
- Enter a name for the baseline — for example, Sprint 12 Delivery or Design Review v2
- Optionally add a description to record the context or reason for the snapshot
- Click Create Baseline to confirm
Only project Editors and Admins can create baselines. Viewers can read baselines but cannot create or delete them.
The baseline is created immediately. The count on the Baselines button updates to reflect the new total.
What Gets Captured
When a baseline is created, ArchRepo records:
- The item’s current properties — name, ref, status, type, version, approval state, and all type-specific fields
- The full narrative as a rendered Markdown document, frozen at that point in time
- The version of every dependency, including:
- Outbound related items (and their current versions)
- Model items embedded in the narrative
- Draw.io diagrams and images embedded in the narrative
- Data entities referenced in the narrative
These dependency versions form the version manifest — the basis for drift detection when you view the baseline later.
Viewing Baselines
Click the Baselines button (which shows the baseline count) to open the baseline list for that item.
Each row shows:
- The baseline name and creation date
- Who created it
- An optional description
- The number of items captured in the snapshot
Click any row to open the drift analysis for that baseline.
Drift Analysis
The drift view shows what has changed in the item and its dependencies since the baseline was captured.
Each dependency is shown with a status indicator:
- Green tick — no changes detected; this dependency matches its baseline version
- Orange cross — this dependency has changed since the baseline was taken, with the baseline version and current version shown side by side (e.g. v2 → v4)
A summary callout at the top shows whether the item is clean or has outstanding changes.
The dependency types checked are:
| Type | What it tracks |
|---|---|
| Item properties | The main item’s own version (increments when properties are saved) |
| Narrative | The narrative’s version (increments when narrative content is saved) |
| Related item | Each outbound related model item’s version |
| Embedded item | Model items referenced inline in the narrative |
| Media | Draw.io diagrams and images embedded in the narrative |
| Data entity | Data entities from DataSet blocks in the narrative |
Viewing the Full Frozen Specification
From the drift view, click View Full Specification to open the complete frozen spec for that baseline. This page shows the full Markdown document exactly as it was at the time the baseline was captured — including properties, narrative, diagrams, and relationships.
A banner at the top of the page identifies this as a baseline view and provides a link back to the current live specification.
You can also download the frozen specification as a Markdown file using the Download button.
The frozen specification is read-only. It reflects the state of the item at the moment the baseline was created and cannot be edited.
Deleting a Baseline
Project Admins can delete a baseline using the trash icon on the baseline row.
Deleting a baseline is permanent. The frozen snapshot and all associated version history will be lost and cannot be recovered.
A confirmation dialog is shown before deletion proceeds.
Common Uses
Sprint or release tracking — Create a baseline at the end of each sprint or before a release. Use the drift view later to see what changed after the handoff.
Design reviews — Baseline the specification before a design review meeting. After feedback is incorporated, the drift view shows reviewers exactly what changed.
Handoff documentation — Share the frozen specification link with a development team as a stable reference that won’t change as the architecture evolves.
Regression detection — If a related item is updated by another team, the drift analysis will flag it, alerting you that a dependency has moved on from what was agreed.