An open playbook

From thirty-year-old legacy to an AI-native platform.

Without dropping a cent. The playbook for modernizing systems that cannot be allowed to break.

Parity, proven value by valueevery record reconciled at intermediate and final stages, nothing sampled
AI recovers the lost intentagents read undocumented logic, humans ratify every rule
Agents in the workflowthe target is AI-native and event-driven, not merely cloud-hosted
Built to be run, not just readModernization OS: four skills that read your own repo →

By Nik Jain. I architect money-critical legacy platforms into AI-native ones. ·LinkedIn ·X ·GitHub

The journey

What actually changes. Both ends of it.

For banks, governments, insurers, healthcare, ERP and mainframes. Most writing on legacy modernization stops at "do not break it," which is a constraint, not a destination. Every item on the right is something the flagship program shipped.

Where you are
A thirty-year-old core
  • Business rules in the database, thousands of lines of stored procedures nobody has read end to end
  • Overnight batch, so the answer to any question arrives tomorrow morning
  • Rules in spreadsheets, on desktops, invisible to every migration tool
  • Manual workflows absorbing hundreds of hours a year in checking and reconciliation
→
Where you land
An AI-native platform
  • Logic in versioned services you can read, test, and change without fear
  • Event-driven and intraday, so the answer exists as it happens
  • Shadow rules brought inside and governed like the code they always were
  • Agents in the workflow, removing manual toil under guardrails that survive an audit
The thesis

The hard part is epistemic.

The cloud target, the services, the pipelines: well understood, and frankly the easy part. The hard part is knowing the new system is right.

Parity first. Speed, cost, and elegance are negotiable. Correctness is not.

No migration tool can read a spreadsheet
Decades of business rules end up in macros, reports, and user-built apps. Code-only translation structurally cannot see them, so those rules vanish silently and nobody notices until a number drifts. Finding them is half the work.
AI translates. Evidence certifies.
Agents are genuinely good at recovering what undocumented code does, and that is where they belong. What proves the new system is right is running both and comparing every value, not a model's confidence.

Independent confirmation, from four directions: Google built Dual Run to certify mainframe parity on live traffic, UK GDS mandates dark-launch comparison testing, Mechanical Orchard sells behavior-first equivalence proof, and Michael Feathers taught us to pin behavior with characterization tests two decades ago.

How to do it

A sequence, not a catalogue.

Nine chapters, arranged as the four stages of one journey. Read in order the first time, then go straight to the stage you are living through.

Understand→Rebuild→Prove→Switch Parity is numbered 01 in the repo because it governs all four stages, not because it happens first.
The pattern
Supporting material
Stage 01
Understand what you have
nothing downstream is safe first
Pattern 01
Get the rules out of the database
Logic executing in the data layer for decades
Deep-dive
Legacy-code archaeology
Agents recover intent, humans ratify it
Decision tree
Choose your strategy per app
The 7Rs and TIME, as a walkable tree
Stage 02
Rebuild it as something modern
where the destination gets built
Pattern 02
Replace it piece by piece
Never one irreversible moment
Pattern 03
Move off overnight batch
Events and sagas, intraday
Pattern 04
Put agents on real money
Guardrails that survive an audit
Pattern 05
Make non-determinism safe
When part of the system is an LLM
Decision tree
Rewrite, strangle, or wrap?
The core decision, with tradeoffs
Stage 03
Prove it is right
the stage everyone underestimates
Pattern 06
Prove the numbers match
A contract nobody may renegotiate
Deep-dive
The parity harness
Every value, including reports and spreadsheets
Template
Parity report
Evidence plus the accepted-difference log
Stage 04
Switch over
anticlimactic, if the first three were done
Pattern 07
Switch over without drama
A promotion of evidence, not a leap
Decision tree
Choose your cutover style
Big-bang, parallel run, or phased
Template
Cutover runbook
Owned steps, a rollback trigger on each
Modernization OS

The playbook, as something you run.

Four skills that install into your own repository, read your actual code, and write a readiness scorecard, a plan review, a cutover runbook and a rollback plan. Twelve categories scored, five of which block a date.

See what it writes, and install it →

Why programs fail

Twelve ways it goes wrong. Every one sourced.

Grouped by what is actually failing, because the fix differs completely between them. Each links to the chapter that addresses it.

These are not failures of technology. They are failures of understanding, verification, and cutover discipline, which is what the twelve categories below are organized around. Eight of them are written up in full: read the post-mortem library →

Understanding the old systemthe comprehension bottleneck
01
Nobody knows how it works
Decades of undocumented logic, and the authors are long gone
02
The people who knew have left
A skills cliff, and the survivors are already fully booked
Proving correctnesswhere money-critical programs actually die
03
The numbers do not match
Data moved cleanly and quietly stopped meaning the same thing
04
We cannot prove it is right
Plenty of testing, no evidence anyone will sign
Execution and architectureself-inflicted damage
05
One weekend, no way back
Big-bang switching, with a rollback nobody rehearsed
07
Starting over never finishes
The rewrite trap, and why it always feels like the rational choice
10
Microservices you did not need
Over-modernization, and the quiet retreat back to a monolith
Money, politics and peoplenot technology problems at all
06
It costs many times the estimate
Escalation by an order of magnitude, and the structural reasons
08
Nobody owns the outcome
Accountability spread thin enough that no one can be wrong
09
A vendor ends up owning your core
Handing away the one capability you cannot buy back
The modern eranew answers, new ways to be wrong
11
What AI genuinely cannot do
Documented limits, and the tasks agents quietly fail at
12
Doing nothing is a decision too
Deferral has a bill, and it arrives without warning
What to produce

Twelve artifacts. Each one ends an argument.

Copy-paste markdown, grouped by the stage that produces them. Industry names kept throughout, because those are the terms practitioners search for and recognize.

Inventory and assessbefore any decision is defensible
01
Application inventory
Every app, its disposition, and the person accountable for it
02
Legacy knowledge map
The people who hold what nobody ever wrote down
03
Risk register
Scored and owned, rather than remembered in a meeting
04
Dependency map
What breaks the moment this thing moves
Decideand leave a trace of why
05
Business case
The money argument, directional first and detailed later
06
ADR
One decision, one page, still findable in two years
Plan the wavesnothing moves without criteria
07
Wave plan
Which populations move when, and what must be true first
08
RACI
One accountable name per workstream, not a committee
Prove paritythe evidence three people will sign
09
Characterization test plan
Pin what the old system does today, before touching it
10
Parity report
Match rates, open discrepancies, and every signed exception
Cut overrehearsed, reversible, owned
11
Cutover runbook
Minute by minute, with a rollback trigger on every step
12
Rollback plan
Abort criteria agreed before anyone is under pressure
Start here

Three roles, one hour each.

Pick your seat at the table. Each path is an hour of reading, then the learning paths take you deeper by role and time budget.

CTO / executive sponsor
1 hour
  1. Start with why programs fail, the twelve sourced categories
  2. Then cutover strategy, which is where the money is lost in a weekend
  3. Read the flagship case study for what a defensible program looks like
Program / product leader
1 hour
  1. Start with what went wrong in public, so you know the shapes to avoid
  2. Then the business case and the wave plan: what you are funding, and what moves when
  3. Score yourself against the readiness scorecard before committing a date
Engineering / architect
1 hour
  1. Start with legacy-code archaeology: recover the rules before you touch anything
  2. Then the parity harness, the machinery that proves you got it right
  3. Then the templates you will actually fill: characterization tests, parity report, runbook

Any role, honest look in the mirror: the readiness scorecard. One hour, 12 categories, no mercy.

Who wrote this

Architecting legacy cores into AI-native platforms.

Earned in production, not assembled from blog posts. I am Nik Jain. 14+ years across multiple industries, from asset management to auto-tech and ed-tech, including co-founding and scaling a company to 450+ people, and Forbes 30 Under 30 Asia. I own these programs end to end.

$1.6T
assets on the platform modernized
$4.5B
in trades flowing through per day
12+ week
production parallel run before cutover
5,000+
scenarios, answers agreed up front

A hands-on leader across product, program, and technical delivery, architecture included, through to the agentic, AI-native platform itself. When a thirty-year-old module has no specification, someone has to reconstruct one from the system itself. I did that work personally: reverse-engineering logic nobody fully understood, then designing the services that replaced it.

AI-native target architecture
Event-driven services replacing overnight batch. Agents embedded where work was manual.
Parity as the contract
Every value matched at intermediate and final stages, proven by a purpose-built harness.
AI-assisted archaeology
Agents recover intent from undocumented logic. Humans ratify every rule.
Wave sequencing
Heaviest work front-loaded, archaeology pipelined against the build, dates held.

Driven with SMEs, business partners, and other leads, never alone. Full detail in the flagship case study.

Take it

MIT licensed. Use it, improve it.

This is meant to become a standard, and a standard is something people use and correct, not something they admire. Three ways to be part of it.