# sapphirefountains/crm_enhancements architecture

> Architecture diagram of the GitHub repository sapphirefountains/crm_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/crm_enhancements
- Repository: https://github.com/sapphirefountains/crm_enhancements

## Overview

1. **Overall shape**
   - This is a **Frappe/ERPNext app** that adds CRM-specific enhancements on top of an existing ERPNext installation.
   - It is not a standalone service; it plugs into the ERPNext runtime through Frappe’s app, hooks, DocTypes, and client script mechanisms.

2. **Main boundary**
   - The repository splits cleanly into:
     - **Python backend code** for server-side logic and integrations
     - **Browser-side JavaScript** for CRM UI behavior
     - **Frappe metadata/configuration** for registration, hooks, and custom DocTypes

3. **Server-side application package**
   - The core Python app lives under `crm_enhancements/crm_enhancements/`.
   - `api.py` is the likely entry point for **whitelisted Frappe API methods** exposed to the client side or other Frappe components.
   - `drive_utils.py` isolates **Google Drive-related logic**, keeping external integration concerns separate from UI and DocType code.

4. **Google Drive integration**
   - The app clearly includes an external-service boundary to **Google Drive**.
   - That integration is probably used to create, locate, or manage project folders from CRM data.
   - `drive_utils.py` is the central abstraction for Drive operations, while the settings DocType supplies the configurable credentials/paths/behavior.

5. **Custom settings DocType**
   - `doctype/project_folder_google_drive_settings/` contains a custom DocType named **Project Folder Google Drive Settings**.
   - This is the app’s main persisted configuration surface for the Drive integration.
   - The JSON file defines the DocType schema; the Python file likely contains validation or helper behavior.

6. **CRM UI customization**
   - The `public/js/opportunity.js` and `public/js/opportunity_list.js` files are client-side extensions for the **Opportunity** form and list view.
   - These scripts likely add buttons, actions, field behavior, or automation triggers tied to the app’s CRM workflow.
   - This is the main front-end boundary: browser actions call back into Frappe/Python through the API layer.

7. **Frappe hooks and app registration**
   - `hooks.py` is the wiring layer that connects the app to ERPNext/Frappe.
   - This is where assets, doc events, overrides, or scheduled actions would be registered so the custom logic runs inside the ERPNext lifecycle.
   - `modules.txt` and `__init__.py` files support Frappe’s module discovery.

8. **Migration/versioning support**
   - `patches.txt` indicates the app has database or schema migrations that Frappe can apply during upgrades.
   - This suggests the app evolves its DocTypes/configuration over time rather than being static.

9. **Templates/pages**
   - The `templates/pages/` structure exists, but there are no concrete page files shown.
   - Architecturally, this is an extension point for server-rendered Frappe pages, though it does not appear to be the primary delivery mechanism here.

10. **Tooling and delivery**
   - The repo is built for Frappe bench deployment and uses `pre-commit` with `ruff`, `eslint`, `prettier`, and `pyupgrade`.
   - That implies a mixed Python/JavaScript codebase with code quality enforced across backend and frontend layers.

11. **Likely data flow**
   - A user interacts with the **Opportunity** UI in ERPNext.
   - Client-side scripts invoke server methods in `api.py`.
   - Server logic consults the **Google Drive settings DocType**, then uses `drive_utils.py` to perform Drive operations.
   - Results flow back to the UI, and any configuration/state is stored in Frappe’s database as DocType records.

12. **Diagram takeaway**
   - The architecture is best drawn as an **ERPNext/Frappe extension app** with three key subsystems:
     - CRM UI customizations for Opportunity
     - Backend API and helper utilities
     - Google Drive configuration/integration via a custom settings DocType

Main entry points: [`crm_enhancements/hooks.py`](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/hooks.py) (hooks.py), [`crm_enhancements/crm_enhancements/api.py`](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/api.py) (API), [`crm_enhancements/crm_enhancements/drive_utils.py`](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/drive_utils.py) (Drive utils), [`crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.json`](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.json) (Settings schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_backend["Backend"]
  node_node_api["API<br/>Whitelisted methods<br/>[api.py]"]
  node_node_drive_utils["Drive utils<br/>Google Drive adapter<br/>[drive_utils.py]"]
end

subgraph group_grp_frontend["Frontend"]
  node_node_opportunity_js["Opportunity UI<br/>Form script<br/>[opportunity.js]"]
  node_node_opportunity_list_js["Opportunity list<br/>List script"]
end

subgraph group_grp_frappe["Frappe wiring"]
  node_node_hooks["hooks.py<br/>Frappe hooks<br/>[hooks.py]"]
  node_node_modules["modules.txt<br/>Module registry<br/>[modules.txt]"]
  node_node_patches["patches.txt<br/>Migrations<br/>[patches.txt]"]
  node_node_templates["Pages<br/>Template area"]
  node_node_init_root(("Package init<br/>Python package<br/>[__init__.py]"))
  node_node_init_app(("App init<br/>Python package<br/>[__init__.py]"))
  node_node_config_init(("Config init<br/>Python package<br/>[__init__.py]"))
  node_node_templates_init(("Templates init<br/>Python package<br/>[__init__.py]"))
  node_node_pages_init(("Pages init<br/>Python package<br/>[__init__.py]"))
end

subgraph group_grp_config["Config & metadata"]
  node_node_settings_py["Settings logic<br/>DocType helper"]
  node_node_settings_json["Settings schema<br/>DocType schema"]
end

node_node_hooks -->|"exposes"| node_node_api
node_node_hooks -->|"loads"| node_node_opportunity_js
node_node_hooks -->|"loads"| node_node_opportunity_list_js
node_node_hooks -->|"registers"| node_node_settings_json
node_node_api -->|"uses"| node_node_drive_utils
node_node_api -->|"reads"| node_node_settings_py
node_node_drive_utils -->|"configured by"| node_node_settings_json
node_node_settings_py -->|"implements"| node_node_settings_json
node_node_opportunity_js -->|"calls"| node_node_api
node_node_opportunity_list_js -->|"calls"| node_node_api
node_node_opportunity_js -.->|"initiates"| node_node_drive_utils
node_node_opportunity_list_js -.->|"initiates"| node_node_drive_utils
node_node_patches -->|"evolves"| node_node_settings_json
node_node_modules -->|"discovers"| node_node_init_app
node_node_init_root -->|"contains"| node_node_init_app
node_node_templates -->|"contains"| node_node_pages_init
node_node_templates_init -->|"contains"| node_node_pages_init
node_node_config_init -.->|"supports"| node_node_hooks

click node_node_hooks "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/hooks.py"
click node_node_modules "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/modules.txt"
click node_node_patches "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/patches.txt"
click node_node_api "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/api.py"
click node_node_drive_utils "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/drive_utils.py"
click node_node_settings_py "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.py"
click node_node_settings_json "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.json"
click node_node_opportunity_js "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/public/js/opportunity.js"
click node_node_opportunity_list_js "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/public/js/opportunity_list.js"
click node_node_templates "https://github.com/sapphirefountains/crm_enhancements/tree/main/crm_enhancements/templates/pages"
click node_node_init_root "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/__init__.py"
click node_node_init_app "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/__init__.py"
click node_node_config_init "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/config/__init__.py"
click node_node_templates_init "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/templates/__init__.py"
click node_node_pages_init "https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/templates/pages/__init__.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_node_api,node_node_drive_utils toneBlue
class node_node_opportunity_js,node_node_opportunity_list_js toneAmber
class node_node_hooks,node_node_modules,node_node_patches,node_node_templates,node_node_init_root,node_node_init_app,node_node_config_init,node_node_templates_init,node_node_pages_init toneMint
class node_node_settings_py,node_node_settings_json toneRose
```

## Components

### Backend

Server-side Frappe app code and integrations.

- [API](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/api.py): Whitelisted methods · Server endpoints exposed to client scripts and other Frappe components. · `crm_enhancements/crm_enhancements/api.py`
- [Drive utils](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/drive_utils.py): Google Drive adapter · Encapsulates Google Drive operations and integration logic. · `crm_enhancements/crm_enhancements/drive_utils.py`

### Frontend

Browser-side CRM behavior for Opportunity views.

- [Opportunity UI](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/public/js/opportunity.js): Form script · Client-side customization for the Opportunity form. · `crm_enhancements/public/js/opportunity.js`
- [Opportunity list](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/public/js/opportunity_list.js): List script · Client-side customization for the Opportunity list view. · `crm_enhancements/public/js/opportunity_list.js`

### Frappe wiring

App registration, hooks, and module discovery.

- [hooks.py](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/hooks.py): Frappe hooks · Registers the app with Frappe/ERPNext and wires assets or lifecycle events. · `crm_enhancements/hooks.py`
- [modules.txt](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/modules.txt): Module registry · Frappe module discovery metadata. · `crm_enhancements/modules.txt`
- [patches.txt](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/patches.txt): Migrations · Upgrade patches for schema or data changes. · `crm_enhancements/patches.txt`
- [Pages](https://github.com/sapphirefountains/crm_enhancements/tree/main/crm_enhancements/templates/pages): Template area · Server-rendered page template extension point. · `crm_enhancements/templates/pages`
- [Package init](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/__init__.py): Python package · Top-level app package marker. · `crm_enhancements/__init__.py`
- [App init](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/__init__.py): Python package · Main app package marker for the Frappe app. · `crm_enhancements/crm_enhancements/__init__.py`
- [Config init](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/config/__init__.py): Python package · Configuration package marker. · `crm_enhancements/config/__init__.py`
- [Templates init](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/templates/__init__.py): Python package · Templates package marker. · `crm_enhancements/templates/__init__.py`
- [Pages init](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/templates/pages/__init__.py): Python package · Pages package marker. · `crm_enhancements/templates/pages/__init__.py`

### Config & metadata

Persisted DocType schema and migration support.

- [Settings logic](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.py): DocType helper · Python behavior for the Project Folder Google Drive Settings DocType. · `crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.py`
- [Settings schema](https://github.com/sapphirefountains/crm_enhancements/blob/main/crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.json): DocType schema · Frappe JSON metadata defining the custom settings DocType. · `crm_enhancements/crm_enhancements/doctype/project_folder_google_drive_settings/project_folder_google_drive_settings.json`

## Connections

- hooks.py → API: exposes · Hooks register server-side methods or app behavior.
- hooks.py → Opportunity UI: loads · Hooks can include browser assets for the Opportunity form.
- hooks.py → Opportunity list: loads · Hooks can include browser assets for the Opportunity list view.
- hooks.py → Settings schema: registers · Hooks connect custom DocTypes to the Frappe app.
- API → Drive utils: uses · API methods delegate Google Drive operations to the integration layer.
- API → Settings logic: reads · API methods can consult settings behavior and validation.
- Drive utils → Settings schema: configured by · Drive operations depend on persisted settings stored in the DocType.
- Settings logic → Settings schema: implements · Python file provides logic for the settings DocType schema.
- Opportunity UI → API: calls · Form actions trigger server-side API methods.
- Opportunity list → API: calls · List actions trigger server-side API methods.
- Opportunity UI → Drive utils: initiates · User actions may start Drive-related workflows through the backend.
- Opportunity list → Drive utils: initiates · List view actions may start Drive-related workflows through the backend.
- patches.txt → Settings schema: evolves · Patches support changes to the custom settings DocType over time.
- modules.txt → App init: discovers · Module metadata helps Frappe locate the app package.
- Package init → App init: contains · Top-level package contains the main app package.
- Pages → Pages init: contains · Template directory contains page package markers.
- Templates init → Pages init: contains · Template package contains the pages subpackage.
- Config init → hooks.py: supports · Config package supports app wiring and runtime configuration.
