# NADDC Performance Management System (PMS) — Implementation Plan

## Overview

Build a production-ready Performance Management System for the National Automotive Design and Development Council (NADDC) using **Laravel 13 + Inertia.js + Vue 3 + Tailwind CSS 4**. The system will automate goal-setting, KPI tracking, 360-degree appraisals, performance dashboards, and continuous feedback.

---

## User Review Required

> [!IMPORTANT]
> **Database**: The `.env` is configured for MySQL (`pms` database). Please confirm the database is created and accessible before we proceed.

> [!IMPORTANT]
> **User Roles**: The plan implements 5 roles: `admin`, `director`, `department_head`, `supervisor`, `staff`. Please confirm these match your organizational structure.

> [!WARNING]
> **Inertia.js**: The fresh Laravel install does NOT include Inertia or Vue. We will install `inertiajs/inertia-laravel`, `@inertiajs/vue3`, and `vue` as part of setup.

> [!IMPORTANT]
> **Appraisal Criteria Values**: Based on your sample data, the scoring scale is:
> - **O (Outstanding)** = 100%
> - **E (Excellent)** = 90%
> - **VG (Very Good)** = 80%
> - **G (Good)** = 70%
> - **F (Fair)** = 60%
> - **P (Poor)** = 50%
>
> Please confirm these are correct.

---

## Proposed Changes

### Phase 1: Foundation & Authentication

#### A. Package Installation

Install required packages:
- **Backend**: `inertiajs/inertia-laravel`, `tightenco/ziggy`, `spatie/laravel-permission`
- **Frontend**: `vue@3`, `@inertiajs/vue3`, `@vitejs/plugin-vue`, `chart.js`, `vue-chartjs`, `@heroicons/vue`

---

#### B. Database Schema (Migrations)

##### [NEW] Extend Users Table
Adds fields: `surname`, `firstname`, `othername`, `ippis_no`, `phone`, `designation`, `staff_number`, `avatar`, `role` (enum), `department_id`, `supervisor_id`, `is_active`

##### [NEW] `departments` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| name | string | |
| code | string | Unique dept code |
| director_id | foreignId → users | nullable |
| head_id | foreignId → users | HOD |
| parent_id | foreignId → departments | nullable, for hierarchy |
| description | text | nullable |
| timestamps | | |

##### [NEW] `appraisal_periods` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| name | string | e.g. "May–Dec 2024" |
| start_date | date | |
| end_date | date | |
| status | enum | draft, active, closed |
| created_by | foreignId → users | |
| timestamps | | |

##### [NEW] `key_result_areas` table (KRA Library)
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| name | string | |
| description | text | nullable |
| department_id | foreignId | nullable (null = org-wide) |
| is_active | boolean | |
| timestamps | | |

##### [NEW] `kpi_library` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| name | string | |
| description | text | nullable |
| unit_of_measurement | string | |
| key_result_area_id | foreignId | nullable |
| department_id | foreignId | nullable |
| is_active | boolean | |
| timestamps | | |

##### [NEW] `appraisals` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| appraisal_period_id | foreignId | |
| employee_id | foreignId → users | |
| supervisor_id | foreignId → users | |
| counter_signing_officer_id | foreignId → users | nullable |
| status | enum | draft, self_assessment, supervisor_review, counter_sign, completed |
| employee_overall_score | decimal(5,2) | nullable |
| supervisor_overall_score | decimal(5,2) | nullable |
| final_score | decimal(5,2) | nullable |
| employee_comment | text | nullable |
| supervisor_comment | text | nullable |
| counter_signing_comment | text | nullable |
| submitted_at | timestamp | nullable |
| reviewed_at | timestamp | nullable |
| completed_at | timestamp | nullable |
| timestamps | | |

##### [NEW] `appraisal_goals` table (Section 4 from sample)
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| appraisal_id | foreignId | |
| key_result_area_id | foreignId | nullable |
| kra_weight | decimal(5,2) | Weight of the KRA |
| objective | text | |
| objective_weight | decimal(5,2) | |
| graded_weight | decimal(5,2) | nullable |
| kpi | string | |
| target_set | string | |
| unit_of_measurement | string | |
| criteria_outstanding | decimal(5,2) | 100% |
| criteria_excellent | decimal(5,2) | 90% |
| criteria_very_good | decimal(5,2) | 80% |
| criteria_good | decimal(5,2) | 70% |
| criteria_fair | decimal(5,2) | 60% |
| criteria_poor | decimal(5,2) | 50% |
| achievement | text | nullable |
| self_rating | enum | O,E,VG,G,F,P — nullable |
| supervisor_rating | enum | O,E,VG,G,F,P — nullable |
| raw_score | decimal(5,2) | nullable |
| weighted_raw_score | decimal(5,2) | nullable |
| sort_order | integer | |
| timestamps | | |

##### [NEW] `feedback` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| from_user_id | foreignId | |
| to_user_id | foreignId | |
| appraisal_id | foreignId | nullable |
| type | enum | praise, constructive, suggestion |
| content | text | |
| is_anonymous | boolean | default false |
| timestamps | | |

##### [NEW] `development_plans` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| employee_id | foreignId | |
| appraisal_id | foreignId | nullable |
| title | string | |
| description | text | |
| type | enum | training, mentoring, course, certification |
| status | enum | planned, in_progress, completed |
| start_date | date | nullable |
| target_date | date | nullable |
| completed_date | date | nullable |
| timestamps | | |

##### [NEW] `notifications_log` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| user_id | foreignId | |
| type | string | |
| title | string | |
| message | text | |
| data | json | nullable |
| read_at | timestamp | nullable |
| timestamps | | |

##### [NEW] `activity_logs` table
| Column | Type | Notes |
|--------|------|-------|
| id | bigint | PK |
| user_id | foreignId | |
| action | string | |
| model_type | string | |
| model_id | bigint | |
| changes | json | nullable |
| ip_address | string | nullable |
| timestamps | | |

---

#### C. Authentication System

##### [MODIFY] [User.php](file:///c:/Users/Taiwo/Documents/GitHub/pms/app/Models/User.php)
- Extend with PMS-specific fields (surname, firstname, othername, ippis_no, etc.)
- Add relationships: `department()`, `supervisor()`, `subordinates()`, `appraisals()`, `goals()`
- Add role helpers: `isAdmin()`, `isDirector()`, `isDepartmentHead()`, `isSupervisor()`, `isStaff()`
- Add accessor for `full_name`

##### [NEW] Auth Controllers
- `LoginController` — Inertia-based login/logout
- `ProfileController` — View/update profile

##### [NEW] Middleware
- `RoleMiddleware` — Check user role access
- `HandleInertiaRequests` — Share auth data, notifications, flash messages

---

### Phase 2: Core PMS Modules

#### D. Department Management

##### [NEW] `app/Models/Department.php`
- Relationships: `director()`, `head()`, `staff()`, `parent()`, `children()`
- Scopes: `active()`, `withStaffCount()`

##### [NEW] `app/Http/Controllers/DepartmentController.php`
- CRUD operations for departments
- Staff assignment
- Hierarchy management

---

#### E. Appraisal Period Management

##### [NEW] `app/Models/AppraisalPeriod.php`
- Relationships: `appraisals()`, `creator()`
- Scopes: `active()`, `current()`

##### [NEW] `app/Http/Controllers/AppraisalPeriodController.php`
- Create/edit/activate/close periods
- Dashboard statistics for each period

---

#### F. KPI & KRA Library Management

##### [NEW] `app/Models/KeyResultArea.php`
##### [NEW] `app/Models/KpiLibrary.php`
##### [NEW] `app/Http/Controllers/KraController.php`
##### [NEW] `app/Http/Controllers/KpiLibraryController.php`
- CRUD for KRAs and KPIs
- Import/export capability
- Department-specific and org-wide KPIs

---

#### G. Appraisal System (Core)

##### [NEW] `app/Models/Appraisal.php`
- Relationships: `employee()`, `supervisor()`, `counterSigningOfficer()`, `goals()`, `period()`
- Status workflow management
- Score calculation methods

##### [NEW] `app/Models/AppraisalGoal.php`
- Score calculation: `raw_score = criteria_value`, `weighted_raw_score = raw_score × (objective_weight / 100)`
- Relationship to KRA

##### [NEW] `app/Http/Controllers/AppraisalController.php`
- Full appraisal workflow:
  1. **Goal Setting** (Employee sets goals at start of period)
  2. **Self-Assessment** (Employee rates achievements)
  3. **Supervisor Review** (Supervisor rates and comments)
  4. **Counter-signing** (CSO reviews and finalizes)
  5. **Completion** (Final scores calculated)
- PDF export of appraisal form

##### [NEW] `app/Services/AppraisalService.php`
- Score calculation logic
- Workflow state machine
- Notification triggers

---

#### H. 360-Degree Feedback

##### [NEW] `app/Models/Feedback.php`
##### [NEW] `app/Http/Controllers/FeedbackController.php`
- Peer feedback submission
- Anonymous feedback option
- Feedback history and analytics

---

#### I. Development Plans

##### [NEW] `app/Models/DevelopmentPlan.php`
##### [NEW] `app/Http/Controllers/DevelopmentPlanController.php`
- Create development plans linked to appraisals
- Track training/mentoring progress

---

### Phase 3: Dashboard & Reporting

#### J. Dashboards

##### [NEW] `app/Http/Controllers/DashboardController.php`

**Admin Dashboard:**
- Organization-wide appraisal completion rates
- Department performance comparison charts
- System usage statistics
- Pending actions overview

**Department Head/Supervisor Dashboard:**
- Team appraisal progress
- Department KPI achievement summary
- Pending reviews count
- Team performance distribution

**Employee Dashboard:**
- Current appraisal status
- Goal progress tracking
- Recent feedback
- Development plan status

---

#### K. Reports

##### [NEW] `app/Http/Controllers/ReportController.php`
- Individual Performance Report
- Department Performance Summary
- Appraisal Completion Status Report
- KPI Achievement Report
- Export to PDF/Excel

---

### Phase 4: Vue.js Frontend (Inertia Pages)

#### L. Layout & Shared Components

##### [NEW] `resources/js/Layouts/AuthenticatedLayout.vue`
- Responsive sidebar navigation
- Header with user profile, notifications
- Breadcrumbs
- Dark mode support

##### [NEW] Shared Components (`resources/js/Components/`)
- `DataTable.vue` — Sortable, filterable, paginated table
- `Modal.vue` — Reusable modal dialog
- `StatCard.vue` — Dashboard metric card with icon
- `Chart.vue` — Chart.js wrapper (bar, pie, line, radar)
- `Badge.vue` — Status badges
- `ProgressBar.vue` — Visual progress indicator
- `SearchableSelect.vue` — Dropdown with search
- `DatePicker.vue` — Date range picker
- `FormSection.vue` — Styled form sections
- `AppraisalForm.vue` — The full appraisal form (Sections 1-4 matching sample)
- `ScoreMatrix.vue` — Criteria values display (O/E/VG/G/F/P)

##### Pages Structure:
```
resources/js/Pages/
├── Auth/
│   ├── Login.vue
│   └── ForgotPassword.vue
├── Dashboard/
│   └── Index.vue
├── Departments/
│   ├── Index.vue
│   ├── Show.vue
│   └── Form.vue
├── Staff/
│   ├── Index.vue
│   ├── Show.vue
│   └── Form.vue
├── AppraisalPeriods/
│   ├── Index.vue
│   └── Form.vue
├── KRA/
│   ├── Index.vue
│   └── Form.vue
├── KPILibrary/
│   ├── Index.vue
│   └── Form.vue
├── Appraisals/
│   ├── Index.vue
│   ├── Create.vue          ← Goal setting
│   ├── SelfAssessment.vue  ← Employee self-rating
│   ├── SupervisorReview.vue
│   ├── CounterSign.vue
│   ├── Show.vue            ← Read-only view
│   └── Print.vue           ← Print-friendly layout
├── Feedback/
│   ├── Index.vue
│   └── Give.vue
├── DevelopmentPlans/
│   ├── Index.vue
│   └── Form.vue
├── Reports/
│   ├── Index.vue
│   ├── Individual.vue
│   └── Department.vue
└── Profile/
    └── Edit.vue
```

---

### Phase 5: Notifications & Workflow Automation

#### M. Notifications

##### [NEW] `app/Notifications/AppraisalStarted.php`
##### [NEW] `app/Notifications/AppraisalSubmitted.php`
##### [NEW] `app/Notifications/ReviewRequired.php`
##### [NEW] `app/Notifications/AppraisalCompleted.php`
##### [NEW] `app/Notifications/PeriodReminder.php`

---

### Phase 6: Seeder & Sample Data

##### [NEW] `database/seeders/DepartmentSeeder.php`
##### [NEW] `database/seeders/UserSeeder.php`
##### [NEW] `database/seeders/KRASeeder.php`
##### [NEW] `database/seeders/KPILibrarySeeder.php`
##### [NEW] `database/seeders/AppraisalPeriodSeeder.php`
##### [NEW] `database/seeders/SampleAppraisalSeeder.php`

Creates sample data including NADDC departments and a demo appraisal matching the sample form provided.

---

## Implementation Order

| Step | Description | Estimated Effort |
|------|------------|-----------------|
| 1 | Install packages (Inertia, Vue, Spatie) | ~10 min |
| 2 | Database migrations (all tables) | ~30 min |
| 3 | Models + relationships | ~30 min |
| 4 | Auth system (Login, middleware, Inertia setup) | ~30 min |
| 5 | Layout + shared Vue components | ~45 min |
| 6 | Dashboard controller + page | ~30 min |
| 7 | Department management | ~20 min |
| 8 | Staff management | ~20 min |
| 9 | KRA/KPI library | ~20 min |
| 10 | Appraisal period management | ~15 min |
| 11 | **Core appraisal system** (goal-setting, self-assessment, review, counter-sign) | ~60 min |
| 12 | Feedback module | ~20 min |
| 13 | Development plans | ~15 min |
| 14 | Reports & analytics | ~30 min |
| 15 | Seeders + sample data | ~20 min |
| 16 | Testing & polish | ~30 min |

---

## Open Questions

> [!IMPORTANT]
> 1. **NADDC Departments**: Can you provide the list of actual NADDC departments/units to seed? Otherwise I'll create reasonable defaults.
> 2. **Logo/Branding**: Do you have an NADDC logo file? I can use a placeholder or generate one.
> 3. **HRIS/Payroll Integration**: The spec mentions potential integration — should I add API endpoints for future integration, or skip this for now?
> 4. **Email Configuration**: Should the system send real emails (SMTP config needed) or just use in-app notifications for now?
> 5. **Number of KRAs**: How many standard KRAs does NADDC use? The sample shows rows with multiple Key Result Areas per appraisal.

---

## Verification Plan

### Automated Tests
```bash
php artisan test
```
- Feature tests for authentication flow
- Feature tests for appraisal CRUD and workflow state transitions
- Unit tests for score calculation logic

### Manual Verification
1. Run `php artisan migrate:fresh --seed` to confirm all migrations and seeders work
2. Login as different roles (Admin, HOD, Supervisor, Staff) and verify dashboard content
3. Complete a full appraisal cycle: Goal Setting → Self-Assessment → Supervisor Review → Counter-Sign → Completed
4. Verify score calculations match the formula from the sample form
5. Check responsive design on different viewport sizes
6. Browser test the full workflow using the browser subagent
