Use Case Guide

Migration diagram: current state, target state, and the transition nobody draws

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Every migration produces two diagrams and needs three. The current state and the target state get drawn in the kickoff deck. The transition architecture, the machinery that exists only while both systems run, is the one that causes the incidents, blows the budget, and outlives the project because nobody wrote down that it was temporary. And the target diagram is a forecast rather than a report until something grounds it, which over the quarters a real migration takes is a distinction with consequences.

Try it free
7 min readFor data teams explaining a migration to the people it affects

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

193/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Three diagrams, not two

The current state and target state pair is the standard, and it hides the expensive part. Between them sits a transition architecture: replication services, change data capture streams, dual writes, reconciliation jobs, and mediating platforms that exist for the migration and are supposed to be decommissioned after it. They have to be provisioned, secured, paid for, and then removed, and the removal is what gets forgotten.

Draw it as its own view. A transition component that appears on a diagram with an owner and an expected end date is a component somebody eventually turns off. One that lives only in a runbook step becomes permanent infrastructure that nobody can explain two years later.

The transition view is also the one your security reviewer should see. Temporary replication infrastructure often carries production data through a path that no threat model covers, precisely because everyone considers it temporary.

Show what moves, what is rebuilt, and what is left alone

The question every stakeholder asks about a migration is whether their thing is affected. A diagram that answers it directly saves a quarter of the meetings. Group the current-state systems by fate rather than by layer: lifted as-is, rebuilt on the new platform, retired, and untouched. Four zones, and most people can find their answer without asking.

For a data platform migration, the field level matters as much as the system level, because the breaking changes are usually renames and type changes rather than moved tables. Column-level lineage from the old model to the new one is what the analytics team needs, and it is a different artefact from the box diagram the sponsor reads. See lineage.

Label the edges with what changes about them, not just with what they carry. An arrow that says nightly extract becomes streaming CDC is doing more work than an arrow that says data, because it tells a downstream consumer that their assumptions about freshness are about to change.

Keeping the target diagram honest over two quarters

A target architecture drawn at kickoff is a forecast, and forecasts drift. Six months in, the target diagram in the project wiki usually describes a design that was abandoned in month two, and the people making decisions from it do not know that.

Connect the repository of the new platform as soon as it has one. From that point the target diagram stops being a forecast and becomes a report: the branch is re-read about once a day, the diagram and the architecture document regenerate, and the commit that quietly replaced the streaming layer shows up in the picture without anybody filing a documentation ticket. The current-state diagram stays hand-drawn, because the system it describes is the one you are leaving.

On a Terraform target platform the environment story comes out of the parse rather than out of a caption. A resource whose count resolves to zero in an environment is drawn as not deployed instead of being silently omitted, and a for_each driven by a variable is resolved against the tfvars files under the environments directory, so the node label carries the per-environment split, two in DEV and one in QUAL, rather than a vague plural. On a migration where two environments run at different speeds, that one label answers the question every steering meeting opens with.

At cutover the target diagram simply becomes the current one, with no redraw, and the transition view can be archived as the record of what needs to be switched off. That is the moment to go through it component by component.

One project per view

Keep current, target, and transition as three projects in the same folder rather than three layers of one canvas. They have different lifespans and different audiences, and only one of them should be connected to a repository.

Getting it in front of the people it affects

Migration communication fails by attachment. A picture emailed in March is the picture people are still working from in July, and every correction since then lives in a thread they were not on. Send a link instead: a view-only page opens without a sign-in, so the finance analyst who owns a downstream dashboard can look at the current target without an account.

Embed the target diagram in the migration page on your wiki with one markdown image line and the page stops needing an owner who refreshes screenshots each sprint. Over a two-quarter migration, that is the difference between a page people trust and a page people check with you before believing.

Export PNG or JPEG for the steering committee deck. The deck is a snapshot by nature, so date the figure and keep the link in the appendix for anyone who wants the current version.

FAQ

What is a transition architecture in a migration diagram?

The machinery that exists only while both systems run: replication services, change data capture streams, dual writes, reconciliation jobs, and mediating platforms. It has to be provisioned, secured, paid for, and decommissioned, and drawing it as its own view with an owner and an expected end date is what makes the decommissioning happen.

How should the current-state diagram be organised?

By fate rather than by layer. Group systems into lifted as-is, rebuilt on the new platform, retired, and untouched. Stakeholders reading a migration diagram are almost always looking for whether their system is affected, and four zones answer that without a meeting.

How do we stop the target diagram from drifting during a long migration?

Connect the repository of the new platform as soon as it exists. The branch is re-read about once a day and the diagram regenerates, so a design change that lands in code shows up in the picture. The current-state diagram stays hand-drawn, because the system it describes is the one being left behind.

Should the three views be one diagram or three?

Three projects in the same folder. They have different audiences and different lifespans: the current-state view is archived at cutover, the target view becomes the current one, and the transition view becomes the checklist of what to switch off.

How do downstream teams find out what changes for them?

Label edges with what changes about them rather than with what they carry, so an arrow reads nightly extract becomes streaming change data capture. For data platforms, add column-level lineage from the old model to the new one, since renames and type changes break more consumers than moved tables do.