Legacy migration: a qualification management system

This is a textbook case summary. Events and outcomes illustrate teaching decisions, rather than measured customer adoption or returns.

Background

A running qualification management system had to move to a new architecture. The old system had no complete docs; business rules hid in code and historical data. Runtime was off limits. One wrong move could affect certificates in flight.

Process

Step one was recon, read only. Static reads of code, database structure, and config, with no runtime path touched. Recon produced a fact map of the old system, not assumptions.

Step two used event storming to recover the old workflow. Key events were laid out and ordered in time. Application, review, issuance, annual inspection, change: every line walked through. Where the order did not line up was where the system was not yet understood.

Step three was a strangler migration. The new system grew beside the old, taking over one business line at a time. Milestones were cut by engineering dimension, not by page. Each line passed a test gate before handover.

Key decisions

When an old rule was ambiguous, no guessing. A divergence record: where the ambiguity sits, the two readings, which was chosen, and why. Divergence records live in the repo, traveling with the code. Migration is not a rewrite but a block-by-block replacement, with the old system kept rollback-ready.

Result

Core business lines all moved to the new architecture. The old system stayed until migration closed out. Fact map, event storming output, and divergence records form a complete migration archive. Any new rule traces back to its old basis.