View source for PAD-Driven ERPNext Strategy 260303

= PAD-Driven ERPNext Implementation Strategy for Comfac IT =

'''Date:''' 3 March 2026<br>
'''Purpose:''' Drastically improve the speed of implementation, configuration, and deployment in Frappe ERPNext for the Comfac IT team using Procedural Agentic Development (PAD) tools (e.g., OpenCode, ClaudeCode).

== 1. Problem Statement ==

'''Current State:''' Implementation and configuration of Frappe/ERPNext are traditionally slow, requiring deep domain knowledge of both the business processes and the proprietary Frappe framework.

'''Objective:''' Drastically improve the speed of implementation, configuration, and deployment in Frappe ERPNext for the Comfac IT team using PAD tools.

== 2. Definition of Terms ==

{| class="wikitable"
! Term !! Definition
|-
| '''PAD''' (Procedural Agentic Development) || A workflow utilizing autonomous AI coding agents (e.g., OpenCode, ClaudeCode) to automate software development, configuration, and deployment. The process involves the agent continuously referencing a strict set of inputs — the PRD, System Prompt (SP), Notes, and Knowledge Base (KB) — to generate configurations or code. The user reviews the output and provides feedback (logged into Notes), creating an iterative, self-correcting loop that requires minimum human supervision to achieve the final target state.
|-
| '''PRD''' (Product Requirements Document) || A clear, human-readable document defining the business logic, required features, and specifications for a given customization.
|-
| '''SP''' (System Prompt) || The precise, technical instructions fed to the AI agent detailing exactly how to execute the PRD within the target environment.
|-
| '''Frappe Framework''' || The underlying low-code, metadata-driven Python/JavaScript web framework that powers ERPNext.
|-
| '''ERPNext''' || The open-source enterprise resource planning suite built on the Frappe framework.
|-
| '''Frappe Cloud''' || The managed Platform-as-a-Service (PaaS) hosting environment used to deploy and manage Frappe/ERPNext instances.
|-
| '''Bench''' || The essential command-line utility (CLI) used to manage Frappe environments, install custom apps, and run database migrations.
|-
| '''DocType''' || The core building block in the Frappe ecosystem; it simultaneously represents a database table, a user interface web form, and its associated business logic.
|-
| '''Fixtures''' || A Frappe mechanism used to export database-level configurations (like Custom Fields, Property Setters, and Workflows) into JSON files so they can be version-controlled in a Git repository.
|}

== 3. The PAD Workflow Methodology ==

Every configuration or customization task is governed by the following four-pillar workflow, all documented and stored in the Comfac IT MediaWiki:

{| class="wikitable"
! Pillar !! Name !! Description
|-
| 1 || '''PRD''' (Product Requirements Document) || Defines the business logic, required DocType changes, workflows, and print formats.
|-
| 2 || '''Knowledge Base''' (Context) || Structured Markdown documentation of Frappe's architecture, specific module logic, and Comfac's historical implementation data. This is the "brain" fed to the AI.
|-
| 3 || '''System Prompt''' (SP) || The exact instructions fed to the PAD agent detailing the Frappe-specific technical execution (e.g., "Using the attached Knowledge Base, create a custom app, add these fields via custom script, export fixtures").
|-
| 4 || '''Notes''' (Feedback & Challenges) || The iterative log of what the agent got wrong, Frappe CLI (bench) errors, and workflow refinements to improve the next System Prompt and update the Knowledge Base.
|}

== 4. Core Concept: "Ansible for Frappe" ==

Instead of humans clicking through the ERPNext UI to configure settings, create custom fields, or define workflows, the PAD toolset acts as an orchestration engine.

* '''Target State Definition:''' Using the PAD workflow to define a target state (e.g., "Company A needs Manufacturing and HR modules configured with X approval workflows").
* '''Agentic Execution:''' The PAD SSHs into the environment, interacts with the bench CLI, or uses the Frappe REST API to mutate the system to match the target state.
* '''Scalability:''' Existing successful PAD workflows become reusable modules, allowing the Comfac IT team to rapidly deploy pre-configured "industry templates" to new Frappe Cloud sites.

== 5. Critical Feedback & Predicted Problems ==

=== A. Frappe Architecture Challenges (File vs. Database State) ===

==== 1. The Metadata Trap ====
In Frappe, when you add a Custom Field or change a workflow via the UI, it saves to the database, not the codebase. If the PAD tries to act like Ansible and just writes Python/JSON files, the system will not recognize the changes.

'''Mitigation:''' The PAD must be instructed to use Custom Apps and Fixtures. The agent must make changes, run <code>bench export-fixtures</code>, and commit the resulting JSON files to Git.

==== 2. Idempotency Issues ====
Ansible's superpower is idempotency (running it 10 times results in the same state as running it once). Agents executing Python scripts or API calls often lack this. If a PAD agent runs a script to "create a Custom Field," running it twice might throw an <code>IntegrityError</code> (duplicate column).

'''Mitigation:''' The PAD must wrap all configuration code in "Check before Execute" logic (e.g., <code>if not frappe.db.exists('Custom Field', ...): create_field()</code>).

=== B. Frappe Cloud Specific Constraints ===

==== 1. Direct SSH Limitations ====
Frappe Cloud is a managed PaaS. Direct, persistent root/SSH access to live-edit files is heavily restricted to prevent drift between container orchestration and the site.

'''Mitigation:''' Do not have the PAD "live-edit" production via SSH. Instead, have the PAD clone the custom app repository locally, write the code/fixtures, commit to GitHub/GitLab, and trigger a webhook to Frappe Cloud to rebuild and deploy the image.

==== 2. bench migrate Downtime ====
Every time the PAD pushes a configuration change that alters the database schema, Frappe Cloud will run <code>bench migrate</code>. If the PAD pushes micro-changes continuously, the site will experience frequent micro-downtimes.

'''Mitigation:''' Batch PAD operations. The workflow should compile a complete "Configuration Release" before pushing to Frappe Cloud.

=== C. PAD (Agentic) Limitations ===

==== 1. Context Window Overwhelm ====
ERPNext is a massive monolith. If you tell an agent to "understand how customizing configuration impacts the system," it will drown in millions of lines of code.

'''Mitigation:''' Restrict the PAD's operational scope using the specific Knowledge Base files from the MediaWiki (e.g., only provide the documentation for the <code>erpnext/manufacturing</code> module).

==== 2. Hallucinating Frappe APIs ====
Frappe has very specific ORM methods (<code>frappe.get_doc</code>, <code>doc.insert()</code>, <code>frappe.db.get_value</code>). LLMs often hallucinate standard Django or SQLAlchemy syntax instead.

'''Mitigation:''' System Prompts must explicitly reference the MediaWiki "Frappe Cheat Sheet," enforcing the correct ORM syntax and bench commands.

== 6. Strategic Roadmap for Implementation ==

=== Phase 0: Research and Context Mapping (The Foundation) ===
* '''Action:''' Clone the Frappe and ERPNext GitHub repositories locally.
* '''Mapping:''' Have an initial LLM parse and organize the repository logic (DocTypes, Controllers, Hooks) into AI- and human-readable Markdown files.
* '''Education (Local Llama):''' Load this mapped context into a local LLM (e.g., Llama 3). Use this instance to translate complex Frappe architecture into simple explanations for non-IT students and Comfac staff.
* '''MediaWiki Deployment:''' Upload all generated PRD templates, System Prompts, Notes, and Knowledge Base Markdown files to the Comfac IT team's MediaWiki as the central "source of truth" for all future PAD operations.

=== Phase 1: Frappe Cloud Experiments & Change Detection (The Sandbox) ===
* '''Action:''' Setup a sandbox/test instance on Frappe Cloud.
* '''Detection:''' Perform manual configurations via the UI. Use the PAD to detect the underlying database or JSON changes (diffing the system state).
* '''Instruction Validation:''' Test the reverse workflow. Write System Prompts giving the PAD instructions to replicate those detected changes programmatically. Update the Notes and Knowledge Base in MediaWiki based on success or failure.

=== Phase 2: The API Configurator (The "Ansible" MVP) ===
* Instead of SSH and CLI, use the Frappe REST API.
* Write PAD workflows that authenticate via API and send JSON payloads to configure basic things (e.g., System Settings, Company setup, Item Groups). The API naturally handles a lot of the database/state validation that SSH/CLI bypassing might miss.

=== Phase 3: The Custom App Generator ===
* Task the PAD with scaffolding actual Frappe Custom Apps based on MediaWiki PRDs.
* '''Workflow:''' PRD specifies a new feature → PAD reads Knowledge Base & SP → Generates the <code>doctype.json</code>, <code>doctype.py</code>, and <code>doctype.js</code> files → Commits to Git → Deploys to Frappe Cloud.

=== Phase 4: Full CI/CD Agentic Deployment ===
* Integrate test data. The PAD deploys a configuration, injects test data (e.g., creates 10 dummy Sales Invoices), and runs an automated script to verify the workflow behaves as expected. If it fails, the error goes back to the "Notes" section of the MediaWiki to trigger a self-correction loop.

== Related Pages ==

* [[Proceedural Agentic Development Methodology 260304]] — Broader PAD methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[Architecture and Structure Comfac ERPN Loc]] — Comfac ERPNext architecture and localization
* [[Frappe Links and References]] — Frappe/ERPNext reference documentation
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — IT automation responsibilities aligned with this strategy
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment used in PAD workflows