Intermediate-State Diagram

A migration review is handed one picture of the system on the last day, when the old store is gone, every arrow points at the new component and every question has a clean answer. It is approved. Three months later the team cannot roll back, because writes have been accepted into the new store and both stores now hold rows the other does not.

The risky object in a migration is the sequence of states the system passes through, and a target-state diagram contains none of them. Every dangerous question is about a day it does not depict.

Why it matters

Reviews approve what they are shown. A target-state diagram is a correct, useful artefact for a steady-state design review, and used for a migration review it systematically hides the only thing worth interrogating: the step after which reversing costs a data-recovery project rather than a configuration change.

The series also changes the conversation's shape. Instead of "is the destination right", which the team has usually already settled, the review asks "is the irreversible step acceptable, and has everything reversible been front-loaded before it". That is a question a reviewer who does not know the system can ask well.

Implementation patterns

• Four to six diagrams for a six-month programme. Fewer and they hide steps; more and nobody reads the series.
• Same components, same layout, same notation in every frame, so the reader's eye tracks what changed rather than re-parsing the picture.
• Mark authority per entity, not per system: which store is authoritative for reads and which for writes, at this step. Dual authority is the condition to make visible.
• Write the rollback on each frame with its cost in time. "Revert the flag: 2 minutes" and "restore from backup and replay 6 hours of events" are both valid and they change the review.
• Mark the point of no return as a date and a condition. This is the single most valuable line in the pack.
• State the observable that proves each step succeeded before the next begins: a row-count delta, a reconciliation report at zero, an error budget untouched for a week.
• Keep the series in the repository next to the migration plan, and update the frame you are in rather than redrawing the set.

Industry example

Published migrations of large datastores from 2015 onwards share a structural feature: the programme is described as a sequence of reversible steps around one irreversible cutover, with dual-write and shadow-read phases named separately because their rollback behaviour differs. An archetype that makes the point concretely: a retail bank moving a core ledger drew five frames and discovered during the review that its planned step three, enabling writes to the new ledger while reads still came from the old, had no rollback at all once a single write had settled. The step was redesigned into two, with a reconciliation gate between them, before any code was written.

Failure scenarios

• The series is drawn after the plan is fixed, so it documents rather than interrogates.
• Rollback is written as "revert the deployment" for a step that has changed data. Deployments revert; rows do not.
• The point of no return is stated as a phase name rather than a date, so nobody notices passing it.
• Frames are drawn at different altitudes, so the reader cannot compare them and stops trying.
• The series is not updated as the migration moves, so the team's shared model is the frame they remember rather than the state they are in.

Trade-offs

Drawing the series costs a day or two of an architect's time and it front-loads argument: dual authority, reconciliation and rollback get debated before any code is written, which feels like delay to a team that wants to start. What it buys is the ability to say no to one step rather than to the whole programme, which is the only useful outcome a migration review can produce.

It also creates an artefact with an expiry. A stale series is worse than none, because a reader will believe it describes the current state.

When not to use it

A single-step migration behind a feature flag does not need a series; one sequence diagram of the switch, with its ordering and its revert, is better. Nor does a lift-and-shift with no schema change, where the risk is failure domains and a deployment diagram answers it. The pattern earns its cost when the data model changes under live traffic, or when the programme runs longer than one planning cycle and the team that finishes it will not be the team that started it.

Interview question

Q: You are reviewing a six-month migration from one datastore to another. The team brings a target-state container diagram. What do you ask for instead, and what specifically do you look for on it?

What a strong answer covers: the transition rather than the destination; per-entity read and write authority at each step; rollback with a cost in time; the dated point of no return; and the judgement to front-load reversible steps so the irreversible one happens as late and as small as possible.

Quick check

Quiz: What does a target-state diagram structurally hide in a migration review? Every intermediate state, including the step at which both stores hold authoritative data and rollback becomes data recovery.

Flashcard: What three annotations make a migration frame useful? Which store is authoritative for reads and writes, the rollback for this step with its cost in time, and whether this step is the point of no return.