Codebase Analysis
Multi-dimensional analysis across complexity, coupling, dependencies, and code intelligence layers. Feeds complexity.json.
Modernization Techniques
ModernizeSpec is a specification, not a methodology. It defines what to capture about a legacy system, not how to capture it. But certain techniques pair well with the spec — they produce the data that populates domains.json, complexity.json, extraction-plan.json, and parity-tests.json.
This section documents those techniques. Each one is system-agnostic: it works on any legacy codebase regardless of language, framework, or domain. ERPNext appears throughout as a running example because it was the system that drove ModernizeSpec’s creation, but the techniques apply equally to a Rails monolith, a Java EE application, or a mainframe COBOL system.
Technique Categories
Section titled “Technique Categories”The techniques fall into three categories that follow the natural order of a modernization effort.
Analysis — Understand What You Have
Section titled “Analysis — Understand What You Have”Before changing anything, build a structured understanding of the legacy system. These techniques produce the data that feeds ModernizeSpec’s specification files.
Domain Decomposition
Breaking monoliths into bounded contexts using aggregate detection, capability mapping, and controller hierarchy analysis. Feeds domains.json.
Runtime Evidence
Using production traces and profiler data to discover actual system behavior — hot paths, dead code, implicit execution chains. Validates static analysis.
Migration — Move to the New System
Section titled “Migration — Move to the New System”With a structured understanding in hand, these techniques guide the actual extraction and migration work.
Strangler Fig Pattern
Incrementally replacing components while both systems run in parallel. State tracking, anti-corruption layers, and extraction sequencing. Feeds extraction-plan.json and migration-state.json.
Data Subsetting
Creating representative data subsets for testing — seed-based traversal, FK resolution, and anonymization. Enables realistic parity testing without production data.
Parity Testing
Proving behavioral equivalence between old and new implementations through characterization tests, behavioral snapshots, and confidence scoring. Feeds parity-tests.json.
Protection — Avoid Common Mistakes
Section titled “Protection — Avoid Common Mistakes”Modernization projects fail in predictable ways. These patterns help you avoid the traps.
Anti-Patterns
Eight common mistakes that derail modernization projects — wrapping without extracting, big bang rewrites, migrating everything, and more.
How Techniques Map to Spec Files
Section titled “How Techniques Map to Spec Files”Each technique produces data that flows into specific ModernizeSpec files:
| Technique | Primary Spec File | What It Produces |
|---|---|---|
| Codebase Analysis | complexity.json | Complexity scores, hotspot identification, tier assignments |
| Domain Decomposition | domains.json | Bounded contexts, coupling scores, aggregate boundaries |
| Runtime Evidence | complexity.json, domains.json | Validated hot paths, dead code flags, actual call graphs |
| Strangler Fig | extraction-plan.json, migration-state.json | Phase sequencing, dependency ordering, progress tracking |
| Data Subsetting | parity-tests.json | Test fixtures, data requirements, anonymization rules |
| Parity Testing | parity-tests.json | Test cases, confidence scores, baseline snapshots |
| Anti-Patterns | All files | Informs what not to do when populating the spec |
About the ERPNext Examples
Section titled “About the ERPNext Examples”ERPNext is used as the running example throughout these technique pages for practical reasons: it is the system that drove ModernizeSpec’s creation, the research data is published, and the numbers are concrete. ERPNext’s characteristics — 316K lines of Python, 521 entity types, deep framework coupling, implicit execution through hooks — are representative of the challenges most legacy modernizations face.
Every technique described here has been applied to ERPNext and validated through the migration experiments. But the techniques themselves contain nothing ERPNext-specific. Replace “DocType” with “ActiveRecord model” or “JPA entity” and the same analysis applies.
Next Steps
Section titled “Next Steps”Start with Codebase Analysis if you are beginning a new modernization effort. Start with Anti-Patterns if you want to audit an existing one.