# MPC Employee Engagement Survey System

A comprehensive employee engagement survey platform built for **Musandam Power Company** by **Talent Arabia**.

## 🎯 Overview

This Laravel 11 application provides a complete solution for conducting employee engagement surveys with:

- **Two-Role System**: Super Admin (Talent Arabia) and Company Admin (MPC HR)
- **Fully Anonymous Surveys**: No tracking between invitations and responses
- **10 Engagement Dimensions**: Based on Gallup Q12 and Aon Hewitt frameworks
- **Comprehensive Analytics**: Engagement index, heatmaps, demographic breakdowns
- **PDF/Excel Reports**: Executive summaries and detailed reports

## 🏗️ Architecture

### Database Schema

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     users       │     │   categories    │     │  question_bank  │
│─────────────────│     │─────────────────│     │─────────────────│
│ id              │     │ id              │◄────│ id              │
│ name            │     │ name            │     │ category_id     │
│ email           │     │ slug            │     │ question_text   │
│ password        │     │ description     │     │ question_type   │
│ role            │     │ icon            │     │ source          │
└─────────────────┘     │ color           │     └─────────────────┘
        │               └─────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    surveys      │     │   questions     │     │demographics_opts│
│─────────────────│     │─────────────────│     │─────────────────│
│ id              │◄────│ id              │     │ id              │
│ title           │     │ survey_id       │     │ type            │
│ status          │     │ category_id     │     │ label           │
│ created_by (FK) │     │ question_text   │     └─────────────────┘
└─────────────────┘     │ question_type   │
        │               └─────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│survey_invitations│    │ response_answers│
│─────────────────│     │─────────────────│
│ id              │     │ id              │
│ survey_id       │     │ response_id     │
│ email           │     │ question_id     │
│ token           │     │ answer_value    │
│ status          │     │ answer_text     │
└─────────────────┘     └─────────────────┘
        │                       ▲
        │ (NO LINK)             │
        │                       │
        │               ┌───────┴───────┐
        │               │survey_responses│ ◄── ANONYMOUS
        │               │───────────────│     (Random UUID token,
        └──────────────►│ id            │      NO user/email/IP)
                        │ survey_id     │
                        │ response_token│
                        │ department    │ ◄── Optional demographics
                        │ tenure        │
                        │ job_level     │
                        └───────────────┘
```

### Anonymity Design

The system is designed with anonymity as a core principle:

1. **Invitation tokens** are used only to track who was invited and response rates
2. **Response tokens** are completely random UUIDs with NO link to invitations
3. **Demographics** are optional and only displayed when n ≥ 5
4. **No IP addresses** or identifying information is stored with responses

## 🎨 Design System

### Colors

| Purpose | Hex | Usage |
|---------|-----|-------|
| Primary | `#a6cf45` | CTAs, highlights, brand |
| Primary Dark | `#8fb83a` | Hover states |
| Secondary | `#2c3e50` | Headers, navigation |
| Success | `#27ae60` | Scores 80-100% |
| Warning | `#f1c40f` | Scores 60-69% |
| Danger | `#e74c3c` | Scores <50% |

### Score Interpretation

| Score Range | Label | Color | Action |
|-------------|-------|-------|--------|
| 80-100% | Strong | Green | Maintain & celebrate |
| 70-79% | Healthy | Lime | Monitor & sustain |
| 60-69% | Moderate | Yellow | Focus area |
| 50-59% | Needs Work | Orange | Priority improvement |
| <50% | Critical | Red | Urgent action required |

## 📊 10 Engagement Categories

1. 👁️ **Leadership & Vision** - Confidence in leadership decisions
2. 💬 **Communication & Collaboration** - Information flow and teamwork
3. 🏆 **Recognition & Reward** - Appreciation and compensation
4. 📈 **Career Growth & Development** - Learning and advancement
5. ⚖️ **Well-being & Work-Life Balance** - Health and flexibility
6. ✅ **Job Satisfaction & Role Clarity** - Role understanding
7. ❤️ **Engagement & Commitment** - Emotional connection
8. 🤝 **Organizational Culture & Inclusion** - Belonging and values
9. 🛠️ **Enablement & Resources** - Tools and support
10. 🦺 **Safety Climate** - Workplace safety

## 🚀 Installation

### Requirements

- PHP 8.2+
- MySQL 8.0+
- Composer 2.x
- Node.js 18+

### Setup

```bash
# 1. Extract the archive
unzip mpc-survey-complete.zip
cd mpc-survey

# 2. Install PHP dependencies
composer install

# 3. Install NPM dependencies  
npm install

# 4. Copy environment file
cp .env.example .env

# 5. Generate application key
php artisan key:generate

# 6. Configure database in .env
# Edit .env and set your database credentials:
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=mpc_survey
# DB_USERNAME=your_username
# DB_PASSWORD=your_password

# 7. Create the database
mysql -u root -p -e "CREATE DATABASE mpc_survey CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 8. Run migrations and seeders
php artisan migrate --seed

# 9. Build frontend assets
npm run build

# 10. Set storage permissions (Linux)
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# 11. Start development server (for testing)
php artisan serve
```

### Production Deployment (Hostinger/cPanel)

1. Upload all files to your `public_html` directory
2. Point document root to the `public` folder
3. Set up database and update `.env`
4. Run `php artisan migrate --seed` via SSH or cPanel Terminal
5. Set folder permissions: `storage` and `bootstrap/cache` need to be writable

### Default Users

| Role | Email | Password |
|------|-------|----------|
| Super Admin | admin@talentarabia.com | password123 |
| Company Admin | hr@mpc.om | mpc2025 |

⚠️ **Change these passwords in production!**

## 📁 Project Structure

```
mpc-survey/
├── app/
│   ├── Http/Controllers/
│   │   ├── Admin/           # Super Admin controllers
│   │   ├── Company/         # Company Admin controllers
│   │   ├── Survey/          # Public survey taking
│   │   └── Auth/            # Authentication
│   ├── Models/              # Eloquent models
│   └── Services/            # Business logic (Analytics)
├── database/
│   ├── migrations/          # Database schema
│   └── seeders/             # Initial data
├── resources/
│   ├── views/
│   │   ├── layouts/         # Base layouts
│   │   ├── admin/           # Super Admin views
│   │   ├── company/         # Company Admin dashboard
│   │   ├── survey/          # Survey taking views
│   │   └── auth/            # Login
│   └── css/                 # Tailwind CSS
└── routes/
    └── web.php              # All routes
```

## 🔒 Security Features

- **CSRF Protection** on all forms
- **Password Hashing** with bcrypt
- **Role-Based Access Control** via Gates
- **Anonymous Response Storage** - no link between invitation and response
- **Minimum Threshold (n=5)** for demographic data display
- **Session-Based Survey Progress** - not stored in URLs

## 📱 Mobile-First Survey

The survey taking interface is designed mobile-first with:

- Large touch-friendly buttons
- Progress indicator
- Auto-save to localStorage
- Category-by-category navigation
- Responsive Likert scale options

## 📈 Analytics Features

- **Engagement Index** - % of engaged employees (Gallup methodology)
- **Category Scores** - Favorability by dimension
- **Heatmap** - Department × Category matrix
- **Question Details** - Item-level analysis with distribution
- **Demographics Breakdown** - Filtered by dept/tenure/level
- **Open Response Themes** - Comment analysis

## 📄 Report Types

| Report | Format | Pages | Content |
|--------|--------|-------|---------|
| Executive Summary | PDF | 2-3 | Key metrics, strengths, improvements |
| Detailed Report | PDF | 10-15 | Full analysis with recommendations |
| Raw Data Export | Excel | - | Anonymized response data |

## 🔧 Customization

### Adding Categories

Edit `database/seeders/CategorySeeder.php` and re-run:

```bash
php artisan db:seed --class=CategorySeeder
```

### Adding Questions

Edit `database/seeders/QuestionBankSeeder.php` or use the admin interface.

### Changing Colors

Edit `tailwind.config.js` and `resources/css/app.css`, then rebuild:

```bash
npm run build
```

## 📝 License

Proprietary - Talent Arabia © 2025

---

Built with ❤️ by **Talent Arabia** for **Musandam Power Company**
