Baselines, Drift Detection and Tamper Resistance

An architecture baseline is a named, immutable reference point that records the approved state of the architecture at a specific moment. Baselines answer the question: "What did the architecture look like when it was last reviewed and approved?" Everything that changes after a baseline is drift, which may be intentional evolution or unintended deviation.

NeoArc implements baselines as JSON files rather than git tags. This design decision has significant implications for enterprise environments where git tag permissions are restricted, squash merges are standard, and audit requirements are strict.

Baseline File Format

Each baseline is stored as a JSON file in the .neoarc-baselines/ directory within your workspace. The file captures everything needed to reproduce and verify the approved state.

Why File-Based Baselines

Traditional approaches use git tags to mark baselines. NeoArc chose file-based baselines for several practical reasons.

Tamper Detection

The integrityHash field is a SHA-256 hash computed over all other fields in the baseline file, serialised in canonical JSON order. When baselines are listed, the hash is recomputed and verified against the stored value.

Drift Dashboard

The drift dashboard measures how far the current architecture has moved from a selected baseline. Select a baseline and the system computes a drift percentage.

The drift percentage is calculated as: (modified + added + removed) / totalAtBaseline x 100. Thresholds are configurable in the team-shared .neoarc-studio/git-settings.json file.

Hotspot Detection

Beyond the overall drift percentage, the dashboard identifies hotspots: the files that change most frequently. The top 10 most modified files are shown with change counts, unique author counts, and last modified dates. Colour intensity increases with frequency, making it easy to spot areas of high architectural churn that may indicate instability or areas requiring closer governance attention.

Structural Hashing for Governance References

Drift detection also operates at the node level through structural hashing. When you link a governance block to an architectural node (for example, linking a risk block to a model entity), NeoArc records an FNV-1a hash of the node's structurally significant fields.

Per-Resource Approval

Baselines are project-wide snapshots, but different APIs and schemas ship at different times. When creating a baseline, the dialog shows a checklist of all APIs and schemas that have been modified since the previous baseline. All are ticked by default. The architect can untick resources that are not formally approved in this baseline.

This distinction matters for impact analysis. If a REST API was approved at v1 in an earlier baseline, and a later baseline only approves a webhook while the REST API has in-progress changes, impact analysis for the REST API compares against the earlier baseline where it was last approved. Each resource is tracked independently.

Baseline Comparison

You can compare any two baselines using their pinned commit SHAs. The comparison uses the semantic diff engine to produce an architectural change set: resources added, removed, modified, and renamed, with each change classified as structural or cosmetic. This shows exactly how the architecture evolved between two approved states.