# sapphirefountains/project_enhancements architecture

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

## Overview

1. **Repo type and core boundary**
   - This is a **Frappe/ERPNext app** named `project_enhancements`.
   - Its main purpose is to extend ERPNext’s **Projects** module with a custom dashboard, list-view behavior, and a small set of supporting configuration DocTypes.

2. **Primary user-facing surface: the Project Dashboard**
   - The main entry point is a **custom Desk page** at `project_enhancements/page/project_dashboard`.
   - Users interact with it as a single-page dashboard with tabs for **Active Projects, Inactive Projects, Priority Overview, and Tasks Tree**.
   - The dashboard is the central integration point between frontend state, server-side project/task data, and inline editing.

3. **Frontend orchestration**
   - `project_dashboard.js` is the dashboard controller: it owns **rendering, tab switching, filtering/search, sorting, group ordering, and event handling**.
   - The UI is split into reusable front-end pieces under `public/js/dashboard_components`, which suggests a modular client-side architecture rather than a monolithic script.
   - The dashboard also uses **inline editing** flows, so the browser is not just displaying data; it is a write-capable client.

4. **Task tree and Gantt-style visualization**
   - The app includes dedicated frontend assets for **hierarchical task visualization** and **Gantt-style scheduling**.
   - `public/js/task_tree_manager.js`, `public/js/task_gantt.js`, and the bundled `frappe-gantt` library indicate that task timelines and parent/child task relationships are first-class dashboard concerns.
   - The CSS files `task_tree.css` and `frappe-gantt.css` support these richer visualizations.

5. **Backend API and data shaping**
   - `page/project_dashboard/project_dashboard.py` is the server-side boundary for the dashboard.
   - It exposes whitelisted functions to **check access, fetch project/task data, return metadata such as status/priority options, and persist inline updates**.
   - The backend is responsible for turning ERPNext records into the grouped and sorted structures the frontend expects.

6. **ERPNext data sources**
   - The dashboard primarily reads and writes standard ERPNext doctypes: **Project** and **Task**.
   - It also uses related metadata such as **Project Type**, status, priority, assignees, and dates to drive sorting and display.
   - The design implies the frontend never queries the database directly; all data access is mediated through Frappe server calls.

7. **Access control and configuration**
   - `Project Dashboard Settings` is a **Single DocType** used to configure access.
   - `Project Dashboard Permitted Role` is a child table that stores the **roles allowed to view the dashboard**.
   - This creates an admin-controlled permission boundary: dashboard visibility is not hardcoded in the client.

8. **Default list-view customization**
   - The standard Project list is customized via `doctype/project/project_list.js`.
   - That client script calls a backend helper in `project.py` to apply a default **group_by = Project Type** behavior.
   - This is a smaller but important integration point because it changes the standard ERPNext list experience, not just the custom dashboard.

9. **Custom DocTypes and metadata**
   - The app contains its own DocType definitions under `doctype/master_project`, `doctype/project_dashboard_settings`, and `doctype/project_dashboard_permitted_role`.
   - `master_project` appears to be a custom business object with its own server and client scripts plus tests, separate from ERPNext’s standard `Project`.
   - The presence of fixture files for `custom_field.json` and `property_setter.json` shows the app also modifies ERPNext metadata at install time.

10. **Install-time migrations and cleanup**
   - `patches/` contains migration scripts such as `rename_master_projects.py`, `delete_master_project.py`, and `update_project_statuses.py`.
   - These indicate the app has evolved schema/data over time and uses Frappe patching to keep existing sites consistent during upgrades.
   - `setup_address.py` suggests additional setup logic beyond simple DocType installation.

11. **Supporting assets and an alternate front-end bundle**
   - The root-level `Custom HTML Block/` directory contains `projects_dashboard.html`, `.css`, and `.js`, which looks like a separate embeddable or prototype version of the dashboard UI.
   - This is distinct from the main Frappe app package and likely serves as a parallel static presentation of similar functionality.

12. **Testing and delivery**
   - There are Python tests for key doctypes/pages, and the repo includes GitHub Actions CI plus pre-commit tooling.
   - Tooling is centered on keeping the Frappe app consistent across backend Python, client-side JavaScript, and packaged static assets.

Main entry points: [`project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py`](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py) (Dashboard API), [`project_enhancements/hooks.py`](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/hooks.py) (Hooks), [`project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js`](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js) (Dashboard JS), [`project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py`](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py) (Dashboard settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_dashboard["Project dashboard"]
  node_node_dashboard_page["Project Dashboard<br/>Desk page"]
  node_node_dashboard_js["Dashboard JS<br/>client controller"]
  node_node_dashboard_api["Dashboard API<br/>server API"]
  node_node_dashboard_components["UI components<br/>frontend modules"]
  node_node_task_tree["Task tree<br/>hierarchy view"]
  node_node_task_gantt["Task Gantt<br/>timeline view<br/>[task_gantt.js]"]
  node_node_frappe_gantt["Gantt library<br/>embedded library"]
end

subgraph group_group_doctypes["Custom doctypes"]
  node_node_project_model["Project model<br/>doctype extension<br/>[project.py]"]
  node_node_master_project["Master Project<br/>custom doctype<br/>[master_project.py]"]
  node_node_dashboard_settings["Dashboard settings<br/>single doctype"]
  node_node_dashboard_role["Permitted role<br/>child table"]
end

subgraph group_group_platform["Platform integration"]
  node_node_project_list["Project list<br/>list script<br/>[project_list.js]"]
  node_node_fixtures["Fixtures<br/>metadata seed<br/>[custom_field.json]"]
  node_node_patches["Patches<br/>migration scripts"]
  node_node_hooks["Hooks<br/>app wiring<br/>[hooks.py]"]
end

subgraph group_group_alt_ui["Alternate UI bundle"]
  node_node_html_block["HTML block UI<br/>static bundle"]
end

node_node_dashboard_page -->|"uses"| node_node_dashboard_js
node_node_dashboard_js -->|"composes"| node_node_dashboard_components
node_node_dashboard_js -->|"calls"| node_node_dashboard_api
node_node_dashboard_api -->|"reads/writes"| node_node_project_model
node_node_dashboard_api -->|"reads/writes"| node_node_master_project
node_node_dashboard_api -->|"checks access"| node_node_dashboard_settings
node_node_dashboard_settings -->|"contains"| node_node_dashboard_role
node_node_task_tree -->|"fetches data"| node_node_dashboard_api
node_node_task_gantt -->|"renders with"| node_node_frappe_gantt
node_node_task_gantt -->|"fetches data"| node_node_dashboard_api
node_node_project_model -->|"extends"| node_node_project_list
node_node_project_list -->|"delegates"| node_node_dashboard_api
node_node_hooks -->|"registers"| node_node_fixtures
node_node_hooks -->|"runs"| node_node_patches
node_node_hooks -->|"exposes"| node_node_dashboard_settings
node_node_hooks -->|"exposes"| node_node_master_project
node_node_html_block -.->|"mirrors"| node_node_dashboard_page

click node_node_dashboard_page "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py"
click node_node_dashboard_js "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js"
click node_node_dashboard_api "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py"
click node_node_dashboard_components "https://github.com/sapphirefountains/project_enhancements/tree/develop/project_enhancements/public/js/dashboard_components"
click node_node_task_tree "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/task_tree_manager.js"
click node_node_task_gantt "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/task_gantt.js"
click node_node_frappe_gantt "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/lib/frappe-gantt.umd.js"
click node_node_project_model "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project/project.py"
click node_node_project_list "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project/project_list.js"
click node_node_master_project "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/master_project/master_project.py"
click node_node_dashboard_settings "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py"
click node_node_dashboard_role "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project_dashboard_permitted_role/project_dashboard_permitted_role.py"
click node_node_fixtures "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/fixtures/custom_field.json"
click node_node_patches "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/patches/rename_master_projects.py"
click node_node_hooks "https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/hooks.py"
click node_node_html_block "https://github.com/sapphirefountains/project_enhancements/blob/develop/Custom HTML Block/projects_dashboard.html"

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_dashboard_page,node_node_dashboard_js,node_node_dashboard_api,node_node_dashboard_components,node_node_task_tree,node_node_task_gantt,node_node_frappe_gantt toneBlue
class node_node_project_model,node_node_master_project,node_node_dashboard_settings,node_node_dashboard_role toneAmber
class node_node_project_list,node_node_fixtures,node_node_patches,node_node_hooks toneMint
class node_node_html_block toneRose
```

## Components

### Project dashboard

Custom Desk page, frontend orchestration, and task visualization.

- [Project Dashboard](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py): Desk page · Primary custom page for active/inactive projects, priority overview, and task tree. · `project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py`
- [Dashboard JS](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js): client controller · Manages rendering, tabs, filtering, sorting, group ordering, and inline-edit events. · `project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js`
- [Dashboard API](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py): server API · Whitelisted backend for access checks, project/task fetches, metadata, and inline saves. · `project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py`
- [UI components](https://github.com/sapphirefountains/project_enhancements/tree/develop/project_enhancements/public/js/dashboard_components): frontend modules · Reusable dashboard pieces for active projects, completed projects, priority views, tasks, and API glue. · `project_enhancements/public/js/dashboard_components`
- [Task tree](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/task_tree_manager.js): hierarchy view · Client-side manager for parent/child task structure and tree interactions. · `project_enhancements/public/js/task_tree_manager.js`
- [Task Gantt](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/task_gantt.js): timeline view · Gantt-style scheduling and timeline rendering for tasks and portfolios. · `project_enhancements/public/js/task_gantt.js`
- [Gantt library](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/public/js/lib/frappe-gantt.umd.js): embedded library · Bundled frappe-gantt runtime used by the dashboard timeline views. · `project_enhancements/public/js/lib/frappe-gantt.umd.js`

### Custom doctypes

App-owned doctypes and model extensions around projects and dashboard access.

- [Project model](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project/project.py): doctype extension · Custom server/client logic for ERPNext Project, including dashboard-related behavior. · `project_enhancements/project_enhancements/doctype/project/project.py`
- [Master Project](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/master_project/master_project.py): custom doctype · Separate business object with its own model, client script, and tests. · `project_enhancements/project_enhancements/doctype/master_project/master_project.py`
- [Dashboard settings](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py): single doctype · Admin configuration for dashboard access and behavior. · `project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py`
- [Permitted role](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project_dashboard_permitted_role/project_dashboard_permitted_role.py): child table · Stores roles allowed to view the project dashboard. · `project_enhancements/project_enhancements/doctype/project_dashboard_permitted_role/project_dashboard_permitted_role.py`

### Platform integration

Hooks, fixtures, patches, and list-view customization that integrate with ERPNext.

- [Project list](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/project_enhancements/doctype/project/project_list.js): list script · Overrides the standard Project list to group by Project Type by default. · `project_enhancements/project_enhancements/doctype/project/project_list.js`
- [Fixtures](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/fixtures/custom_field.json): metadata seed · Custom field and property setter fixtures applied at install time. · `project_enhancements/fixtures/custom_field.json`
- [Patches](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/patches/rename_master_projects.py): migration scripts · Upgrade scripts for renames, cleanup, status updates, and site setup. · `project_enhancements/patches/rename_master_projects.py`
- [Hooks](https://github.com/sapphirefountains/project_enhancements/blob/develop/project_enhancements/hooks.py): app wiring · Frappe hook definitions that register doctypes, fixtures, and runtime integration. · `project_enhancements/hooks.py`

### Alternate UI bundle

Standalone HTML block assets for a parallel dashboard presentation.

- [HTML block UI](https://github.com/sapphirefountains/project_enhancements/blob/HEAD/Custom%20HTML%20Block/projects_dashboard.html): static bundle · Alternate embeddable dashboard presentation in standalone HTML, CSS, and JS. · `Custom HTML Block/projects_dashboard.html`

## Connections

- Project Dashboard → Dashboard JS: uses · The page is driven by its front-end controller.
- Dashboard JS → UI components: composes · The controller assembles modular dashboard views.
- Dashboard JS → Dashboard API: calls · Client interactions flow through the server API.
- Dashboard API → Project model: reads/writes · The dashboard backend shapes ERPNext Project data.
- Dashboard API → Master Project: reads/writes · Dashboard logic also interacts with the custom Master Project object.
- Dashboard API → Dashboard settings: checks access · Visibility and behavior are gated by dashboard settings.
- Dashboard settings → Permitted role: contains · Permitted roles are stored as child records.
- Task tree → Dashboard API: fetches data · Tree views rely on server-shaped project/task structures.
- Task Gantt → Gantt library: renders with · Timeline UI uses the bundled Gantt runtime.
- Task Gantt → Dashboard API: fetches data · Scheduling and timeline data come from the backend.
- Project model → Project list: extends · The Project model is paired with list-view customization.
- Project list → Dashboard API: delegates · The list script relies on a backend helper to set grouping.
- Hooks → Fixtures: registers · App hooks seed metadata modifications.
- Hooks → Patches: runs · Upgrade hooks invoke migration scripts.
- Hooks → Dashboard settings: exposes · The settings doctype is part of the app wiring.
- Hooks → Master Project: exposes · The custom doctype is registered through app hooks.
- HTML block UI → Project Dashboard: mirrors · The static bundle appears to parallel the main dashboard experience.
