Timesheets & Projects (TSM)
Module code TSM · Release R3 · Packaging Add-on · Requirements
FR-TSM-*,BR-TSM-*in the PRD and BRD · Related Attendance, Organization (shared accounts)
1. Overview and scope
TSM serves IT and services SMEs: who worked on which project and task, for how long, whether it is billable, and how actual effort compares with the plan.
In scope: projects linked to a shared client account; project roles and team assignment with allocation percentage; tasks with planned hours and dates; weekly grid entry with daily rows; the rule "timesheet hours ≤ attendance hours"; billable and non-billable flags and rates (export only); approval by project manager through NTF; defaulter detection and nudges; period lock; bench view; effort variance.
Out of scope: invoicing, resource capacity planning, Gantt charts.
2. Learned from the reference product
Source: Spryple analysis, §10 and §21.8.
- [Observed] Admin masters: Clients (contact, designation, start date, address), Projects, Assign Team, Tasks and Project Roles, with duplicate checks and Active/Inactive (A: Time Sheet).
- [Observed] Manager dashboard: active projects, assigned employees, bench count, hours by project, status with and without variance, estimated vs consumed hours; pending approvals with bulk actions; Defaulters with "Send Notification" (M: Time Sheet).
- [Observed] Employee submits rows of date, project, task, description, hours, % and task completed; an HR rule "limit timesheet hours to attendance hours" is referenced but not in the documented rules (E: Time Sheet; defect D11).
- [Observed] Effort variance = (Actual − Planned) / Planned, verified on sample rows (§21.8).
- [Inferred] Timesheet clients duplicate the CRM client master; no billable split, weekly grid or period lock (§10).
3. Our design decisions
| ID | Decision [Proposed] | Reason |
|---|---|---|
| D-TSM-01 | Projects reference org_account (shared with FFM). | One client master. |
| D-TSM-02 | Weekly timesheet as the unit of submission and approval; daily rows inside. | Matches how services teams work; fewer approvals. |
| D-TSM-03 | Attendance cap enforced per day with policy action BLOCK or WARN, reading att_day.worked_minutes (and allowing WFH/OD days). | Implements the referenced rule explicitly. |
| D-TSM-04 | Period lock after month end; edits after lock need reopening by an admin. | Billing exports must be stable. |
4. Domain model
5. State machines
When a week has entries for several projects, each project manager approves their own lines (ALL mode in NTF); the sheet is approved when all lines are.
6. Key business logic
validateDay(employee, date, entries, policy):
booked = sum(entries.hours on date)
day = ATT.day(employee, date)
cap = day.worked_minutes / 60 if day.status in (P, HD, WP, HP) else
policy.wfh_cap_hours if day.status in (WFH, OD) else 0
if booked > cap + policy.tolerance_hours: apply policy.cap_action (BLOCK or WARN)
defaulters(week):
employees with active project membership and timesheet missing or Draft after
policy.submit_by (e.g. Monday 12:00) ; nudge via NTF ; escalate to manager after N nudges
effortVariance(task) = (actual_hours - planned_hours) / planned_hours # as observed
bench(date) = active employees with no allocation valid on date
7. Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
entry.granularity | enum | WEEKLY | DAILY or WEEKLY submission |
attendance_cap.enabled | boolean | true | Hours limited to attendance |
attendance_cap.action | enum | WARN | BLOCK or WARN |
attendance_cap.tolerance_hours | number | 0.5 | Allowance |
wfh_cap_hours | number | 9 | Cap on WFH and on-duty days |
submit_by | string | MON 12:00 | Deadline for the previous week |
defaulter.max_nudges | integer | 2 | Before manager escalation |
lock.after_days | integer | 5 | Days after month end to lock |
min_entry_hours | number | 0.25 | Smallest entry |
8. Screens by persona
| Persona | Web | Mobile |
|---|---|---|
| Employee | Weekly grid, copy last week, my tasks with progress | Daily quick entry (R3) |
| Project manager | Approvals with bulk actions, project dashboard (estimated vs consumed, variance), task assignment | Approvals |
| Line manager / HR | Defaulters with send notification, bench | — |
| Admin | Projects, roles, tasks, team assignment, period lock | — |
| Org owner | Utilisation and billable share | — |
9. Events
| Event | Consumers |
|---|---|
tsm.timesheet.submitted | NTF (workflow) |
tsm.timesheet.approved, tsm.timesheet.rejected | NTF, RPT |
tsm.defaulter.detected | NTF |
tsm.period.locked | RPT, billing export |
Consumed: att.day.computed (cap revalidation warnings), org.account.updated, ext.lwd.reached (end memberships).
10. API surface
| Resource | Main operations |
|---|---|
/v1/tsm/projects and /:id/members | CRUD |
/v1/tsm/tasks | CRUD |
/v1/tsm/timesheets | GET by week, PUT entries, POST /:id/submit, POST /:id/recall |
/v1/tsm/defaulters | GET, POST /notify |
/v1/tsm/period-locks | POST, POST /:id/reopen |
Detailed in API endpoints.
11. Permissions
| Permission | Scopes | Default roles |
|---|---|---|
tsm.timesheet.submit | SELF | employee |
tsm.timesheet.approve | own projects | project manager (resolver) |
tsm.project.manage | ORG | hr_admin or a delegated project admin |
tsm.task.manage | own projects | project manager |
tsm.period.lock | ORG | hr_admin |
tsm.report.export | own projects, ORG | project manager, org_owner |
12. Reports
| Report | Contents | Reference |
|---|---|---|
| Project summary | Client, project, manager, estimated days, worked hours, status | [Observed] §21.8 |
| Effort variance | Planned vs actual hours and dates, variance % | [Observed] §21.8 |
| Timesheet summary | Hours by employee, project, week | [Observed] §10 |
| Defaulters | Missing weeks by employee | [Observed] §10 |
| Utilisation and billable share | Billable hours over available hours | [Proposed] |
| Bench | Unallocated employees | [Observed] §10 |
13. Release and priority
| Capability | Release | MoSCoW |
|---|---|---|
| Projects, tasks, team, weekly entry, approvals | R3 | Must |
| Attendance cap | R3 | Must |
| Defaulters and nudges | R3 | Should |
| Billable flags and rates export | R3 | Should |
| Period lock | R3 | Should |
| Effort variance and bench | R3 | Should |
14. Open questions
- Should approved billable hours export to accounting (Tally, Zoho Books) as invoice lines? Proposed as a CSV export only.
- Do we allow timesheets for employees without attendance (consultants)? If so, the cap must be off for their employment type.