ERPNext Beginner to Intermediate: The Architecture Guide

🎯 Who This Is For & the Learning Journey

This guide is written for anyone who needs to go from zero knowledge of ERPNext to being productive with it professionally: ERPNext beginners, Python/Django and full-stack developers, system administrators, database developers, ERP implementers, business analysts, technical support engineers, and anyone building a custom ERPNext module.

Every diagram in this guide labels the same underlying chain: User → Frontend → Backend → DocType → Database → Integration. That chain is the single idea the whole course is built around — once it clicks, every ERPNext screen, table, and API call reads as an instance of it.

⚠️ Version & Accuracy Note

🧭 What Is ERPNext? Frappe vs ERPNext

ERP (Enterprise Resource Planning) software exists to solve one recurring business problem: sales, purchasing, inventory, accounting, and HR are all run as separate spreadsheets or disconnected tools, so nobody can see one true, current picture of the business. An ERP unifies them into one database with one shared set of master data (customers, items, accounts) so every transaction updates the same source of truth.

ERPNext is an open-source ERP application. It is not a standalone codebase — it is built on top of Frappe Framework, a full-stack, metadata-driven web application framework (Python backend, JavaScript frontend, MariaDB database) that ERPNext uses for everything: authentication, permissions, forms, reports, workflows, and the REST API. This is the single most important distinction for a developer to internalize before touching ERPNext code.

🏗️ Frappe/ERPNext Architecture

Behind that request/response path, a full ERPNext deployment runs several supporting processes together:

⚙️ Installation & Dependencies

ERPNext can be installed for local development (bench on bare metal or WSL), via Docker, or directly on a production VPS. All paths converge on the same tool: Frappe Bench, the CLI that manages sites, apps, and processes.

The core bench workflow, in order:

# install bench itself (via pip/pipx), then:
bench init frappe-bench                 # scaffold a new bench (downloads the Frappe app)
cd frappe-bench
bench new-site site1.local              # create a site: its own database + config
bench get-app erpnext                   # fetch the ERPNext app source
bench --site site1.local install-app erpnext   # install ERPNext into that site
bench start                             # run web server + workers + scheduler for development

Each command has a distinct job: bench init sets up the shared bench (apps + environment); bench new-site creates one isolated tenant (its own MariaDB database, own config, own set of installed apps); get-app vs install-app is the same split as downloading a package vs actually enabling it for a specific site — one bench can host many sites, each with a different combination of installed apps.

🚀 Production Deployment Architecture

In production, Supervisor keeps Gunicorn, the background workers, and the scheduler running (and restarts them on crash or reboot), while Nginx handles TLS (typically via Let's Encrypt / Certbot for free auto-renewing HTTPS certificates), serves static assets directly, and proxies dynamic requests to Gunicorn. A production checklist also includes a configured firewall (only 80/443/22 open), a scheduled backup job, and a DNS record pointed at the server before requesting a certificate.

🔑 First Login & Initial Setup

The first login into a freshly installed site runs the Setup Wizard, which walks through the minimum master data ERPNext needs before any transaction can be created:

🖥️ ERPNext UI Concepts

Almost the entire application is one interface, called the Desk, built from a small set of reusable view types:

👥 Users, Roles & Permission Flow

ERPNext ships a set of standard roles that map to job functions, all ultimately subordinate to the System Manager role, which has unrestricted administrative access:

Access is resolved through a layered chain, not a single flag — this is the same "many small typed layers, not one field" principle that shows up in ERP accounting status modeling:

A Role Profile bundles a set of roles for fast assignment to new users; Document Share grants ad-hoc access to one specific document outside the normal role rules; and workflow-state permissions (see Workflow Engine) can further restrict who may transition a document, independent of its base role permissions.

🧩 Core Modules at a Glance

ERPNext ships as a set of business modules sharing one database and one permission system. Every module follows the same internal shape — Purpose → Master Data → Transactions → Child Tables → Workflow → Database → Accounting/Stock Impact → Other-Module Connections → Reports → API — so once you understand one module deeply, reading a new one is mostly about learning its specific documents, not a new mental model.

🔗 Flagship Document Flows

Selling: Lead to Cash

Child tables carry the line items at every stage: Quotation Item, Sales Order Item, Delivery Note Item, Sales Invoice Item — each new document typically pulls its rows from the previous one so item, price, and quantity stay traceable end to end.

Buying: Procure to Pay

Manufacturing: BOM to Finished Goods

A BOM (Bill of Materials) can itself reference another Item that has its own BOM — a multi-level BOM — so manufacturing a finished item can cascade into manufacturing its sub-assemblies first.

HR & Payroll: Employee to Accounting

Assets: Purchase to Disposal

🕸️ Module Interconnection Master Diagram

Notice the pattern: almost every module is a source that eventually drains into Stock and/or Accounting. Those two are the shared "settlement layer" every other module's transactions converge on — the ERPNext equivalent of the subledger/GL relationship described in the accounting curriculum's ERP Architecture level.

🗄️ Database Architecture: DocType → Table

This is a verified, stable Frappe convention: every non-child, non-virtual DocType gets a MariaDB table named tab + the DocType name, spaces included — e.g. tabCustomer, tabSupplier, tabItem, tabSales Order, tabSales Invoice. Changing a DocType's fields in the UI ("Customize Form" or the DocType editor) triggers a schema migration that adds/alters the corresponding column — this is why DocTypes are described as "metadata-driven": the schema is a byproduct of the metadata, not hand-written SQL.

📚 Master Tables vs Transaction Tables

Master data exists so transactions don't repeat information — a Sales Order doesn't store a customer's address text, it stores a Link to the Customer, and the Customer record is the single place that address gets corrected. This is the same "don't duplicate the fact, reference it" principle behind normalized database design generally.

Child Tables Explained

A child table row always carries four framework-managed fields that tie it back to its parent, in addition to whatever fields the child DocType itself defines:

tabSales Order
       │
       │ parent (1) ──── (N) rows
       ▼
tabSales Order Item
  parent      = "SAL-ORD-2026-00042"
  parenttype  = "Sales Order"
  parentfield = "items"
  idx         = 1
  item_code   = "WIDGET-001"
  qty         = 10

Illustrative Table Map (Verify Per Version)

The following are well-known, long-stable core DocTypes grouped by module, to illustrate the naming convention — not an exhaustive schema dump. Confirm exact names and any version differences against your installed site (e.g. via bench --site SITE console or the DocType list in Developer Mode) before relying on them in code.

🔀 ER Diagrams: Customer, Item, Accounting

Customer Relationships

Item Relationships

Accounting Relationships

🔌 Internal vs External Connections

Internal (module ↔ module, inside one database)

External (ERPNext ↔ the outside world)

🌐 REST API Basics

Frappe auto-generates a REST-style endpoint for every DocType at /api/resource/<DocType>, supporting the standard HTTP verbs, authenticated with an API key/secret pair generated per user:

# list/read
GET /api/resource/Customer
GET /api/resource/Customer/CUST-00001

# create
POST /api/resource/Customer

# update
PUT /api/resource/Customer/CUST-00001

# delete
DELETE /api/resource/Customer/CUST-00001

# Python (requests)
import requests
headers = {"Authorization": "token API_KEY:API_SECRET"}
r = requests.get("https://site.example.com/api/resource/Customer", headers=headers)

// JavaScript (fetch)
fetch("https://site.example.com/api/resource/Customer", {
  headers: { "Authorization": "token API_KEY:API_SECRET" }
}).then(r => r.json());

🛠️ Customization Decision Tree

ERPNext offers a deliberate ladder of customization tools, from no-code to full custom application — always reach for the lowest rung that solves the problem:

📦 Building a Custom Frappe App

bench new-app my_custom_app
bench --site site1.local install-app my_custom_app

my_custom_app/
├── hooks.py            # app config: doc_events, scheduler_events, includes, fixtures
├── modules.txt         # modules this app defines
├── patches.txt         # data migration scripts run on update
├── public/             # JS/CSS/images served to the browser
├── templates/           # Jinja templates for web pages/emails
└── my_custom_app/
    └── my_module/
        ├── doctype/     # one folder per custom DocType (json + python + js)
        ├── report/      # custom reports
        └── page/        # custom Desk pages

Doc-event hooks are how a custom app plugs into the lifecycle of any document — including ERPNext's own — without editing ERPNext source:

Other key hook categories: scheduler_events (cron-style background jobs), app_include_js/app_include_css (global frontend assets), fixtures (data — like custom fields or roles — exported and reapplied on install), permission_query_conditions and has_permission (row-level access rules beyond the standard permission engine), and override_doctype_class (replacing a standard DocType's controller logic without editing its file).

🧪 Custom Module Case Study: Laboratory Management

A realistic custom app example — extending ERPNext for a diagnostic lab — illustrates how a domain-specific module plugs into ERPNext's core rather than replacing it:

New DocTypes (Patient, Sample, Test Request, etc.) link back into ERPNext core via ordinary Link fields — Sample.customer → Customer, Sample.company → Company, Test.item → Item, Test Request.employee → Employee — so a lab report can bill through the standard Sales Invoice flow instead of the custom app reinventing billing.

Integration happens on three levels, and a well-designed custom app touches all three deliberately rather than only the first:

🔄 Workflow Engine

A Frappe Workflow defines a set of Workflow States, the Actions/Transitions allowed between them, and which Role may perform each transition — letting a document (any DocType, standard or custom) require a multi-step approval chain without writing code:

🛡️ Security, Backup & Troubleshooting

Layer that with HTTPS everywhere, a real password policy, server-side validation (never trust client scripts alone), and the audit trail every document already carries (owner, modified_by, version history) — plus scheduled, tested backups:

💻 Developer Command Cheat Sheet

bench start                          # run dev processes (web, workers, scheduler)
bench restart                        # restart supervisor-managed processes (production)
bench update                         # pull latest app code + run migrations
bench migrate                        # apply pending schema/data migrations
bench build                          # rebuild frontend JS/CSS assets
bench clear-cache                    # clear Frappe's Redis cache
bench clear-website-cache            # clear rendered website page cache
bench console                        # interactive Python shell with the site bootstrapped
bench mariadb                        # open a MariaDB shell for the current site
bench doctor                         # diagnose common environment problems
bench --site SITE list-apps          # list apps installed on a site
bench --site SITE install-app APP    # install an app into a site
bench --site SITE uninstall-app APP  # remove an app from a site
bench --site SITE backup             # take a database (+ optional files) backup

✅ Best Practices

🏢 Real-World Scenarios

Retail: ABC Electronics Ltd.

Running in parallel on the purchasing side — Supplier → Purchase Order → Purchase Receipt → Purchase Invoice → Payment — with Stock and Accounting updating automatically from both sides without either team touching the other's documents directly.

Manufacturing Company

Custom Module: Laboratory Extension

The same Lab Management case study above, closing with billing: once a Lab Report is approved, the custom app's business-logic hook creates a Sales Invoice against the linked Customer, feeding straight back into the Accounting module covered earlier.

🗺️ Learning Roadmap & What's Next

This article is Part 1 of a 9-part series, covering the foundations (architecture, installation, modules, and database design) in enough depth to navigate the rest of ERPNext confidently. The planned follow-ups go deeper on each area:

If your interest in ERPNext is specifically the accounting side — how GL Entry, Payment Entry, and invoice settlement actually work under the hood — that ground is covered in full depth, framework-agnostically, in Invoice vs Payment: The Complete ERP Accounting Architecture and the Accounting to ERP curriculum.