Next PMS — Developer Documentation

Technical reference for developers working on next_pms. For end-user docs see the hosted guide at /pms-guide (source: next_pms/www/pms-guide.html).

Architecture

next_pms/                       Frappe app (Python, v15)
├── next_pms/
│   ├── api/                    Whitelisted HTTP endpoints (SPA backend)
│   ├── next_pms/doctype/       DocTypes + controllers
│   ├── www/                    Public web pages (user-guide, pms-portal)
│   ├── public/frontend/        BUILT Vue SPA (committed — see Deploy)
│   ├── tasks.py                Scheduler jobs (emails, reminders, alerts)
│   └── hooks.py                Scheduler events, fixtures, assets
├── frontend/                   Vue 3 + Vite + Pinia SPA source
│   └── src/{views,components,store,utils}
├── android-capacitor/          Capacitor Android wrapper
└── docs/                       This documentation

• SPA served at /next-pms from next_pms/public/frontend (vite build output).
• Client portal at /pms-portal?token=… — server-rendered, token-auth, no login.
• Desk is secondary; primary UX is the SPA.

DocTypes

API layer (next_pms/api/)

All SPA calls go through whitelisted methods here. Key modules:

Hard rules (production incidents happened — respect these)

1. PMS Comment fields are comment and user — not content/author.
2. All portal frappe.get_all() need ignore_permissions=True — PMS Customer users lack doctype read perms.
3. Never frappe.get_doc() in portal APIs — use frappe.db.get_value() / frappe.get_all(..., ignore_permissions=True).
4. Whitelisted methods that expose cross-user data must gate on is_admin_user() or is_manager_user() and frappe.throw otherwise.
5. Coerce inputs with cint/flt/cstr/getdate from frappe.utils, never bare int()/float().
6. No f-string SQL, ever. frappe.qb or parameterised frappe.db.sql.

Metrics engine

_hours.py — the shared basis

Every report derives "how many hours should this person have worked" from here so numbers stay consistent:

target_hours = effective_working_days × working_hours_per_day (default 8)

effective_working_days = all days in range
                       − Sundays
                       − holidays (employee's Holiday List, weekly_off=0)
                       − full-day approved leave (docstatus != 2!)
                       − 0.5 × half-day approved leave

• PMS Time Log.duration_hours is the only "actual hours" source. Check-in/out is informational.
• Frappe quirk handled here: cancelled Leave Applications keep status='Approved' with docstatus=2 — must exclude docstatus 2 explicitly.

The two headline metrics — do not conflate

Windows also differ by surface: weekly email = fixed Mon–Fri week (Saturday cron, Saturday excluded from target); Task Report periods = rolling N days ending today. Same engine, different slice — both metrics are now labelled with their formula wherever shown.

Performance Score (performance.py)

Management-only composite, 8 dimensions, weights fixed in WEIGHTS (sum 100):

• Composite = Σ(weight × score) ÷ Σ included weights. Dimensions with no data are excluded and weights renormalised — missing data never scores zero.
• "Completed in window" proxy = status='Done' AND modified BETWEEN window (PMS Task has no completion_date — roadmap item).
• Bands: A ≥ 85, B ≥ 70, C ≥ 50, else D.
• Methodology is user-documented inside the Performance tab (PerformanceTab.vue) — keep code, tab docs and this file in sync when changing formulas.

Scheduler jobs (tasks.py + hooks.py)

⚠️ After deploying scheduler-code changes, restart workers — stale workers silently run old code (2026-06-18 incident: 4-day silent outage).

⚠️ A new cron entry in hooks.py needs a Scheduled Job Type sync to start firing. Full bench migrate does it, but when migrate is risky, sync just the jobs:

# bench --site <site> console
from frappe.core.doctype.scheduled_job_type.scheduled_job_type import sync_jobs
sync_jobs(); frappe.db.commit()

Frontend (Vue 3 + Vite + Pinia)

• Views in frontend/src/views, shared components in frontend/src/components.
• API calls: import { call } from '@/utils/frappe' → call('next_pms.api.module.method', {args}).
• Role gates: useSettingsStore() → isAdmin, isManager, canViewFinance. Gate both the UI (v-if) and the backend (throw) — UI hiding alone is not security.
• Dev: npx vite --port 8081 (proxies /api to localhost:8000). Local site: mysite.local — bench serve serves sites/currentsite.txt; if the SPA says "App next_pms is not installed", you're on the wrong current site (bench use mysite.local).

Build & Deploy

Built SPA assets are committed to the repo (next_pms/public/frontend). Production deploy is therefore pull-only:

# 1. Local: build + commit
cd frontend && yarn build          # outputs to next_pms/public/frontend
git add -A && git commit && git push

# 2. Server (as bench user)
cd frappe-bench/apps/next_pms && git pull origin main

# 3. Restart (root — `bench restart` fails as bench user on office)
supervisorctl restart all

# 4. Only if a www/ page changed:
bench --site <site> clear-website-cache

# 5. Only if DocType JSON / fixtures / hooks cron changed:
bench --site <site> migrate       # ⚠️ see migrate warning below

• yarn build in frontend/ ≠ bench build. The former builds the SPA; the latter bundles Frappe assets. SPA changes need the former.
• ⚠️ Migrate on office is currently booby-trapped by an HRMS web-form duplicate. For new doctypes prefer targeted frappe.reload_doc(module, "doctype", "name") over full migrate; always take a DB backup first.
• Multiple sites exist on production benches — verify the site before any bench --site command.

Testing

bench --site mysite.local run-tests --app next_pms          # all
bench --site mysite.local run-tests --module next_pms.api.test_hours

Tests live beside the modules (api/test_*.py) and in doctype folders (test_<doctype>.py), inheriting FrappeTestCase. Anything touching money, hours math, or permissions needs a test.

Roadmap

Performance snapshot lifecycle (how to work with it)

1st 08:00 cron ─► compute_team_performance(prev month)
              ─► _upsert_month_snapshots()  → insert + submit  (docstatus 1 = FROZEN)
              ─► commit
              ─► member emails + leaderboard email, FROM the snapshots

• Freeze guarantee: any post-submit write to a non-allow_on_submit field raises UpdateAfterSubmitError (core, tested). Snapshots cannot be deleted/cancelled/amended by any role.
• Adjustment path: apply_adjustment → gate → fresh frappe.get_doc → set override fields in memory → one doc.save(). Controller validates ±10 + mandatory reason in BOTH validate and before_update_after_submit (plain validate does not run post-submit in v15). final_score = clamp(composite + adj, 0, 100), final_band recomputed via the shared _band. Version row records old→new (audit trail).
• Trend: get_score_history(user) → Score History card in PerformanceTab Individual view.
• Tests: next_pms/api/test_performance_snapshots.py (22 cases: naming, freeze matrix, idempotency, clamps, reason rule, gates, Version audit, email idempotency). Run: bench --site mysite.local run-tests --app next_pms --module next_pms.api.test_performance_snapshots.

Deploying a NEW DocType to office (migrate is broken there)

# bench --site office console — child table FIRST, then parent
frappe.reload_doc("next_pms", "doctype", "pms_performance_dimension")
frappe.reload_doc("next_pms", "doctype", "pms_performance_score")
frappe.db.commit()

Then restart workers (root supervisorctl restart all). Never bench migrate on office until the HRMS web-form duplicate is fixed. New cron hooks additionally need sync_jobs() (see above).

Settings reference (PMS AI Settings, Single)

Pattern: new toggles are read with getattr(frappe.get_cached_doc("PMS AI Settings"), "<field>", <default>) so code deploys before schema — add the actual Check field later for UI control, no code change needed.

Release process

# 1. Bump version (both files must match)
#    next_pms/__init__.py  → __version__
#    pyproject.toml        → version
# 2. Commit, push, tag
git tag -a v<X.Y.Z> -m "next_pms v<X.Y.Z>"
git push origin main --tags
# 3. GitHub release with generated notes
gh release create v<X.Y.Z> --title "next_pms v<X.Y.Z>" --notes-file <notes.md>

Semver: MAJOR = breaking DocType/API change, MINOR = features (new endpoints, tabs, emails), PATCH = fixes.

Related docs

• README.md — features, install, access points
• PERMISSIONS.md — role system deep-dive
• /pms-guide (hosted) — end-user documentation
• CLAUDE.md — AI-agent project memory (safety rules, session logs)