HRM — Product Specification

v1.0 — DraftPlatform: VENI-AI ShellPlan: Pro+

1. Overview

What is HRM?

HRM (Human Resource Management) is the organization's employee management system. It centralizes employee profiles, manages leave requests, guides new hires through onboarding checklists, and displays the organizational chart. All data is scoped to a single organization and connected to the Shell's RBAC so the right people see the right information.

Why it exists

Growing organizations quickly outgrow spreadsheets for tracking employee data and leave balances. HRM provides a single, permission-controlled record of who works at the company, their role and reporting structure, their leave history, and their onboarding progress — without requiring a separate HR SaaS subscription.

Who is it for?

Persona	What they do in HRM
Employee	Views own profile; submits and tracks leave requests; completes onboarding checklist
Manager	Approves/rejects leave for direct reports; views team profiles and leave calendar
HR Admin	Manages all employee profiles; configures leave policies; oversees onboarding
Admin	Full access; configures org structure and department hierarchy

2. Goals & Non-Goals

Goals ✅

Employee profiles: personal info, job title, department, manager, start date, contact
Leave management: request, approve, reject, cancel; leave balance per type
Onboarding checklists: templates per role; task assignment; progress tracking
Organizational chart: visual hierarchy by department and reporting line
Team leave calendar: see who is off and when
Leave balance reports per employee (HR Admin view)

Non-Goals ❌

Payroll processing or salary management
Performance reviews and appraisals — v2 roadmap
Recruitment and applicant tracking
Time tracking and attendance logging
Benefits enrollment and insurance management

3. User Stories

3.1 View and edit employee profile

As an employee, I want to view and update my profile, so that my contact information and job details are always accurate.

Acceptance criteria:

I can see my own profile with: full name, job title, department, manager, start date, work email, phone
I can edit: phone number, emergency contact, and profile photo
Fields like job title, department, and manager can only be edited by HR Admin
Changes to editable fields are saved immediately
I can view (read-only) any other employee's public profile: name, title, department, manager

3.2 Submit a leave request

As an employee, I want to submit a leave request, so that my manager knows I will be away and can plan accordingly.

Acceptance criteria:

I select the leave type (Annual, Sick, Unpaid, Public Holiday top-up), start date, and end date
The form shows my current balance for the selected leave type before I submit
I can add an optional note for context
On submit, the request status is Pending and my manager receives an in-app notification
I cannot submit a request if I have insufficient balance (except for Sick or Unpaid)
I can cancel a Pending request; I cannot cancel an Approved request that has already started

3.3 Approve or reject a leave request (manager)

As a manager, I want to review and act on leave requests from my direct reports, so that I can manage team availability.

Acceptance criteria:

I see a list of all Pending requests from my direct reports
Each request shows: employee name, leave type, dates, duration (working days), and note
I can approve or reject with a required comment on rejection
On approval the employee is notified and their leave balance is deducted
On rejection the employee is notified with my comment; their balance is unchanged
I can view the team leave calendar to check for conflicts before deciding

3.4 Complete onboarding checklist (new hire)

As a new employee, I want to follow a structured onboarding checklist, so that I know exactly what to do in my first weeks and don't miss anything important.

Acceptance criteria:

When my profile is created by HR Admin with a role, an onboarding checklist is automatically generated from the role's template
The checklist shows tasks organized by week (Week 1, Week 2, Week 3–4)
Each task has a title, description, due date, and optionally a linked document or URL
I can mark tasks as complete; completion is timestamped and visible to my manager
My manager and HR Admin can also mark tasks on my behalf
A progress bar shows my overall completion percentage

3.5 View the org chart

As an employee, I want to see the organizational chart, so that I understand the company structure and know who reports to whom.

Acceptance criteria:

The org chart renders as a visual tree, top-down from the CEO / top-level role
Each node shows: profile photo (or initials), name, and job title
I can click any node to open a mini-profile card with contact details and a link to the full profile
Departments are visually grouped with a color band
I can search by name and the chart zooms to highlight the matching node
The chart is view-only for all employees; only HR Admin can change the reporting structure

3.6 View team leave calendar

As a manager, I want to see a calendar showing when my team members are on leave, so that I can avoid scheduling conflicts.

Acceptance criteria:

The calendar shows approved and pending leaves for all my direct reports
I can switch between month view and week view
Leaves are color-coded by type (Annual = blue, Sick = orange, Unpaid = grey)
Pending leaves are shown with a striped/dashed border to distinguish from approved
Public holidays are shown as background highlights
I can click any leave block to see the employee name, leave type, dates, and approval status

4. Business Rules

Rule	Detail
Org isolation	All HRM data is scoped to a single organization
Leave balance enforcement	Annual leave submissions are blocked if balance < requested days
Working days calculation	Leave duration counts working days only (Mon–Fri excluding public holidays)
Approval chain	Leave requests go to the employee's direct manager only (no skip-level in v1)
Balance accrual	Annual leave accrues monthly (annual entitlement ÷ 12); shown as available balance
Carry-forward limit	Configurable per org (default: 5 days); excess is forfeited at year-end
Checklist assignment	Onboarding checklists are assigned automatically on employee profile creation
Org chart source of truth	The `managerId` field on the employee record defines the org chart; HR Admin owns it
Profile visibility	All employees can view public profiles of others in the same org; personal fields (salary, emergency contact) are HR Admin only

HRM
├── Dashboard               Leave balance summary + pending actions
├── Employees               Full employee directory + search
│   └── [Employee]          Profile detail — info, leave history, onboarding
├── My Leave                My leave balance, requests, history
│   └── New Request         Leave request form
├── Team Leave              Manager: pending approvals + team calendar
├── Org Chart               Visual hierarchy tree
└── Onboarding              My checklist (employee) / All checklists (HR Admin)

Screen: Employee profile

Element	Behaviour
Header	Photo, name, title, department, status badge (Active/On Leave/New)
Info tab	Job details, contact, start date, manager link
Leave tab	Balance per type, leave history table
Onboarding tab	Progress bar, task list with completion status
Edit button	Visible only to self (for personal fields) or HR Admin (all fields)

6. Mockups

Screen A — Employee Directory

hrm.venizia.ai · Employees

HRM

🏠 Dashboard

👥 Employees

🌴 My Leave

📅 Team Leave

🌳 Org Chart

✅ Onboarding

	Name	Title	Department	Manager	Status
JD	Jane Doe	HR Manager	Human Resources	CEO	Active	View
BJ	Bob Jones	Senior Engineer	Engineering	Alice Smith	On Leave	View
CL	Carol Lee	Finance Analyst	Finance	CFO	Active	View
MK	Mike Kim	Product Designer	Product	CPO	New	View

Screen A — Employee directory: avatar · name · title · department · manager · status badge

Screen B — Leave Request Form

hrm.venizia.ai · My Leave · New Request

HRM

🏠 Dashboard

👥 Employees

🌴 My Leave

Annual Leave

8.5

days remaining

Sick Leave

days remaining

Unpaid

∞

no limit

🌴 Annual🤒 Sick⏸ Unpaid

Mar 24, 2025

Mar 26, 2025

= 3 working days · Balance after approval: 5.5 days

Family trip — booked in advance

Will be sent to Alice Smith for approval

CancelSubmit Request

Screen B — Leave Request: balance cards · type selector · date range · working days calc · manager shown

Screen C — Team Leave Calendar (Manager)

hrm.venizia.ai · Team Leave — March 2025

HRM

🏠 Dashboard

👥 Employees

🌴 My Leave

📅 Team Leave

Mon 24

Tue 25

Wed 26

Thu 27

Fri 28

Jane D.

🌴 Annual

Bob J.

🤒 Sick (P)

Carol L.

Mike K.

🌴 Annual

Annual (Approved)

Sick (Pending)

Screen C — Team calendar: per-person rows · color-coded leave types · dashed = pending · week view

Screen D — Onboarding Checklist

hrm.venizia.ai · Onboarding — Mike Kim

HRM

🏠 Dashboard

👥 Employees

✅ Onboarding

33% complete

Week 1

✅

Set up laptop and tools

Completed Mar 17 by Mike Kim

✅

Read Employee Handbook

Completed Mar 18 by Mike Kim · View doc

⬜

Meet with your manager

Due Mar 21 · Schedule a 1:1 with Alice Smith

Mark Done

Week 2

⬜

Complete design system training

Due Mar 28 · Figma training module

Mark Done

⬜

Shadow a product review session

Due Mar 28 · Coordinate with CPO

Mark Done

Screen D — Onboarding checklist: progress bar · tasks by week · completed/pending states · Mark Done

7. Permissions (RBAC)

Permission	Resource	Action	Who has it by default
View own profile	`employees`	`read:self`	All authenticated users
View other profiles (public fields)	`employees`	`read:public`	All authenticated users
Edit own personal fields	`employees`	`write:self`	All authenticated users
Edit any employee (all fields)	`employees`	`write`	HR Admin, Admin
Submit leave request	`leave_requests`	`create`	All authenticated users
Approve/reject leave (direct reports)	`leave_requests`	`approve`	Manager, HR Admin, Admin
View all leave (org-wide)	`leave_requests`	`read:all`	HR Admin, Admin
Manage onboarding templates	`onboarding_templates`	`manage`	HR Admin, Admin
View all onboarding checklists	`onboarding_checklists`	`read:all`	Manager, HR Admin, Admin
Edit org structure (reporting lines)	`employees`	`write:structure`	HR Admin, Admin

8. Data Model

organizations
    │
    ├── employees (orgId, userId, jobTitle, departmentId, managerId, startDate, status)
    │       │
    │       └── leave_balances (employeeId, leaveType, totalDays, usedDays, carryForward)
    │
    ├── leave_requests (orgId, employeeId, leaveType, startDate, endDate, workingDays, status)
    │
    ├── departments (orgId, name, parentDepartmentId?)
    │
    └── onboarding_templates (orgId, name, roleTag)
            │
            └── onboarding_template_tasks (templateId, title, description, weekNumber, linkUrl?)
                        │
                        └── onboarding_checklists (employeeId, templateId)
                                    │
                                    └── checklist_items (checklistId, taskId, completedAt?, completedBy?)

Table: `employees`

Column	Type	Notes
`id`	uuid	Primary key
`orgId`	uuid	Organization scope
`userId`	uuid	FK to Shell user account
`jobTitle`	text	e.g. "Product Designer"
`departmentId`	uuid	FK to departments
`managerId`	uuid?	FK to another employee (`null` = top of org)
`startDate`	date	Employment start date
`status`	enum	`active`, `on_leave`, `inactive`
`phone`	text?	Work phone
`emergencyContact`	jsonb?	HR Admin visible only

Table: `leave_requests`

Column	Type	Notes
`id`	uuid	Primary key
`orgId`	uuid	Organization scope
`employeeId`	uuid	FK to employees
`leaveType`	enum	`annual`, `sick`, `unpaid`
`startDate`	date	—
`endDate`	date	—
`workingDays`	int	Computed on submission
`status`	enum	`pending`, `approved`, `rejected`, `cancelled`
`note`	text?	Employee note
`rejectionReason`	text?	Manager's comment on rejection
`approvedBy`	uuid?	Manager who acted
`decidedAt`	timestamp?	—

Table: `leave_balances`

Column	Type	Notes
`id`	uuid	Primary key
`employeeId`	uuid	FK to employees
`leaveType`	enum	`annual`, `sick`
`totalDays`	decimal	Entitlement for the year
`usedDays`	decimal	Approved leave taken this year
`carryForward`	decimal	Carried from previous year

9. API Endpoints

Employees

GET /api/employees — list all employees in the org

Query	Type	Default
`q`	string?	—
`departmentId`	uuid?	—
`status`	string?	—

POST /api/employees — create an employee profile

Requires: employees:write
Body: { userId, jobTitle, departmentId, managerId?, startDate }
Automatically assigns onboarding checklist if a matching template exists

GET /api/employees/:id — get employee profile with balances

PUT /api/employees/:id — update employee (HR Admin: all fields; self: personal fields only)

GET /api/org-chart — return the full org tree from root

Leave

GET /api/leave-requests — list leave requests

Query	Notes
`employeeId`	Filter by employee (own or direct reports)
`status`	`pending`, `approved`, etc.
`from` / `to`	Date range for calendar view

POST /api/leave-requests — submit a new leave request

Body: { leaveType, startDate, endDate, note? }
Validates balance; sets status pending; notifies manager

POST /api/leave-requests/:id/approve — approve a request

Requires: leave_requests:approve; must be the employee's manager
Deducts from leave_balances

POST /api/leave-requests/:id/reject — reject a request

Body: { reason: string }

DELETE /api/leave-requests/:id — cancel a pending request

Employee can cancel their own pending requests only

Onboarding

GET /api/onboarding/checklists/:employeeId — get checklist with item status

POST /api/onboarding/checklists/:employeeId/items/:itemId/complete — mark task done

GET /api/onboarding/templates — list templates (admin)

POST /api/onboarding/templates — create a template (admin)

10. Error Responses

json

{
  "error": {
    "code": "INSUFFICIENT_LEAVE_BALANCE",
    "message": "Requested 5 days but only 3.5 annual leave days remain",
    "status": 422
  }
}

Code	Status	When
`INSUFFICIENT_LEAVE_BALANCE`	422	Annual leave request exceeds available balance
`LEAVE_OVERLAP`	409	Dates overlap with an existing approved request
`NOT_YOUR_REPORT`	403	Approve/reject attempted on non-direct-report
`CANNOT_CANCEL_STARTED`	409	Cancel attempted on leave that has already begun
`FORBIDDEN`	403	Missing required permission
`NOT_FOUND`	404	Employee or request not found in this org

11. Non-Functional Requirements

Requirement	Target
Directory search response	< 300 ms for orgs up to 10,000 employees
Org chart rendering	Handles up to 500 nodes without pagination
Leave calendar	< 500 ms to load month view for a team of 50
Working-day calculation	Correctly handles public holiday calendars per country
Availability	99.9% monthly uptime
Audit trail	All leave approvals/rejections are recorded with actor, timestamp, and reason

12. Out of Scope (v1)

Payroll and salary management
Performance reviews and goal tracking
Recruitment and job posting
Time tracking and attendance
Benefits and insurance enrollment
Multi-country public holiday calendars (v1 uses a single configurable calendar per org)
Employee self-service contract or document signing

13. Open Questions

#	Question	Owner	Status
1	Should leave approval support skip-level escalation if manager is on leave?	Product	Open
2	Do we need a half-day leave option?	Product	Open
3	Should onboarding task completion trigger any notifications?	Product	Open
4	How are public holidays configured — per country, per org, or both?	Engineering	Open
5	Should employees be able to request retroactive sick leave?	Product	Open
6	Is an org chart export (PNG / PDF) needed at launch?	Product	Open

HRM developer guide — implementation walkthrough
Drive spec — file storage for employee documents
Document spec — policy documents used in onboarding

HRM — Product Specification ​

1. Overview ​

What is HRM? ​

Why it exists ​

Who is it for? ​

2. Goals & Non-Goals ​

Goals ✅ ​

Non-Goals ❌ ​

3. User Stories ​

3.1 View and edit employee profile ​

3.2 Submit a leave request ​

3.3 Approve or reject a leave request (manager) ​

3.4 Complete onboarding checklist (new hire) ​

3.5 View the org chart ​

3.6 View team leave calendar ​

4. Business Rules ​

5. Screens & Navigation ​

Screen: Employee profile ​

6. Mockups ​

Screen A — Employee Directory ​

Screen B — Leave Request Form ​

Screen C — Team Leave Calendar (Manager) ​

Screen D — Onboarding Checklist ​

7. Permissions (RBAC) ​

8. Data Model ​

Table: employees ​

Table: leave_requests ​

Table: leave_balances ​

9. API Endpoints ​

Employees ​

Leave ​

Onboarding ​

10. Error Responses ​

11. Non-Functional Requirements ​

12. Out of Scope (v1) ​

13. Open Questions ​

HRM — Product Specification

1. Overview

What is HRM?

Why it exists

Who is it for?

2. Goals & Non-Goals

Goals ✅

Non-Goals ❌

3. User Stories

3.1 View and edit employee profile

3.2 Submit a leave request

3.3 Approve or reject a leave request (manager)

3.4 Complete onboarding checklist (new hire)

3.5 View the org chart

3.6 View team leave calendar

4. Business Rules

5. Screens & Navigation

Screen: Employee profile

6. Mockups

Screen A — Employee Directory

Screen B — Leave Request Form

Screen C — Team Leave Calendar (Manager)

Screen D — Onboarding Checklist

7. Permissions (RBAC)

8. Data Model

Table: `employees`

Table: `leave_requests`

Table: `leave_balances`

9. API Endpoints

Employees

Leave

Onboarding

10. Error Responses

11. Non-Functional Requirements

12. Out of Scope (v1)

13. Open Questions