# Project Gap Analysis (HRMS / ERP Foundation)

## Executive Summary

This report summarizes the current project status based on the implemented codebase and identifies the most important gaps to move the system from a strong HRMS/ERP foundation to a more flexible, stable, and enterprise-ready product.

### Current Position (Practical Assessment)
- `Strong foundation`: HR, attendance, payroll, approvals, notifications, mail center, chat, reception/visits, system settings, operations center.
- `Good extensibility`: modular libraries (`Settings`, `Comms`, `ApprovalFlow`, `Jobs`, `SystemHealth`) and configurable workflows.
- `Main gap now`: **flexibility + operational hardening + UX consistency**.

### What Was Added Recently (Flexibility Focus)
- System branding from Admin (`site name`, `subtitle`, `logo upload`)
- Sidebar customization from Admin:
  - custom labels
  - custom icons
  - hide/show menu items (UI-level)
  - custom section names
  - per-item sort order inside each section

---

## 1) Current Capability Matrix

| Domain | Status | Notes |
|---|---|---|
| Authentication / Login / OTP recovery | Implemented | Professional login UI + OTP recovery + email confirmation |
| Roles & route permissions | Implemented (good) | Route visibility + action-level controls exist |
| Multi-language (AR/EN) + RTL/LTR | Implemented (partial polish pending) | Core areas translated, full hardcoded cleanup still needed |
| Notifications (internal) | Implemented | Center + targeting + unread counters |
| Mail Center (professional email) | Implemented | Separate from notifications, SMTP-driven |
| Internal chat + attachments | Implemented | Good foundation |
| Reception / visits | Implemented (strong) | Requests, approvals, badge, reports, delayed visit alerts |
| Approval workflows | Implemented (strong foundation) | Configurable routes + conditional amount ranges |
| Operations Center / Jobs / Health | Implemented (foundation) | Queue + health + SLA/report planning foundations |
| Branding & sidebar customization | Implemented (new) | Strong flexibility improvement |
| Dashboard analytics | Implemented (expanded) | More cards/analytics added |
| Biometric sync engine (vendor connector) | Partial | Settings + mapping + monitoring ready; connectors pending |
| Backup / restore (real execution) | Partial | Tracking/visibility exists; actual backup engine pending |
| Accounting depth (ERP-grade) | Partial | Foundation exists; advanced financial flows/reports pending |
| UX consistency across all pages | Partial | Some screens are polished, some need standardization |
| Database migrations/versioning | Missing | `/setup.php` is useful but not enough long-term |
| Automated tests for critical flows | Missing | High priority for safety and regression control |

---

## 2) Priority Gaps (What Is Still Missing)

### A. Flexibility (Highest Priority per Product Goal)

#### A1. Sidebar & Navigation Flexibility (Now improved, still expandable)
- `Done`: rename item, icon, hide/show, rename sections, sort within section
- `Missing next`:
  - drag-and-drop ordering (instead of numeric sort)
  - per-role sidebar profiles
  - per-branch navigation profiles
  - enable/disable route access from same UI (not just hide)

#### A2. Dashboard Flexibility
- `Current`: multiple dashboards/cards by role
- `Missing next`:
  - per-user card layout preferences
  - hide/show/reorder dashboard widgets
  - saved dashboard views by role
  - date presets + favorite filters

#### A3. Settings Inheritance (Global -> Branch -> Department -> User)
- `Missing`
- Business impact: very high (real enterprise flexibility)

---

### B. Stability / Technical Hardening

#### B1. Database Migrations & Versioning
- `Missing`
- Risk today:
  - setup upgrades can be partial
  - duplicate constraints / schema drift
  - hard to track DB version

#### B2. Query Hardening
- `Partial`
- Recurring symptom already observed:
  - ambiguous columns (`status`, `amount`) in joined queries
- Needed:
  - query audit + aliasing standard

#### B3. Encoding / i18n Hardening
- `Partial`
- Progress exists, but final state should be:
  - all source files UTF-8
  - all UI strings from `t()`
  - no runtime mojibake repair dependency except fallback

#### B4. Automated Tests (Critical Flows)
- `Missing`
- Prioritize:
  - approvals
  - loan flow
  - password reset OTP
  - permissions
  - payroll posting/accounting links

---

### C. UX / Ease of Use

#### C1. Unified Inbox with direct actions
- `Partial` (Manager Inbox exists)
- `Missing next`:
  - approve/reject directly from inbox
  - filters/saved views
  - SLA highlighting

#### C2. Table Experience Standardization
- `Missing (system-wide standard)`
- Needed:
  - saved filters
  - column chooser
  - bulk actions
  - export consistency

#### C3. In-app guidance
- `Missing`
- Needed:
  - tooltips for admin settings
  - empty state guidance
  - quick-start guides per role

---

### D. Operations / Enterprise Readiness

#### D1. Queue Adoption Across Modules
- `Partial`
- Foundation exists (`Jobs`), but many actions still run synchronously.
- Target:
  - emails, heavy notifications, sync tasks, report generation via queue

#### D2. Worker Scheduling / Monitoring
- `Partial`
- Need production routine:
  - Windows Task Scheduler or Cron jobs
  - failure alerts
  - retry policy review

#### D3. Real Backup & Restore
- `Partial`
- Needed:
  - DB backup job execution
  - restore script
  - validation/test restore

#### D4. Biometric Connectors
- `Partial`
- Needed:
  - actual vendor connectors (ZKTeco/API/SDK/file)
  - dedup logic + error handling + reprocessing

---

## 3) Recommended Roadmap (Practical Sequence)

## Phase 1: Flexibility & UX (Immediate)
1. Dashboard widget personalization (show/hide/reorder)
2. Sidebar drag-and-drop ordering (replace numeric sort UX)
3. Sidebar customization by role profile
4. In-app help text/tooltips for complex settings (SMTP, workflows, devices)
5. Unified table UX standard (filters + columns + bulk actions)

## Phase 2: Stability & Safety
1. Migration system (`db/migrations`)
2. Query alias audit (prevent ambiguous columns)
3. UTF-8 + i18n hardening pass
4. Critical flow smoke tests
5. Security rate limits (login / OTP / forgot password)

## Phase 3: Operational Maturity
1. Queue adoption across mail/notifications/reports
2. Worker scheduling and health alarms
3. Real backup + restore workflow
4. Biometric sync connector(s)
5. Scheduled reports finalization (PDF/Excel + email delivery)

---

## 4) Flexibility-Focused Backlog (Recommended Next Builds)

| Item | Priority | Effort | Impact |
|---|---|---:|---:|
| Dashboard widget customization per user | High | Medium | High |
| Sidebar drag-and-drop ordering | High | Medium | High |
| Sidebar profiles by role | High | Medium | High |
| Section show/hide by role | High | Medium | Medium |
| Settings inheritance (Global/Branch/Dept/User) | High | High | Very High |
| Notification preferences per user | High | Medium | High |
| Custom email templates from admin | Medium | Medium | High |
| Form templates / presets for repeated requests | Medium | Medium | Medium |

---

## 5) UX Quality Checklist (Target State)

- No technical messages shown to end users (use professional wording)
- Same button style and action placement across modules
- Same status badge language and color logic across modules
- Same table filters/export behavior across modules
- Same create/edit/approve flow pattern across modules
- Full Arabic mode without mixed English labels
- Full English mode without Arabic remnants

---

## 6) Immediate Action Plan (What to Build Next)

### Recommended next 3 items (after this report)
1. `Dashboard personalization` (cards show/hide/reorder per user)
2. `Sidebar drag-and-drop` (upgrade current numeric sort UX)
3. `User guide + in-app help links` (reduce support load and speed onboarding)

---

## 7) Success Metrics (How to know the system improved)

- Admin can rebrand and reorganize navigation without code changes
- New user onboarding time decreases (measured operationally)
- Fewer support questions about “where is feature X”
- Fewer runtime issues from schema drift / encoding / ambiguous queries
- Faster pages during email/report heavy actions after queue adoption

---

## 8) Notes

- This analysis reflects the current codebase and implemented features observed in the repository.
- The strongest immediate differentiator for this product is **flexibility from Admin** without requiring developer intervention.