KPI Matrix Module — Documentation Package

Module: KPI Matrix (Employee Performance Management) Target System: ERPat ERP System (CodeIgniter 3 / PHP 8.2+) Documentation Date: February 2026 · Last Revised: June 2026 Status: Implemented — documentation reconciled to code (see fidelity notes in doc 02 Appendix C) Branch: ERPAT-2345 (migration 20260604185300_create_kpi_matrix_tables.php)

???? End-user guide (interactive HTML): a multi-page, browser-ready user guide now lives alongside these developer docs — open index.html in this folder. It covers every screen, workflow, legend, SOP, terminology and the salary-progression standards from the end user's perspective (the files below remain the deeper developer/design reference).

Purpose

This documentation package describes the KPI Matrix module — a performance management system that transforms ERPat's existing operational data into structured, measurable Key Performance Indicators (KPIs) for employee evaluation, salary progression, and organizational insight. The module is implemented; these documents are maintained to match the shipped code (config, calculation engine, models, controller, views, and migration).

The KPI Matrix:

1. Leverages existing data — attendance, tasks, projects, tickets, timesheets, disciplinary, leave, certifications
2. Provides a calculation engine — 29 metrics across 8 categories, automated scoring, normalization, review cycles
3. Integrates with salary progression — KPI scores generate (advisory) salary-grade step-advancement recommendations
4. Provides actionable dashboards — per-employee, per-department, per-organization views

Best-KPI grounding: the metric set follows current performance-management best practice — a balance of leading and lagging indicators across quantity, quality, efficiency, reliability/compliance, development, and wellbeing dimensions, with SMART target guidance and role-based weighting. See 02_KPI_CATEGORIES_AND_METRICS.md.

Document Index

Earlier drafts referenced separate 07_PERMISSIONS_AND_ACCESS.md, 08_IMPLEMENTATION_ROADMAP.md, and AI_IMPLEMENTATION_GUIDE.md files. Those were never created; permissions, roadmap, and implementation guidance are covered inside docs 00, 04, 05, and 06 and the in-code config. The index above reflects the actual files in this package.

Architecture Summary

┌─────────────────────────────────────────────────────────────┐
│                    KPI MATRIX MODULE                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Data Layer   │  │ Calculation  │  │ Presentation │      │
│  │  (Existing)   │→│   Engine     │→│   Layer       │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                              │
│  Attendance         Aggregation       Employee Card          │
│  Tasks/Projects     Scoring           Department Matrix      │
│  Tickets            Weighting         Review Dashboard       │
│  Timesheets         Normalization     Analytics/Reports      │
│  Discipline         Target Compare    Timeline Feed          │
│  Leaves/Schedule                                             │
│  Certifications              ┌──────────────┐               │
│  Skillsets                   │   Salary      │               │
│  Payslips                    │   Integration │               │
│                              └──────────────┘               │
│                              Grade Step ↑                    │
│                              Increase Rec.                   │
│                              History Link                    │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  Database (9 tables): kpi_templates, kpi_template_metrics,    │
│  kpi_review_cycles, kpi_employee_assignments,                │
│  kpi_metric_scores, kpi_composite_results,                   │
│  kpi_manual_entries, kpi_score_history,                      │
│  kpi_salary_recommendations                                  │
└─────────────────────────────────────────────────────────────┘

Implemented Code Artifacts

Key Data Sources Identified

Relationship to Existing Modules

Payroll Module ←── salary_history, salary_grades
       ↑
  KPI Matrix ←── attendance, tasks, tickets, timesheets,
       ↓            discipline, leaves, certs, skillsets
Salary Progression ←── KPI scores → grade step advancement

The KPI Matrix sits between operational data collection (left) and compensation decisions (right), transforming raw activity data into structured performance metrics that drive salary progression.

How to Use This Documentation

1. Start with 00_BACKGROUND.md to understand the business case
2. Review 01_DATA_SOURCES_INVENTORY.md for available data points
3. Study 02_KPI_CATEGORIES_AND_METRICS.md for proposed metrics and formulas
4. Check 03_DATABASE_SCHEMA.md for new table designs
5. Read 04_SALARY_INTEGRATION.md for the critical salary link
6. Dig into 05_CALCULATION_ENGINE.md for the computation, scoring, and scheduling logic, then 06_UI_AND_DASHBOARDS.md for the interface

Roadmap and implementation-guidance content (once planned as separate files that were never created — see the note under the Document Index above) now lives inside docs 00, 04, 05, and 06 and the in-code config under modules/KpiMatrix/config/.

Related Documentation

• temp/payroll-module-documentation/ — Payroll module architecture (reference pattern)
• .github/copilot-instructions.md — ERPat system architecture and coding standards
• application/config/system_logs.php — System logging configuration
• application/helpers/payroll_helper.php — Salary computation helpers