Snapshots & gap analysis

In simple terms

A snapshot is a saved photograph of a whole scenario: the assumptions, the sizing, and the solved results, frozen under a name. The Snapshots room lets you browse your history, open one, or compare two — and when you compare, it shows you exactly which inputs changed and how each one moved the cost. It’s how you tell the story of how a design evolved.

Why it exists

Developers iterate: try a bigger electrolyser, a cheaper battery, a different product mix. Without history you lose the trail. Snapshots retain full solved scenarios so any two designs are comparable later, with a deterministic input-and-output diff — the provenance the product is built to sell.

Where it lives

Room: frontend/src/rooms/snapshots/ (SnapshotsRoom, SnapshotDetailPanel, SnapshotComparePanel, SnapshotGap, snapHelpers.ts).
Capture: the cockpit’s ⎚ Snapshot button; backend POST /projects/{id}/snapshots stores book + config + a fresh solve.

What a snapshot captures (vs a version)

Snapshot = a full result (book + sizing config + the solved bundle), optionally a frozen feasibility frame. Named, timestamped.
Version = an input-set only (assumptions or sizing), on one of the two version axes.

A scenario across both version axes plus its results is exactly a snapshot. See the data model.

How it works, step by step

Timeline (left rail). All snapshots, searchable. Click one to view; ⌘/Ctrl-click a second to compare. The selection is shareable via the URL hash (#snap=<id> / #cmp=<a>,<b>).
Single snapshot → detail. SnapshotDetailPanel is a mini-cockpit rendered from the stored bundle: FlowDiagram + LCO hero + KPI strip + CostBuildup + EnergyBalance + CapexBreakdown + LcoBreakdown + production rows.
Two snapshots → compare + gap. SnapshotComparePanel shows paired LCO heroes with green/red deltas, a KPI-delta strip, and side-by-side FlowDiagrams. Then SnapshotGap breaks the move down in three deterministic panels (no engine re-solve):
- (a) Inputs that changed — a searchable, sortable diff of every book param + sizing field where A ≠ B (with labels, group, absolute + % Δ).
- (b) Output deltas by component — signed bars for CAPEX (per component), OPEX, and production (per molecule).
- (c) LCO bridge — a per-product mini-waterfall that recomposes the LCO move and reconciles exactly to LCO_B − LCO_A.
Restore. Writes a snapshot’s book + config back onto the project.
Export. The .zip bundle (and any feasibility frame) is regenerated on demand — nothing is pre-stored.

Gap analysis: what it is (and isn’t)

The gap panels are closed-form and deterministic — a direct decomposition that reconciles to the exact LCO delta. They are intentionally not a Shapley / single-variable attribution (which would need many re-solves and make interdependent inputs look independent). The honest promise is “here is everything that changed and how the arithmetic of the cost moved,” not “input X caused Y% of the change.”

Annual ↔ timeseries comparability

An NH₃-only project stores a single-chain bundle in annual mode but a multi bundle in timeseries mode; the room normalises these to a common representation so the two are comparable (a reconciliation tracked as an open item). Feasibility snapshots that both carry frames also get a dispatch-delta strip.

Failure & edge cases

Comparing incompatible shapes (single-chain vs multi) is normalised rather than failing; if a metric can’t align it’s shown as n/a, never a wrong number.
A cold deep-link (#cmp=… on first load) may briefly show an empty pane while the bundles fetch — it fills in once loaded (not a bug).

How to modify this safely

The gap decomposition must keep reconciling exactly to the LCO delta — if you change financials, re-check the LCO bridge closes.
Snapshots store structured JSON, not artefacts — keep exports regenerated on demand.