How sapphirefountains/global_enhancements works
This repository is a Frappe app named global_enhancements. Its architecture is centered on extending Frappe behavior through hooks, setup-time metadata changes, patch scripts, and client-side assets rather than through a standalone service or monolith application.
1. Core boundary: a Frappe app
The global_enhancements/ package is the installable app that Frappe loads into a bench. The repo is not a generic Python library; it is structured around Frappe conventions such as hooks.py, setup/, patches/, public/, and templates/.
2. Runtime extension points
global_enhancements/hooks.py is the main integration point with the Frappe framework. This is where the app likely registers doctypes, fixtures, client/server hooks, scheduled jobs, or asset includes. Architecturally, this is the entry boundary where the app influences the host Frappe instance.
3. Schema and metadata setup
The global_enhancements/setup/ package contains installation or bootstrap logic:
- custom_fields.py suggests creation/update of custom fields.
- supplier_groups.py suggests seed data or master-data setup for supplier grouping.
This layer is the “provisioning” boundary: it changes Frappe metadata and configured business entities rather than handling runtime requests.
4. Patch and migration layer
The global_enhancements/patches/ directory contains patch modules such as migrate_contact_data.py. This is the upgrade path for evolving data and schema between app versions. In Frappe terms, these patches are the controlled migration mechanism applied during bench migrate / app upgrade.
5. Business logic helpers
global_enhancements/utils/ contains reusable internal logic:
- triton_sync.py indicates an integration/synchronization helper for an external Triton system or service.
- patch_delete.py and delete_utils.py suggest safe deletion or unlinking workflows.
These utilities act as the server-side service layer used by patches, hooks, or custom scripts.
6. Domain-specific server modules
Top-level modules like sync_contact.py, supplier_query.py, and commit_custom_fields.py indicate task-oriented routines for querying, syncing, or updating business data. They look like operational scripts or callable jobs rather than persistent application services.
7. Frontend customization assets
global_enhancements/public/ holds browser-side enhancements:
- js/global_sidebar.js
- js/unified_tab_controller.js
- js/disable_kanban_drag.js
- js/primary_contact.js
- js/quill_mentions.js
- js/supplier_list.js
- js/unlink_and_delete.js
- css/horizontal_scroll.css
These are likely injected into Frappe forms, lists, or desk pages to alter user interactions and UI behavior. This is the client-side boundary of the app.
8. Template and page structure
global_enhancements/templates/pages/ suggests custom Frappe desk/web pages or page fragments. The templates layer is separate from the public assets and likely provides server-rendered page entry points or page definitions.
9. Packaging and module layout
The nested global_enhancements/global_enhancements/ directory shows the standard Python package structure used by Frappe apps. The presence of modules.txt and patches.txt further indicates Frappe’s app metadata and migration registration model.
10. Ad hoc repository scripts
The many root-level scripts like fix_tabs*.py, update_tabs.py, print_mp.py, test_*, and runner.py appear to be maintenance or one-off operational tools. They are not the main app architecture, but they do show that the repo includes repeatable admin utilities for field/tab manipulation and validation around a “master project” object (master_project_meta.*, master_project_doctype.json).
11. Data flow pattern
The main data flow appears to be:
Frappe installation/migration → setup code creates custom fields and reference data → patches migrate existing records → hooks and utilities perform ongoing sync/delete/query logic → public JS/CSS adjusts user interactions in the desk UI. This is a metadata-heavy customization app with some integration logic, not a request-driven backend service.
12. Tooling and repo hygiene
pyproject.toml, .pre-commit-config.yaml, .eslintrc, and .editorconfig indicate a mixed Python/JavaScript codebase with formatting and linting enforced through pre-commit. The README explicitly names ruff, eslint, prettier, and pyupgrade, which matches the server/client split in the repository.
13. External dependency context
The only clearly implied external platform is Frappe/Bench, which is the runtime and deployment host. Any Triton integration appears to be an application-specific external dependency, but the repository itself mainly acts as a customization layer inside Frappe.
14. Overall architecture summary
Think of this repo as a Frappe customization package with four major surfaces: installation/setup, migration patches, reusable server utilities/integrations, and client-side UI enhancements. The root scripts are supporting maintenance tools around those core surfaces.
Main entry points: hooks.py Hooks · migrate_contact_data.py Contact patch · sync_contact.py Sync contact · delete_utils.py Delete utils
Components 22
Frappe app
Installable app boundary and framework integration points.
- App package · Installable Python package loaded by Frappe/Bench.
global_enhancements/global_enhancements/__init__.py - Hooks · Main Frappe integration surface for registrations and asset wiring.
global_enhancements/hooks.py
Setup & migration
Install-time metadata changes and upgrade patches.
- Custom fields · Creates and updates Frappe custom field metadata.
global_enhancements/setup/custom_fields.py - Supplier groups · Bootstraps supplier-group reference data.
global_enhancements/setup/supplier_groups.py - Contact patch · Migrates existing contact data during app upgrades.
global_enhancements/patches/migrate_contact_data.py
Server logic
Reusable backend helpers and task-oriented modules.
- Triton sync · Sync helper for an external Triton system or service.
global_enhancements/utils/triton_sync.py - Delete flow · Safe unlink/delete workflow used by scripts and UI actions.
global_enhancements/utils/patch_delete.py - Delete utils · Shared deletion and cleanup helpers.
global_enhancements/delete_utils.py - Sync contact · Task-oriented routine for contact synchronization.
global_enhancements/sync_contact.py - Supplier query · Task-oriented routine for supplier lookup or extraction.
global_enhancements/supplier_query.py
Client UI
Browser-side assets and templates that customize the desk.
- Sidebar UI · Desk sidebar customization script.
global_enhancements/public/js/global_sidebar.js - Tab controller · Coordinates or normalizes tab behavior across forms.
global_enhancements/public/js/unified_tab_controller.js - Kanban lock · Disables kanban drag interactions.
global_enhancements/public/js/disable_kanban_drag.js - Primary contact · Enhances contact-related form behavior.
global_enhancements/public/js/primary_contact.js - Mentions · Quill editor mention behavior for rich text input.
global_enhancements/public/js/quill_mentions.js - Supplier list · List-view customization for supplier workflows.
global_enhancements/public/js/supplier_list.js - Unlink delete · Browser-side action for unlinking and deleting records.
global_enhancements/public/js/unlink_and_delete.js - Scroll CSS · Horizontal scrolling styles for desk or form layouts.
global_enhancements/public/css/horizontal_scroll.css - Pages · Server-rendered page entry points and page fragments.
global_enhancements/templates/pages/__init__.py
Repo tools
Maintenance scripts and one-off admin utilities.
- Master project · Reference metadata for the master project model used by maintenance scripts.
master_project_doctype.json - Runner · General-purpose script runner and maintenance entry point.
runner.py - Tab tools · One-off scripts for updating or fixing tab metadata.
update_tabs.py
Connections 21
- App package → Hooks: loads · The app package exposes the Frappe hook entry point.
- Hooks → Custom fields: bootstraps · Hooks likely wire install/setup behavior for metadata changes.
- Hooks → Supplier groups: bootstraps · Hooks may register seed-data setup on install.
- Hooks → Contact patch: registers · Hooks and patch metadata drive upgrade execution.
- Contact patch → Triton sync: uses · Migration work can reuse sync helpers for external data.
- Sync contact → Triton sync: uses · Contact sync task likely delegates to Triton integration logic.
- Sync contact → Delete utils: uses · Sync routines may clean up or reconcile related records.
- Supplier query → Delete utils: uses · Query/maintenance routines share common cleanup helpers.
- Delete flow → Delete utils: wraps · Deletion flow composes reusable deletion utilities.
- Hooks → Sidebar UI: includes · Client assets are typically injected through app hooks.
- Hooks → Tab controller: includes · Client assets are typically injected through app hooks.
- Hooks → Kanban lock: includes · Client assets are typically injected through app hooks.
- Hooks → Primary contact: includes · Client assets are typically injected through app hooks.
- Hooks → Mentions: includes · Client assets are typically injected through app hooks.
- Hooks → Supplier list: includes · Client assets are typically injected through app hooks.
- Hooks → Unlink delete: includes · Client assets are typically injected through app hooks.
- Hooks → Scroll CSS: includes · Style assets are likely added via framework hooks.
- Hooks → Pages: exposes · Page templates provide server-rendered UI entry points.
- Runner → Master project: operates on · Maintenance scripts appear centered on master project metadata.
- Tab tools → Master project: operates on · Tab-fixing utilities manipulate the master project fixture.
- Contact patch → Sync contact: aligns with · Migration logic and operational sync code work on the same domain data.