How ahmedemamhatem/invoicing works
Project type and purpose
• This is a Frappe/ERPNext “app” (plugin) named “invoicing” that extends the core framework with custom doctypes, reports, workspace pages and fixtures for an invoicing module.
• Its purpose is to add invoicing features—clients, suppliers, invoice settings—and a profit-and-loss report to a Frappe site.
File structure
• Top-level:
• pyproject.toml, license.txt, .gitignore
• invoicing/ — root of the app
• invoicing/ contains:
• config/ — app configuration (hooks, permissions)
• fixtures/ — JSON fixtures for custom fields, translations, property setters
• hooks.py, install.py — entry points into Frappe’s installation lifecycle
• invoicing/ — actual module packages
– report/profit_and_loss/ (Python logic, JSON report definition, JS client)
– workspace/ (JSON definitions for module workspaces, named in Arabic)
• modules.txt, patches.txt — module registration and migration scripts
• templates/ — Jinja templates for custom pages
• public/ — static assets (empty placeholder)
README
• Very brief; confirms the project is named “Invoicing” and is MIT-licensed.
Main components
a. Frappe Framework Server
b. Invoicing App
• Hooks & Configuration
• Fixtures Loader
• Custom Doctypes & Property Setters
• Reports subsystem (Python + JSON + JS)
• Workspace definitions (custom pages)
• Templates and static assets
c. Database (MariaDB/MySQL)
d. Web Client (Browser, running Frappe Desk UI + custom JS)
e. Bench/Scheduler Worker (for patch runs, scheduled report generation)
Relationships and interactions
• Browser ↔ HTTP ↔ Frappe Server
• User clicks “Profit & Loss” → JS widget fetches JSON definition → invokes Python report script → SQL queries → JSON response → rendered in UI
• User navigates to workspace pages → Frappe serves Jinja templates and JSON definitions
• Frappe Server ↔ Database
• Fixtures loaded at install time write to tabCustom Field, tabProperty Setter, tabTranslation
• Modules.txt tells Frappe which module to register
• Patches.txt runs migrations on bench migrate
• Bench Scheduler ↔ Frappe Server
• install.py hook executes on app install
• patches.txt entries applied by patch runner
Architectural patterns and design principles
• Modular layering—app conforms to Frappe’s plugin architecture
• Separation of concerns:
• hooks.py handles lifecycle events
• fixtures store declarative customizations
• report folder encapsulates server logic, metadata, client code
• Convention over configuration—modules.txt auto-registers module
Details to capture
• Report flow: “profit_and_loss.json defines report → profit_and_loss.py executes → JS renders”
• Workspace JSON definitions mapped to UI menus