# MQT HRMS Internal Developer Handover

Last updated: 2026-03-17  
Audience: incoming developers, technical leads, DevOps support

## 1) System Overview
This repository is a Laravel 11 based HRMS platform that combines:
- Employee master and profile management
- Domestic and overseas onboarding
- Attendance, leave, and biometric integration
- Resignation and clearance workflow
- Tickets/helpdesk operations
- Compliance, policy, and document acknowledgement
- Operational tools (network/chipset/passport-visa)
- Notifications, bulk mail, and scheduled automations

Core framework and packages are defined in `composer.json` and include:
- `laravel/framework` 11.x
- `laravel/sanctum` (API auth)
- `spatie/laravel-permission` (RBAC/permissions)
- `spatie/laravel-backup` (backup jobs)
- `predis/predis` (Redis/caching/queue support)

## 2) High-Level Architecture
- Backend: Laravel MVC (`app/Http/Controllers`, `app/Models`, `app/Services`)
- Frontend: Blade views in `resources/views`, static assets via Vite
- API: `routes/api.php` with Sanctum-protected endpoints
- Scheduler: `routes/console.php` for recurring jobs/commands
- Auth/RBAC: Laravel auth + Spatie role/permission middleware aliases in `bootstrap/app.php`
- Logging:
  - default Laravel logs
  - custom admin activity log channel (`admin_activity`) with JSON formatting

## 3) Key Directories
- `app/Http/Controllers`: business workflows by module
- `app/Models`: Eloquent entities (HR, attendance, tickets, exits, tools)
- `app/Services`: domain logic (attendance approvals/reporting, leave ledger, utilization, biometric processing)
- `app/Jobs`: queue jobs (biometric sync/delete/manual sync, onboarding reminders, bulk email)
- `app/Console/Commands`: import/cron command handlers
- `routes/web.php`: main product surface
- `routes/api.php`: API for auth and selected master/resource data
- `routes/console.php`: scheduler map
- `resources/views`: all module UI templates
- `database/migrations`: schema evolution

## 4) Module Map (What Exists in Code)
### Master Data and Core HR
- Client, Department, Designation, Job Status, Location, Project, Region
- Team, Resource Status, Resource Type, Manager, Lead
- UK Right to Work list
- Holiday list

### Workforce Lifecycle
- Resource Management (active employees)
- Probation tracking and reminder support
- Ex-Resource Management
- Overseas Resource Management
- Ex-Overseas Resource Management
- Passport/Visa records
- Overseas contract extension

### Onboarding
- Onboarding creation and mail trigger
- Onboarding request approval/rejection
- Overseas onboarding requests and approval workflow
- Onboarding status listing

### Identity, Access, and Compliance
- Role management
- Permission management
- User management
- Compliance accept flow (`/compliance/accept`)
- Policy/document center (HR, security, privacy, tools docs)
- Admin activity logging

### Communication and Notifications
- Custom notifications
- Notification inbox/read
- Birthday wish trigger
- Bulk email campaign creation and queue dispatch

### Resignation and Exit
- Employee resignation apply
- HR/manager decision
- Department-level clearance updates
- Exit department configuration from UI
- HR final exit action
- Reminder commands for pending tasks and exit closure

### Attendance, Leave, and Biometric
- Attendance apply/edit/delete/view/my attendance
- Attendance approval queues (domestic, onsite, international, manager)
- Approval queue entries show requestor name + email for quicker verifier validation
- Attendance cancellation flow and preview
- Attendance calendar/events
- Attendance report preview/export and request views
- Leave apply/edit/delete and approval queues
- Leave ledger (employee + HR adjustments)
- Biometric ingest, sync logs, delete logs, retries, manual sync, export

### Support and Tools
- Ticket system (create, assign, auto-assign to least-loaded resolver, transfer/reassign, accept, update, resolve, close, reopen, escalate)
- Department ticket list default order: OPEN -> ASSIGNED -> REOPENED -> IN_PROGRESS -> ESCALATED -> RESOLVED -> CLOSED (with latest updates first within each status)
- Department ticket list top filters: RESOLVED, REOPENED, CLOSED, ESCALATED
- Ticket analytics/reporting view for end-to-end ticket insights, including KPI counts for OPEN/REOPENED/ESCALATED and a status breakdown chart
- Department ticket role mapping
- Network information CRUD
- Chipset CRUD
- Travel portal auto-login
- Utilization dashboards/data/ranking/drilldowns
- Inventory page

## 5) Authentication and Authorization
### Auth entry points
- Web login/logout/password reset in `CustomAuthController`
- API login in `ApiAuthController`

### Authorization model
- Spatie permission middleware aliases configured in `bootstrap/app.php`:
  - `role`
  - `permission`
  - `role_or_permission`
- Custom middleware:
  - `log.admin` (`App\Http\Middleware\LogAdminActivity`)
  - `RoleCheck` exists for role/perms checking paths
- Several controllers also use Laravel 11 controller-level middleware (`HasMiddleware`)

### Policy layer
- `ResignationRequestPolicy` controls visibility/decision/clearance/exit actions.

## 6) Background Jobs and Scheduler
Scheduled tasks are declared in `routes/console.php`:
- Daily onboarding reminders job (`SendOnboardingRemindersJob`) at 10:00 IST
- Weekly backup run/cleanup
- Weekly probation reminder command
- Daily resignation clearance reminders (09:00 IST)
- Daily resignation exit-pending reminders (10:00 IST)
- Daily overseas contract check (11:00 IST)
- Monthly leave credit command (`MonthlyLeaveCredit`)
- Biometric device sync job every minute

Queue jobs in `app/Jobs`:
- `SendBulkEmailJob`
- `SendOnboardingRemindersJob`
- `BiometricSyncJob`
- `BiometricDeviceSyncJob`
- `BiometricDeleteJob`
- `BiometricManualRangeSyncJob`

Operational requirement: run queue workers and scheduler continuously in production.

## 7) Data Model Surface (Main Entities)
Representative model groups:
- Workforce: `ResourceMaster`, `ExResource`, `OverseasMaster`, `ExOverseasResource`, `User`
- Org masters: `Department`, `Designation`, `ManagerName`, `LeadMaster`, `TeamName`, `ProjectName`, `ClientName`
- Onboarding: `Onboarding`, `OnboardingApprovalTemp`, `OverseasOnboarding`, `OverseasProfileUpdateRequest`
- Attendance/Leave: `AttendanceRequest`, `AttendanceLog`, `LeaveRequest`, `LeaveLog`, `Holiday`
- Exit: `ResignationRequest`, `ResignationClearanceTask`, `ResignationAction`
- Tickets: `Ticket`, `TicketUpdate`, `TicketDepartmentRole`
- Tools: `NetworkInformation`, `Chipset`, `RightToWorkList`
- Communication: `CustomNotification`, `EmailBatch`, `EmailBatchRecipient`

## 8) Runtime Dependencies and Config
Key config files:
- `config/permission.php` (Spatie roles/permissions)
- `config/logging.php` (admin activity JSON logs)
- `config/legal.php` (compliance/nda versions and text)
- `config/mail.php` (bulk mail and notification delivery)
- `config/essl.php` (biometric integration settings)
- `config/database.php`, `config/cache.php`, `config/queue.php`

Expected infrastructure:
- Relational DB for Laravel
- Queue backend (commonly Redis/database)
- Cron/supervisor process management
- SMTP setup for mail notifications

## 9) Local Setup (Developer Quick Start)
1. Install dependencies:
   - `composer install`
   - `npm install`
2. Environment:
   - copy `.env` from example and set DB/cache/queue/mail
3. App setup:
   - `php artisan key:generate`
   - `php artisan migrate`
4. Frontend:
   - `npm run dev` (local)
5. Background processes:
   - `php artisan queue:work`
   - `php artisan schedule:work` or OS cron running `php artisan schedule:run`

## 10) Observed Gaps and Risks
- README is still default Laravel; project-specific onboarding was missing (this doc addresses it).
- Test coverage is minimal (`tests/Feature/ExampleTest.php`, `tests/Unit/ExampleTest.php`), so core business flows are not protected by automated regression tests.
- `routes/web.php` is very large; route groups and module files could improve maintainability.
- Multiple modules use cache keys for master lists; cache invalidation consistency must be verified when data changes.
- Mixed legacy and newer authorization patterns are present; standardization would reduce permission drift.

## 11) Recommended Engineering Priorities
1. Add integration tests for:
   - onboarding approve/reject
   - resignation decision/clearance/exit
   - attendance/leave approval flows
2. Split route files by domain (HR core, attendance, tickets, tools).
3. Publish a seed strategy for roles/permissions and baseline master data.
4. Add module-level runbooks (mail issues, biometric sync failures, queue backlog handling).
5. Add API and feature-level documentation for stakeholders and QA.

## 12) New Developer First Week Checklist
1. Run local app and confirm login, dashboard, notifications, and one module from each domain.
2. Verify queue/scheduler jobs are running and logs are generated.
3. Review permissions matrix and role behavior with sample accounts.
4. Walk through hire-to-onboard-to-exit lifecycle in staging data.
5. Add at least one meaningful feature test before starting new feature work.

## 13) Attendance and Approval Updates (2026-03-10)
### Domestic/Onsite Attendance Request Enhancements
- Calendar-based domestic/onsite apply flow supports biometric mode toggle.
- Biometric selection is restricted to a single date request only.
- User can select IN/OUT punches from same-day biometric logs.
- Selected biometric values are persisted in request `form_data` and shown in user/approval views.

## 14) Master Data Archive Update (2026-03-17)
### What Changed
- Master data modules for Client, Department, Designation, Job Status, Project, Region, Resource Status, Resource Type, and Team now use soft delete instead of hard delete.
- A shared controller concern, `HandlesMasterSoftDeletes`, now standardizes create, update, duplicate detection, restore, and archive behavior across these modules.
- A shared model concern, `UsesSoftDeletesForMasterData`, enables Laravel soft deletes on the covered master entities.
- Migration `2026_03_17_000001_add_deleted_at_to_master_tables.php` adds `deleted_at` to the covered master tables.

### Current Business Behavior
- Delete actions in covered master screens now archive records instead of permanently removing them.
- Recreating a master item with the same name restores the archived record instead of inserting a duplicate.
- Duplicate checks are case-insensitive and trim whitespace before comparison.
- Success messaging in covered UIs now reflects archive behavior.

### Data Integrity Impact
- Downstream relationships were updated to use `withTrashed()` where needed so historical employee, ticket, onboarding, attendance, leave, and exit records continue to resolve archived master references.
- This reduces reporting breakage when an organizational reference is retired but still used by historical records.

### Operational Notes
- Covered controllers still flush cache after create, update, restore, or archive.
- Active master list pages continue to show non-archived records only because standard Eloquent queries exclude soft-deleted rows.
- There is no separate restore UI yet; restore currently happens when the same name is created again.

## 15) Exit Department Configuration Update (2026-03-17)
### What Changed
- Exit workflow department ownership is now configurable from UI instead of relying on hardcoded mappings.
- A dedicated `exit_departments` table and controller-backed settings screen now manage exit department entries.
- Department deletion is blocked when the department is still tied to pending exit workflow responsibilities.

### Business Behavior
- HR/admin can update exit-department routing without code changes.
- Resignation and clearance routing stays aligned with changing department structure.
- This reduces the risk of broken exit flows after org changes.

## 16) Probation Tracking and HR Executive Analytics Update (2026-03-17)
### What Changed
- Resource master data now carries probation-tracking fields used for probation operations and reminders.
- A probation management screen/controller was added for tracking probation status operationally.
- A dedicated HR executive report module/service was added for management analytics and utilization-oriented reporting.

### Operational Impact
- Weekly probation reminder automation now works from explicit probation-tracking data.
- HR leadership gets a dedicated reporting surface for executive-level workforce analysis.
- The report service is the main aggregation layer for these management metrics and should be treated as the primary extension point.

### Domestic Approval: Mandatory Late-Policy Decision
- Domestic approval row now requires `Deduct Half Day Leave` selection (`yes/no`) before approve/bulk approve.
- Client-side validation blocks submit if any selected row has no decision.
- Server-side validation enforces the same (cannot bypass from crafted request).

### Late Policy Deduction Logic (Current)
- If approver selects `yes` and leave balance >= 0.5:
  - Deduct 0.5 via `LeaveLedgerService` with:
    - `reference_type = attendance_late_policy`
    - reason: `Leave deduction due to late policy`
  - Attendance log remains full present (`P`, `is_half_day = 0`).
- If approver selects `yes` and balance is insufficient:
  - No leave deduction.
  - Attendance log marked as half-day present (`0.5P` behavior using `P + is_half_day = 1`).
  - For multi-day attendance request, only one day is marked half-day; remaining days stay full-day `P`.
- If approver selects `no`:
  - No deduction and normal attendance logging.

### Approval UI and UX Stability
- Fixed domestic approval submit behavior where processing overlay stayed active after validation alert.
- Submit lock and global loader are reset when client-side validation blocks submission.

### Performance Optimizations
- Attendance submit/update emails moved from sync send to queued mail.
- Attendance approve/reject emails moved to queued mail and dispatched after DB transaction completion.
- Approval service avoids N+1 user lookup during grouped mail dispatch.
- Queue worker is now operationally required for attendance mail notifications.

### Report Updates
- Attendance report preview now treats any `P` log with `is_half_day = 1` as `0.5P` (not only international).
- Domestic requests report includes dedicated `Half Day / 0.5P` indicator:
  - `0.5P (Late Policy)` when leave was not deducted under late policy
  - `Half Day` for explicit half-day requests
  - `No` otherwise