# Ajdan HR – Project overview

A server-rendered Laravel web app for Ajdan's staff appraisal process. Reviewers (team leads, department heads, HR) score employees in stages; an admin manages people, questions, cycles and reports. The database schema is documented separately in [DATABASE_DESIGN.md](DATABASE_DESIGN.md).

## Stack
- Laravel 12, PHP, MySQL 8 (database `ajdan_hr`, utf8mb4)
- Blade templates, hand-written CSS (`resources/css/app.css`), small vanilla JS, built with Vite
- Fonts and icons self-hosted through npm (IBM Plex Sans / Arabic, Tabler icons)
- Microsoft 365 sign-in via Socialite + Microsoft Azure provider
- English and Arabic (`lang/ar.json`) with RTL support
- Queue, cache and sessions use the database driver

## How the app works
- `employees` is the login table. Only roles `team_lead`, `department_head` and `hr` can sign in, plus admins (`is_admin`). Normal users sign in with Microsoft 365; a dev picker (`/dev-login/{id}`) exists only when `APP_ENV=local`.
- An admin creates an appraisal cycle, opens it, and generates reviews. Reviewers and section weights are copied onto each review (snapshot), so later org or question changes never rewrite history.
- A review moves through stages, one section per reviewer role. The reviewer uses **Save Progress** (partial, editable) or **Final Submit** (must be complete; locks the section, advances the stage and notifies the next reviewer). The final score is computed from weighted sections.
- Access is enforced by `ReviewPolicy`; row locking prevents double submits; every important action is written to `audit_logs`.
- Admin can "view as" another user (audited under both names).

## What is built
- **Database:** 10 migrations, models, enums, factories, seeders (`ReviewSectionSeeder`, `AdminSeeder`, `DemoDataSeeder`).
- **Workflow:** `ReviewService` (create reviews, Save Progress, Final Submit, scoring, notifications), `ReviewPolicy`, audit log.
- **Sign-in:** Microsoft SSO controller, local dev picker, deactivated users signed out by middleware.
- **Reviewer screens:** dashboard, My reviews, review form, notifications.
- **Admin screens:** overview, employees, questions, all reviews, reports with CSV export, cycles and email log, view-as.
- **Frontend:** CSS ported from the approved prototype (`ui-preview/index.html`), Blade components, EN/AR, RTL, stacked mobile tables.

### Routes (summary)
Guest: `/login`, `/auth/microsoft`, `/auth/microsoft/callback`, `/access-denied`, `/dev-login/{employee}` (local only).
Signed in: `/dashboard`, `/reviews`, `/reviews/{review}` (+ `save`, `submit`), `/notifications`.
Admin (`/admin/...`): employees, questions, reviews, reports (+ export), cycles (+ open, close, create reviews), impersonate.

## Running locally
```
composer install
npm install
cp .env.example .env        # set DB_* and APP_URL, then: php artisan key:generate
php artisan migrate --seed
npm run build               # or: npm run dev (hot reload)
php artisan queue:work      # queued notifications
```
Site: `http://ajdan-hr.test` (Laravel Herd).

## Testing
```
php artisan test
vendor\bin\pint
```
Tests use in-memory SQLite (`phpunit.xml`) and never touch the `ajdan_hr` database. Last run (5 Nov 2026): **89 passed, 370 assertions**; Pint clean. Coverage: review workflow and scoring (`ReviewWorkflowTest`), the same rules over HTTP including access control and IDOR (`ReviewHttpTest`), and who can see or rate what (`ReviewPolicyTest`), plus admin modules.

## Known limitations and pending work
- Not yet verified in a browser across screen sizes (320 to 1920px).
- Real Microsoft sign-in needs the tenant id, client id, secret and redirect URL from Ajdan IT.
- Mail is `MAIL_MAILER=log`; real delivery (SMTP or Graph) is not configured.
- Rating band thresholds in `config/appraisal.php` are assumptions awaiting client confirmation; report types and whether managers are themselves appraised are open decisions.
- Concurrency relies on a row lock; there is no parallel-run test.
- Admin forms are server-rendered side drawers driven by `?edit=` / `?create=1`.
- Security and performance review pass not done yet.
