How sapphirefountains/project_enhancements works
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_dashboard.py Dashboard API · hooks.py Hooks · project_dashboard.js Dashboard JS · project_dashboard_settings.py Dashboard settings
Components 16
Project dashboard
Custom Desk page, frontend orchestration, and task visualization.
- Project Dashboard · Primary custom page for active/inactive projects, priority overview, and task tree.
project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.py - Dashboard JS · Manages rendering, tabs, filtering, sorting, group ordering, and inline-edit events.
project_enhancements/project_enhancements/page/project_dashboard/project_dashboard.js - Dashboard 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 · Reusable dashboard pieces for active projects, completed projects, priority views, tasks, and API glue.
project_enhancements/public/js/dashboard_components - Task tree · Client-side manager for parent/child task structure and tree interactions.
project_enhancements/public/js/task_tree_manager.js - Task Gantt · Gantt-style scheduling and timeline rendering for tasks and portfolios.
project_enhancements/public/js/task_gantt.js - Gantt 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 · Custom server/client logic for ERPNext Project, including dashboard-related behavior.
project_enhancements/project_enhancements/doctype/project/project.py - Master Project · Separate business object with its own model, client script, and tests.
project_enhancements/project_enhancements/doctype/master_project/master_project.py - Dashboard settings · Admin configuration for dashboard access and behavior.
project_enhancements/project_enhancements/doctype/project_dashboard_settings/project_dashboard_settings.py - Permitted role · 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 · Overrides the standard Project list to group by Project Type by default.
project_enhancements/project_enhancements/doctype/project/project_list.js - Fixtures · Custom field and property setter fixtures applied at install time.
project_enhancements/fixtures/custom_field.json - Patches · Upgrade scripts for renames, cleanup, status updates, and site setup.
project_enhancements/patches/rename_master_projects.py - Hooks · 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 · Alternate embeddable dashboard presentation in standalone HTML, CSS, and JS.
Custom HTML Block/projects_dashboard.html
Connections 17
- 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.