User Guide for Patching Frappe & ERPNext Core

[sanjay]

Github: erpnext_user_guide/docs/knowledge_base/patching_handbook.md at main · sanjay-kumar001/erpnext_user_guide · GitHub

Production‑Grade Methodology for Runtime Monkey Patching
For Frappe Architects, ERPNext Architects, Enterprise Solution Designers, Framework Maintainers, and Developers modifying core behaviour

---

Index

Part 1 – Introduction and Decision Framework

• Chapter 1 – Executive Summary
• Chapter 2 – When Patching Is Necessary
• Chapter 3 – The Decision Framework: Override vs. Patch
• Chapter 4 – The Five Scenarios Analysed

Part 2 – Understanding Frappe Runtime Architecture

• Chapter 5 – Frappe Runtime Architecture Overview
• Chapter 6 – Process Types and Execution Contexts
• Chapter 7 – Why Monkey Patching Exists

Part 3 – Patching Mechanisms and Registration

• Chapter 8 – Hook Deep Dive
• Chapter 9 – Python Import System and the Role of __init__.py
• Chapter 10 – Frontend JavaScript Patching Mechanisms
• Chapter 11 – Backend Python Patching Mechanisms
• Chapter 12 – Complete Pros & Cons Analysis
• Chapter 13 – The Universal Solution: Safe __init__.py Patching
• Chapter 14 – Hybrid Registration Architecture

Part 4 – Enterprise Patch Framework

• Chapter 15 – Enterprise Patch Manager Architecture
• Chapter 16 – Enterprise Patch Registry Design
• Chapter 17 – Idempotent Monkey Patching Pattern
• Chapter 18 – Backend Monkey Patching Framework
• Chapter 19 – Frontend Monkey Patching Framework

Part 5 – Scenario‑Specific Implementations

• Chapter 20 – Scenario 1: Dashboard.setup_dashboard_sections()
• Chapter 21 – Scenario 2: QueryReport.prepare_columns()
• Chapter 22 – Scenario 3: Frontend TaxesAndTotals.calculate_item_values()
• Chapter 23 – Scenario 4: Backend calculate_item_values()
• Chapter 24 – Scenario 5: update_outgoing_rate_on_transaction()

Part 6 – Complete Sample Codebase and Architecture

• Chapter 25 – Complete Sample Codebase
• Chapter 26 – Complete __init__.py
• Chapter 27 – Complete runtime_patches.js
• Chapter 28 – Complete hooks.py Architecture
• Chapter 29 – Complete patch_manager.py
• Chapter 30 – Complete patch_registry.py

Part 7 – Testing, Validation, and Observability

• Chapter 31 – Testing Framework for Runtime Patches
• Chapter 32 – Bench Console Validation
• Chapter 33 – Worker Validation
• Chapter 34 – Repost Item Valuation Validation
• Chapter 35 – Verification and Debugging
• Chapter 36 – Observability and Logging

Part 8 – Production Deployment and Governance

• Chapter 37 – Production Deployment Architecture
• Chapter 38 – Upgrade Governance and Compatibility Testing
• Chapter 39 – Rollback Strategy
• Chapter 40 – Security Considerations
• Chapter 41 – Enterprise Governance Model
• Chapter 42 – Final Architect Recommendations

Part 9 – Appendices and Reference

• Appendix A – File Structure Reference
• Appendix B – Execution Context Matrix
• Appendix C – Gotchas, Edge Cases & FAQ
• Appendix D – Safety, Idempotency & Upgrade Proofing
• Appendix E – Documentation Template (patches.txt)