bench get-app https://github.com/sapphirefountains/erpnext_enhancements

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=sapphirefountains%2Ferpnext_enhancements)](https://frappegems.com/gems/apps/sapphirefountains/erpnext_enhancements)

ERPNext Enhancements

A single Frappe v16 app that bundles Sapphire Fountains' customizations and enhancements to ERPNext. It consolidates what used to be several separate apps (CRM, Global, Project, Task, and QuickBooks Time enhancements) into one installable app made up of eight Frappe modules, plus a standalone Time Kiosk Progressive Web App and a large library of desk (browser) customizations.

• App name: erpnext_enhancements
• Publisher: Sapphire Fountains · info@sapphirefountains.com
• License: MIT
• Requires: Frappe >=16.0.0,<17.0.0, Python >=3.10
• Current version: see erpnext_enhancements/__init__.py and CHANGELOG.md

> New to this codebase? Read this file top-to-bottom, then jump to the per-module documentation index. Every source file in the app also carries inline docstrings/comments describing what it does and how it is wired.

---

Table of contents

1. What this app does
2. Architecture at a glance
3. Module map
4. How customizations are wired (hooks.py)
5. External integrations
6. Key subsystems
7. Installation
8. Development workflow
9. Conventions
10. Documentation index

---

What this app does

ERPNext Enhancements layers Sapphire Fountains' business processes onto a stock ERPNext install without forking ERPNext itself. Broadly, it provides:

• Project management upgrades — a custom Project Dashboard desk page (tabbed, realtime, portfolio Gantt + resource heatmap), a Master Project doctype that groups projects into programs, procurement-status rollups, project merging, and Opportunity→Project conversion with attachment carry-over.
• Field-service maintenance (Sapphire Maintenance) — template-driven maintenance records that, on submit, create Stock Entries, Timesheets, warranty RMAs, and draft Sales Invoices, plus a customer portal and predictive scheduling.
• Time tracking — a standalone, installable Time Kiosk PWA with battery-aware GPS tracking, offline queueing, and automatic consolidation into ERPNext Timesheets.
• CRM enhancements — Opportunity customizations and automatic Google Drive project-folder provisioning.
• Integrations — QuickBooks Online (accounting sync), Twilio/Triton telephony (click-to-call + SMS), Google Analytics 4 / Search Console dashboard, and the "Triton" in-app AI assistant.
• Live collaborative editing — Google-Docs-style multi-user editing on the ten most-used doctypes: field changes stream in real time to everyone viewing the same document, saves apply silently on collaborators' screens (no more "Document has been modified" conflicts between collaborators), and per-field highlights show who is editing what.
• Desk usability fixes — Kanban drag/scroll/leak fixes, a custom Vue comments app, safe form drafts, an aggregated contacts/addresses directory, sidebar tweaks, and a pile of performance hotfixes for upstream Frappe bugs.

Architecture at a glance

This is a conventional Frappe app. If you know Frappe, the layout will be familiar; if not, here is the mental model:

erpnext_enhancements/                 ← the Python package (one folder per Frappe module + shared code)
├── hooks.py                          ← THE control center: every customization registers here
├── modules.txt                       ← the 8 Frappe modules this app ships
├── patches.txt                       ← ordered list of one-time migration patches
├── /                         ← one folder per module (see "Module map")
│   ├── doctype//            ← DocType: .json (schema) + .py (controller) + .js (form script)
│   ├── page//                  ← desk Page: .json + .py (backend) + .js (frontend)
│   └── ...
├── api/                              ← @frappe.whitelist() HTTP endpoints (called by JS / external clients)
├── script_migrations/               ← Python ports of legacy DB-stored Client/Server Scripts
├── patches/                          ← one-time migration scripts (run by `bench migrate`)
├── setup/                            ← idempotent setup run after every migrate (custom fields, etc.)
├── utils/                            ← shared helpers (global Triton sync, delete patching)
├── fixtures/                         ← exported records installed on migrate (custom fields, workflows…)
├── public/                           ← browser assets (JS form scripts, CSS, kiosk front-end)
├── www/                              ← the standalone Time Kiosk PWA (`/kiosk`)
├── templates/                        ← Jinja web templates
└── tests/                            ← test suite

Custom HTML Block/                    ← exported source of a Frappe "Custom HTML Block" dashboard widget
sync_time_kiosk.py                    ← standalone REST tool: Job Intervals → Timesheets

Three layers carry most of the behavior:

1. Server (Python). DocType controllers (*.py next to *.json), whitelisted endpoints in api/, document-event handlers, scheduler jobs, and script_migrations/. Everything server-side that hooks into ERPNext is registered in hooks.py.
2. Client (JavaScript). Form scripts, list-view scripts, desk-wide patches, the Vue comments app, and the kiosk front-end — all under public/. Loaded via hooks.py (app_include_js, doctype_js, …) except the kiosk PWA, which is loaded by www/kiosk.html.
3. Data model. DocTypes (*.json) plus Custom Fields, Property Setters, Workflows, and Notifications shipped as fixtures/ and created by setup/ / patches/.

Module map

The app ships eight Frappe modules (see modules.txt). Each has its own README:

Module (folder)	What it covers	README
Enhancements Core (enhancements_core/)	Catch-all: app Single settings, Time Kiosk data doctypes (Job Interval, Time Kiosk Log), Asset Booking, GA4 dashboard page, Location Timeline map page	README
Project Enhancements (project_enhancements/)	Project Dashboard page, Master Project, procurement status, project merge, dashboard overrides	README
Sapphire Maintenance (sapphire_maintenance/)	Template→Record→Result maintenance subsystem, portal, print format, on-submit automation	README
CRM Enhancements (crm_enhancements/)	Opportunity customizations + Google Drive project-folder provisioning	README
Global Enhancements (global_enhancements/)	Triton AI assistant settings + Directory Link Exclusion doctype	README
Task Enhancements (task_enhancements/)	Overrides the core Task class; Hierarchical Task View page	README
Travel Management (travel_management/)	Travel Trip workflow + child tables → draft Expense Claim	README
QuickBooks Time Integration (quickbooks_time_integration/)	QuickBooks Online accounting sync (OAuth2, CDC, webhooks) + QB Time webhook	README

Shared / cross-cutting code (not a Frappe module):

Folder	What it covers	README
api/	Whitelisted HTTP endpoints	README
script_migrations/	Ported Client/Server Scripts (wired via doc_events)	README
patches/	One-time migration scripts	README
public/	Browser assets (JS/CSS)	README
www/	Time Kiosk PWA shell	README
tests/	Test suite	README
Custom HTML Block/	Exported dashboard-widget source	README

> History: v0.2.0 merged the previously separate crm_enhancements, global_enhancements, project_enhancements, task_enhancements, and qb_time_integration apps into this one app. Their public assets are namespaced under public/{js,css}// to avoid collisions. Uninstall the old standalone apps from existing benches after deploying.

How customizations are wired (hooks.py)

hooks.py is the single source of truth for how this app attaches to ERPNext. The major registrations:

Hook	Purpose	Notable entries
app_include_js / app_include_css	Desk-wide assets loaded on every page	Kanban patches, the Vue comments app (vue.global.js + comments.js + comments_auto.js), Triton widget, telephony client, perf fixes
doctype_js / doctype_list_js / doctype_css / doctype_calendar_js	Per-doctype form/list/calendar scripts	Project, Opportunity, Task, Customer, Supplier, Contact, etc.
doc_events	Document lifecycle handlers	Contact-sync on most party doctypes, script_migrations.* ports, dashboard realtime updates, maintenance scheduling, "*": {after_save: global_triton_sync} (fires on every save site-wide)
scheduler_events	Background jobs	daily: project reminders, predictive maintenance, customer inactivity, elapsed-time refresh, draft cleanup, location-log purge · hourly: QuickBooks token refresh, CDC poll, retry failed syncs
override_doctype_class	Replace a core controller	Task → task_enhancements.doctype.task.task.Task
override_whitelisted_methods	Replace a core endpoint	opportunity.make_project → opportunity_enhancements.make_project
override_doctype_dashboards	Customize the "connections" dashboard	Project, Employee
extend_bootinfo	Per-session data shipped to the desk client	boot.boot_session — the live-collab doctype allowlist (frappe.boot.collab_doctypes) from ERPNext Enhancements Settings
after_migrate	Idempotent setup after each migrate	setup.custom_fields, setup.supplier_groups, setup.process_documents (seeds/updates the Mermaid.js Process Document charts — repo is the source of truth)
fixtures	Records installed on migrate	All manual customizations — every manually created Custom Field (425) and Property Setter (349); see fixtures/README.md — plus Travel Trip Workflow + states/actions, maintenance Notifications + Print Format
portal_menu_items	Customer portal links	/maintenance-records

When you add a feature, you almost always register it here. When you are tracing "what runs when X is saved", start here.

External integrations

This app talks to several third-party services. Credentials live in dedicated Single settings doctypes (encrypted Password fields where secret):

Service	Used for	Configured in
Google Drive	Auto-create per-project folder trees on Opportunity→Project	Project Folder Google Drive Settings (service-account JSON)
Google Analytics 4 + Search Console	Marketing dashboard	GA4 Settings (service-account JSON; see Enhancements Core README)
Vertex AI (Gemini)