# sapphirefountains/global_enhancements architecture

> Architecture diagram of the GitHub repository sapphirefountains/global_enhancements, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sapphirefountains/global_enhancements
- Repository: https://github.com/sapphirefountains/global_enhancements

## Overview

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: [`global_enhancements/hooks.py`](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/hooks.py) (Hooks), [`global_enhancements/patches/migrate_contact_data.py`](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/patches/migrate_contact_data.py) (Contact patch), [`global_enhancements/sync_contact.py`](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/sync_contact.py) (Sync contact), [`global_enhancements/delete_utils.py`](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/delete_utils.py) (Delete utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Frappe app"]
  node_app_pkg["App package<br/>frappe app<br/>[__init__.py]"]
  node_hooks["Hooks<br/>framework entry<br/>[hooks.py]"]
end

subgraph group_provisioning["Setup & migration"]
  node_setup_custom_fields["Custom fields<br/>setup script<br/>[custom_fields.py]"]
  node_setup_supplier_groups["Supplier groups<br/>seed setup<br/>[supplier_groups.py]"]
  node_patch_migrate_contact["Contact patch<br/>migration patch"]
end

subgraph group_runtime["Server logic"]
  node_triton_sync["Triton sync<br/>integration helper<br/>[triton_sync.py]"]
  node_patch_delete_utils["Delete flow<br/>deletion helper<br/>[patch_delete.py]"]
  node_delete_utils["Delete utils<br/>utility module<br/>[delete_utils.py]"]
  node_sync_contact["Sync contact<br/>server task<br/>[sync_contact.py]"]
  node_supplier_query["Supplier query<br/>server task<br/>[supplier_query.py]"]
end

subgraph group_client["Client UI"]
  node_global_sidebar_js["Sidebar UI<br/>client script<br/>[global_sidebar.js]"]
  node_unified_tab_js["Tab controller<br/>client script"]
  node_kanban_js["Kanban lock<br/>client script"]
  node_primary_contact_js["Primary contact<br/>client script<br/>[primary_contact.js]"]
  node_quill_mentions_js["Mentions<br/>client script<br/>[quill_mentions.js]"]
  node_supplier_list_js["Supplier list<br/>client script<br/>[supplier_list.js]"]
  node_unlink_delete_js["Unlink delete<br/>client script"]
  node_horizontal_scroll_css["Scroll CSS<br/>style asset"]
  node_pages["Pages<br/>[__init__.py]"]
end

subgraph group_ops["Repo tools"]
  node_master_project_doctype[("Master project<br/>doctype fixture")]
  node_runner["Runner<br/>admin script<br/>[runner.py]"]
  node_update_tabs["Tab tools<br/>maintenance script<br/>[update_tabs.py]"]
end

node_app_pkg -->|"loads"| node_hooks
node_hooks -->|"bootstraps"| node_setup_custom_fields
node_hooks -->|"bootstraps"| node_setup_supplier_groups
node_hooks -->|"registers"| node_patch_migrate_contact
node_patch_migrate_contact -.->|"uses"| node_triton_sync
node_sync_contact -->|"uses"| node_triton_sync
node_sync_contact -.->|"uses"| node_delete_utils
node_supplier_query -.->|"uses"| node_delete_utils
node_patch_delete_utils -->|"wraps"| node_delete_utils
node_hooks -->|"includes"| node_global_sidebar_js
node_hooks -->|"includes"| node_unified_tab_js
node_hooks -->|"includes"| node_kanban_js
node_hooks -->|"includes"| node_primary_contact_js
node_hooks -->|"includes"| node_quill_mentions_js
node_hooks -->|"includes"| node_supplier_list_js
node_hooks -->|"includes"| node_unlink_delete_js
node_hooks -->|"includes"| node_horizontal_scroll_css
node_hooks -->|"exposes"| node_pages
node_runner -->|"operates on"| node_master_project_doctype
node_update_tabs -->|"operates on"| node_master_project_doctype
node_patch_migrate_contact -.->|"aligns with"| node_sync_contact

click node_app_pkg "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/global_enhancements/__init__.py"
click node_hooks "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/hooks.py"
click node_setup_custom_fields "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/setup/custom_fields.py"
click node_setup_supplier_groups "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/setup/supplier_groups.py"
click node_patch_migrate_contact "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/patches/migrate_contact_data.py"
click node_triton_sync "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/utils/triton_sync.py"
click node_patch_delete_utils "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/utils/patch_delete.py"
click node_delete_utils "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/delete_utils.py"
click node_sync_contact "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/sync_contact.py"
click node_supplier_query "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/supplier_query.py"
click node_global_sidebar_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/global_sidebar.js"
click node_unified_tab_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/unified_tab_controller.js"
click node_kanban_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/disable_kanban_drag.js"
click node_primary_contact_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/primary_contact.js"
click node_quill_mentions_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/quill_mentions.js"
click node_supplier_list_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/supplier_list.js"
click node_unlink_delete_js "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/unlink_and_delete.js"
click node_horizontal_scroll_css "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/css/horizontal_scroll.css"
click node_pages "https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/templates/pages/__init__.py"
click node_master_project_doctype "https://github.com/sapphirefountains/global_enhancements/blob/main/master_project_doctype.json"
click node_runner "https://github.com/sapphirefountains/global_enhancements/blob/main/runner.py"
click node_update_tabs "https://github.com/sapphirefountains/global_enhancements/blob/main/update_tabs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_pkg,node_hooks toneBlue
class node_setup_custom_fields,node_setup_supplier_groups,node_patch_migrate_contact toneAmber
class node_triton_sync,node_patch_delete_utils,node_delete_utils,node_sync_contact,node_supplier_query toneMint
class node_global_sidebar_js,node_unified_tab_js,node_kanban_js,node_primary_contact_js,node_quill_mentions_js,node_supplier_list_js,node_unlink_delete_js,node_horizontal_scroll_css,node_pages toneRose
class node_master_project_doctype,node_runner,node_update_tabs toneIndigo
```

## Components

### Frappe app

Installable app boundary and framework integration points.

- [App package](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/global_enhancements/__init__.py): frappe app · Installable Python package loaded by Frappe/Bench. · `global_enhancements/global_enhancements/__init__.py`
- [Hooks](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/hooks.py): framework entry · Main Frappe integration surface for registrations and asset wiring. · `global_enhancements/hooks.py`

### Setup & migration

Install-time metadata changes and upgrade patches.

- [Custom fields](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/setup/custom_fields.py): setup script · Creates and updates Frappe custom field metadata. · `global_enhancements/setup/custom_fields.py`
- [Supplier groups](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/setup/supplier_groups.py): seed setup · Bootstraps supplier-group reference data. · `global_enhancements/setup/supplier_groups.py`
- [Contact patch](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/patches/migrate_contact_data.py): migration 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](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/utils/triton_sync.py): integration helper · Sync helper for an external Triton system or service. · `global_enhancements/utils/triton_sync.py`
- [Delete flow](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/utils/patch_delete.py): deletion helper · Safe unlink/delete workflow used by scripts and UI actions. · `global_enhancements/utils/patch_delete.py`
- [Delete utils](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/delete_utils.py): utility module · Shared deletion and cleanup helpers. · `global_enhancements/delete_utils.py`
- [Sync contact](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/sync_contact.py): server task · Task-oriented routine for contact synchronization. · `global_enhancements/sync_contact.py`
- [Supplier query](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/supplier_query.py): server task · 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](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/global_sidebar.js): client script · Desk sidebar customization script. · `global_enhancements/public/js/global_sidebar.js`
- [Tab controller](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/unified_tab_controller.js): client script · Coordinates or normalizes tab behavior across forms. · `global_enhancements/public/js/unified_tab_controller.js`
- [Kanban lock](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/disable_kanban_drag.js): client script · Disables kanban drag interactions. · `global_enhancements/public/js/disable_kanban_drag.js`
- [Primary contact](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/primary_contact.js): client script · Enhances contact-related form behavior. · `global_enhancements/public/js/primary_contact.js`
- [Mentions](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/quill_mentions.js): client script · Quill editor mention behavior for rich text input. · `global_enhancements/public/js/quill_mentions.js`
- [Supplier list](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/supplier_list.js): client script · List-view customization for supplier workflows. · `global_enhancements/public/js/supplier_list.js`
- [Unlink delete](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/js/unlink_and_delete.js): client script · Browser-side action for unlinking and deleting records. · `global_enhancements/public/js/unlink_and_delete.js`
- [Scroll CSS](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/public/css/horizontal_scroll.css): style asset · Horizontal scrolling styles for desk or form layouts. · `global_enhancements/public/css/horizontal_scroll.css`
- [Pages](https://github.com/sapphirefountains/global_enhancements/blob/main/global_enhancements/templates/pages/__init__.py): template 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](https://github.com/sapphirefountains/global_enhancements/blob/main/master_project_doctype.json): doctype fixture · Reference metadata for the master project model used by maintenance scripts. · `master_project_doctype.json`
- [Runner](https://github.com/sapphirefountains/global_enhancements/blob/main/runner.py): admin script · General-purpose script runner and maintenance entry point. · `runner.py`
- [Tab tools](https://github.com/sapphirefountains/global_enhancements/blob/main/update_tabs.py): maintenance script · One-off scripts for updating or fixing tab metadata. · `update_tabs.py`

## Connections

- 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.
