A team brings one target-state container diagram to the review of a six-month datastore migration. The review approves it. Three months in, rollback is impossible because both the old and the new store hold rows nothing else has. Which artefact should the review have required?
Show the full answer Hide the answer
The deciding property
The risky object in a migration is not the destination, it is the sequence of states the system passes through on the way, and a target-state diagram contains none of them. It shows the system on the last day, when the old store is gone and every question has a clean answer. Every dangerous question in a migration is about a day that the target-state diagram does not depict.
The specific failure in the stem has a name in practice: the migration passed the point where both stores held authoritative data, and nothing in the review asked when that point arrived or what reversing it would require. Once writes have landed in the new store and been accepted, going back means reconciling two divergent sets of rows, which is a data-recovery project rather than a rollback.
Why this diagram
An intermediate-state diagram is a short series, typically four to six pictures for a six-month programme, each showing the same components with three annotations a target-state diagram cannot carry:
- Which store is authoritative for reads and which for writes, per entity, at that step.
- The rollback for this step, and its cost in time. "Revert the flag, 2 minutes" and "restore from backup and replay 6 hours of events" are both valid answers and they change the review.
- The step at which rollback stops being possible, stated as a date and a condition. This is the single most valuable line in the pack and it is what the review exists to interrogate.
The review then asks the only question worth asking: is the irreversible step acceptable, and have we front-loaded everything reversible before it?
Why the other options fail
- The annotated target-state diagram is the artefact the team already brought. Ownership and technology labels are useful for a steady-state review and for on-boarding, and they say nothing about the transition. Right artefact for a design review of a new system, wrong one here.
- The deployment diagram is the correct answer to a different question, and a good one: it is what an auditor should get when they ask what happens if a zone fails. It becomes the right primary artefact when the migration is a relocation rather than a change of data model.
- The sequence diagram of the write path is genuinely valuable, and it is where compensations and ordering get settled. It works at the granularity of one request, whereas the failure here was at the granularity of the programme.
- The data-flow diagram is the right artefact when the migration crosses a jurisdiction or a trust boundary, and it is what a privacy reviewer needs. It would not have surfaced the dual-authority problem, because trust boundaries did not change.
What would flip the decision
| If this changes | Require instead | Because |
|---|---|---|
| The move is lift-and-shift with no schema change | Deployment diagram | The risk is topology and failure domains |
| Data crosses a new jurisdiction | Data-flow diagram | The binding constraint is legal not technical |
| The cutover is a single atomic switch under a flag | Sequence diagram of the switch | There is one state transition and its ordering is the risk |
Common weak answers
- "Add a rollback plan appendix." A plan in prose is not reviewable at the speed of a review. The reason the picture works is that the irreversible step is visible in one glance rather than on page nine.
- "Review more often." More reviews of the wrong artefact produce more approvals.