KPI Management Module

Overview

The KPI module enables structured performance evaluation of employees through configurable templates, time-boxed cycles, and a multi-step review workflow.

Scope

Feature	Status
KPI Templates CRUD	✅ Implemented
KPI Template Import	✅ Implemented
KPI Cycles CRUD	✅ Implemented
Department-scoped Publishing	✅ Implemented
Self-Assessment Flow	✅ Implemented
Manager Review Flow	✅ Implemented
HR Review Flow	✅ Implemented
Accept / Dispute	✅ Implemented
Force-Close	✅ Implemented
Evidence Attachments	✅ Implemented
Reviewer Assignment	✅ Implemented
Finance CSV Export	✅ Implemented

Data Model

Core Tables

kpi_templates (id, name, ...)
├── has many → kpi_template_items (id, template_id, name, weight)

kpi_cycles (id, title, start_date, end_date, ...)
├── has many → kpi_cycle_departments (cycle_id, department_id, template_id, is_published)

kpi_evaluations (id, cycle_id, employee_id, reviewer_id, status, overall_score, ...)
├── has many → kpi_evaluation_details (id, evaluation_id, template_item_id, self_score, self_comment, manager_score, manager_comment)
├── has many → attachments (polymorphic evidence files)

Relationships

Relationship	Description
Template → Items	One template has many weighted items (must sum to 100)
Cycle → Departments	A cycle assigns templates to specific departments
Cycle → Evaluations	Publishing generates one evaluation per eligible employee
Evaluation → Details	One detail row per template item per evaluation
Evaluation → Reviewer	Employee assigned to perform manager review

Workflow Engine

Status Transitions

┌─────────────────┐
│ Self-Assessment  │ ← Employee submits self-scores
└────────┬────────┘
         ▼
┌─────────────────┐
│ Manager Review   │ ← Reviewer submits manager scores
└────────┬────────┘
         ▼
┌─────────────────┐
│   HR Review      │ ← HR submits overall review
└────────┬────────┘
         ▼
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐
│Accepted│ │ Disputed │ ← Employee responds
└───┬────┘ └────┬─────┘
    ▼           ▼
┌─────────────────┐
│   Completed      │ ← HR force-closes
└─────────────────┘

Transition Guards

From	To	Who Can Trigger
Self-Assessment	Manager Review	Employee (submit self-assessment)
Manager Review	HR Review	Reviewer (submit manager review)
HR Review	Accepted	Employee (accept)
HR Review	Disputed	Employee (dispute with reason)
Accepted / Disputed	Completed	HR / Admin (force-close)

Invalid transitions are rejected by the backend service layer.

Scoring System

Item-Level Scoring

Each KPI item is scored on a 1–5 scale:

Score	Label
1	Poor
2	Below Average
3	Average
4	Good
5	Excellent

Overall Score Calculation

Overall % = Σ (Manager Score_i / 5 × Weight_i)

Example: 3 items with weights 40/30/30 and manager scores 4/3/5:

Overall = (4/5 × 40) + (3/5 × 30) + (5/5 × 30) = 32 + 18 + 30 = 80%

Performance Thresholds

Range	Classification	Action
< 50%	PIP	Performance Improvement Plan recommended
50–89%	Standard	Normal performance
≥ 90%	HiPo	High Potential — consider fast-track confirmation

Architecture

Backend Components

Component	Path	Purpose
KpiTemplate Model	app/Models/KpiTemplate.php	Template with items
KpiCycle Model	app/Models/KpiCycle.php	Cycle with department assignments
KpiEvaluation Model	app/Models/KpiEvaluation.php	Individual evaluation records
KpiCycleService	app/Services/KpiCycleService.php	Cycle publishing logic
KpiEvaluationService	app/Services/KpiEvaluationService.php	Workflow transitions, scoring
KpiTemplateImportService	app/Services/KpiTemplateImportService.php	CSV import

Frontend Components

Component	Path	Purpose
Templates Page	app/dashboard/kpi-templates/page.tsx	Template list & management
Cycles Page	app/dashboard/kpi-cycles/page.tsx	Cycle list
Cycle Detail	app/dashboard/kpi-cycles/[id]/page.tsx	Dept assignment & publishing
Evaluations Page	app/dashboard/kpi-evaluations/page.tsx	Evaluation list by role

API Endpoints

Templates

Method	Endpoint	Description
GET	/api/kpi-templates	List templates
POST	/api/kpi-templates	Create template with items
PUT	/api/kpi-templates/{id}	Update template
DELETE	/api/kpi-templates/{id}	Delete template
POST	/api/kpi-templates/import	Import templates from CSV

Cycles

Method	Endpoint	Description
GET	/api/kpi-cycles	List cycles
POST	/api/kpi-cycles	Create cycle
PUT	/api/kpi-cycles/{id}	Update cycle
DELETE	/api/kpi-cycles/{id}	Delete cycle
POST	/api/kpi-cycles/{id}/publish	Publish (generate evaluations)
GET	/api/kpi-cycles/{id}/export	Finance CSV export

Evaluations

Method	Endpoint	Description
GET	/api/kpi-evaluations	List evaluations
GET	/api/kpi-evaluations/{id}	Get evaluation detail
POST	/api/kpi-evaluations/{id}/self-assess	Submit self-assessment
POST	/api/kpi-evaluations/{id}/review	Submit manager review
POST	/api/kpi-evaluations/{id}/hr-review	Submit HR review
POST	/api/kpi-evaluations/{id}/accept	Employee accepts
POST	/api/kpi-evaluations/{id}/dispute	Employee disputes
POST	/api/kpi-evaluations/{id}/complete	HR force-closes
PUT	/api/kpi-evaluations/{id}/assign-reviewer	Assign reviewer

2026-03 UX Updates

• KPI evaluation detail now shows live runtime final scoring for both employee and reviewer while filling ratings.
• Live scoring includes score, percentage, and rated-item progress.
• HR/dashboard action label was updated to Confirm Final Decision (positive wording, blue action).
• KPI evidence now supports Preview (images/PDF) in addition to download.