Full Replacement
521 doctypes, all modules, framework replacement. Not feasible in 3 months — estimated 26-43 months of work.
ERPNext Case Study
ModernizeSpec did not start as a specification. It started as an internal need: PearlThoughts was migrating ERPNext from Python/Frappe to Go, and the teams needed a structured way to describe the legacy system to AI agents.
This case study documents the journey from internal tooling to open standard.
ERPNext at a Glance
Section titled “ERPNext at a Glance”| Dimension | Value |
|---|---|
| First commit | 2005-2006 (GitHub 2011) |
| Python lines of code | 316,679 |
| JavaScript lines of code | 73,932 |
| Unique doctypes (entities) | 521 |
| API endpoints | 768 |
| Standard reports | ~177 |
| Modules | 21 |
| GitHub stars | 31,400+ |
| COCOMO estimate | ~216 person-years |
ERPNext is one of the longest-running open-source ERP systems. Its 20 years of development produced a monolithic codebase deeply coupled to the Frappe framework, with implicit execution paths driven by a hooks system and a controller inheritance chain where a single file (accounts_controller.py, 4,412 lines, 168 functions) affects every financial transaction.
The Migration Challenge
Section titled “The Migration Challenge”The core question: Can 3-5 interns migrate ERPNext from Python to Go in 3 months with unlimited AI credits?
Core Accounting
~75 doctypes covering GL, Tax, Invoicing, Payments. Achievable in 3 months with a focused team.
Core + Stock + Selling
~150 doctypes covering 60% of business value. Achievable in 6-9 months.
Production-Ready (80% Parity)
~400 doctypes + framework + frontend. Requires 8-12 engineers over 12-18 months.
The Experiment
Section titled “The Experiment”PearlThoughts ran two parallel tracks:
Reference Implementation (SenG)
Section titled “Reference Implementation (SenG)”Three iterations extracting core accounting modules into idiomatic Go using hexagonal architecture:
| Iteration | Python Source | Go Output | Tests |
|---|---|---|---|
| Mode of Payment | 66 lines | 518 lines | 19 |
| Tax Calculator | 1,334 lines | 1,240 lines | 24 |
| GL Entry Engine | 878 lines | 2,608 lines | 32 |
68 passing parity tests, zero external dependencies.
Intern Teams (7 teams, 40-50+ interns)
Section titled “Intern Teams (7 teams, 40-50+ interns)”| Team | Focus | Key Achievement |
|---|---|---|
| Alpha | Accounts Modernization | RAG system with Streamlit UI |
| Beta | AI-Driven Modernization | VS Code extension (1,700 LOC), 600x Redis caching |
| Gamma | Graph-Augmented RAG | +2.5 accuracy over flat RAG on golden dataset |
| Delta | Code Analyzer and Transpiler | Python-to-Go AST transpiler |
| Epsilon | Parity Testing | CI-ready parity tests, best engineering discipline |
| Zeta | Tax Calculation | 100% tax calculation parity (independently replicated) |
| Eta | RAG Evaluation | Evaluation pipeline (infrastructure issues limited output) |
What Was Proven
Section titled “What Was Proven”- Hexagonal extraction works. Business logic separates cleanly from Frappe framework dependencies using ports and adapters.
- Parity testing is achievable. Table-driven Go tests verify functional equivalence against Python behavior.
- The pattern is reproducible. Team Zeta independently replicated tax calculation parity from the reference repo without direct mentorship.
- AI accelerates understanding. Graph-augmented RAG outperforms naive retrieval by +2.5 accuracy for hook-driven architectures.
- Team quality matters more than team size. A solo contributor (Zeta) matched 4-person teams in output.
What Remained Unproven
Section titled “What Remained Unproven”- Production database adapters (only interfaces exist)
- Framework replacement (Frappe’s ORM, permissions, workflow, multi-tenancy)
- Scale beyond Accounts module (no team attempted Stock, Manufacturing, or CRM)
- Frontend migration (73,932 lines of JavaScript untouched)
- Cross-module integration testing
From Internal Tooling to Open Standard
Section titled “From Internal Tooling to Open Standard”The .agents/modernization/ directory structure, the DDD mapping format, the extraction sequencing schema, and the parity verification approach were all built for this specific migration. But none of them contained anything ERPNext-specific at the schema level.
The feasibility analysis confirmed: every concept generalizes. What was internal tooling could become an open specification.
That specification became ModernizeSpec.
Case Study Contents
Section titled “Case Study Contents”Platform Analysis
Deep dive into ERPNext’s architecture, DocType system, controller inheritance chain, and what makes it hard to migrate.
Migration Experiments
Three Go extraction iterations with hexagonal architecture, parity testing methodology, and results.
Ongoing Experimentation
Seven teams running parallel experiments. We update the spec as we learn.