How ahmed-fawzy99/hr-management-system works
Purpose and runtime
This is an HR-management SPA for organization structure, employee records, attendance, requests/leaves, payroll, calendars, and audit logs. Laravel 10/PHP 8.2 is the server and Vue 3/Inertia is the browser UI. PostgreSQL is the intended datastore; database queues, cron-driven scheduler, SMTP, and a Vite-built frontend are required.
Server entry points are public/index.php, bootstrap/app.php, routes/web.php, and routes/auth.php. The SPA starts at resources/js/app.js, with its Blade/Inertia shell in resources/views/app.blade.php.
Request, identity, and authorization boundary
Browser visits hit Laravel routes, pass through HTTP middleware, then controllers and domain services; responses are Inertia page props rendered by Vue rather than a separate REST frontend. Authentication, registration, password recovery, and email verification are handled by app/Http/Controllers/Auth/ and routes/auth.php.
Authorization/data isolation is materially enforced through application middleware, especially app/Http/Middleware/FilterOnlyUserDataMiddleware.php; standard authentication and Inertia request handling live in app/Http/Middleware/Authenticate.php and app/Http/Middleware/HandleInertiaRequests.php. Roles/permissions are backed by the permission migrations and config/permission.php.
Organizational and employee core
Employees are the central aggregate, attached to branches, departments, positions, salaries, managers, and shifts. Persistence models are under app/Models/Employee.php, app/Models/Branch.php, and app/Models/Department.php; their relational schema begins in database/migrations/2014_10_12_000000_create_employees_table.php and related 2023 migrations.
app/Http/Controllers/EmployeeController.php delegates employee lifecycle/search/archive work to app/Services/EmployeeServices.php. Employee deletion retains personal details via app/Models/ArchivedEmployee.php; creation also triggers credential email through app/Mail/EmployeeRegisterationCredentials.php.
Attendance and scheduling
Attendance is driven by employees’ assigned shifts and calendar exceptions. The primary boundary is app/Http/Controllers/AttendanceController.php → app/Services/AttendanceServices.php → app/Models/Attendance.php, with shift assignment in app/Models/EmployeeShift.php.
The system supports employee self-check-in and admin override, validates organization IP policy via app/Rules/CustomIPValidator.php, and derives work/overtime/undertime against shift definitions. Calendar events, holidays, and leave-related exclusions flow through app/Services/CalendarServices.php and app/Models/Calendar.php.
A scheduled daily process, app/Tasks/DailyAttendanceHandle.php, marks missing attendance as absent. Its orchestration point is app/Console/Kernel.php, requiring the external cron invocation of Laravel’s scheduler.
Payroll and evaluations
Payroll combines employee salary, attendance outcomes, additions/deductions, and weighted evaluations. The main flow is app/Http/Controllers/PayrollController.php → app/Services/PayrollServices.php → app/Models/Payroll.php, with related records in app/Models/Addition.php and app/Models/Deduction.php.
Monthly generation is executed asynchronously/scheduled through app/Tasks/MonthlyPayrollsHandle.php and app/Console/Kernel.php. Admin review can overwrite generated values; approval emails employees using app/Mail/PayrollEmail.php. Database queue infrastructure is represented by database/migrations/2023_07_24_101801_create_jobs_table.php and requires a running queue worker.
Employee requests, notifications, and auditability
Employees submit leave/complaint-style requests; admins decide status and response. The request workflow is centered on app/Http/Controllers/RequestController.php, app/Services/RequestServices.php, and app/Models/Request.php. Status changes notify by SMTP through app/Mail/RequestStatusUpdated.php.
Activity history is a cross-cutting audit concern, configured at config/activitylog.php and persisted by the activity-log migrations, notably database/migrations/2023_07_31_211210_add_event_column_to_activity_log_table.php. Logs are exposed through app/Http/Controllers/LogsController.php.
Client application and presentation boundary
Vue pages mirror server domains: employee pages in resources/js/Pages/Employee/, attendance views in resources/js/Pages/Attendance/, and payroll review/view pages in resources/js/Pages/Payroll/. Shared navigation/layout and reusable data-table UI live in resources/js/Layouts/AuthenticatedLayout.vue and resources/js/Components/DataTable.vue.
The frontend communicates through Inertia’s server-driven navigation/form lifecycle, not independently versioned API endpoints. Built static assets are served from public/build/; localization is supplied by lang/en.json, lang/ar.json, and locale middleware at app/Http/Middleware/SetLocale.php.
Main entry points: FilterOnlyUserDataMiddleware.php Identity, isolation and locale · PayrollServices.php Payroll workflow · AttendanceServices.php Attendance workflow · Employee.php Organization and employees
Components 22
Browser SPA
- Employee/admin browser
- Vue Inertia UI · Server-driven pages, forms, layouts, and tables.
resources/js/app.js - Inertia Blade shell
resources/views/app.blade.php - Vite build assets
Laravel HTTP boundary
- Laravel entry
public/index.php - Web and auth routes
routes/web.php - Identity, isolation and locale · Authenticates, scopes user data, supplies Inertia props, and sets locale.
app/Http/Middleware/FilterOnlyUserDataMiddleware.php - Auth flows · Registration, recovery, and email verification.
Domain workflows
- Employee lifecycle · Creates, searches, archives, and manages employee records.
app/Services/EmployeeServices.php - Organization and employees · Employees relate to branches, departments, positions, salaries, managers, and shifts.
app/Models/Employee.php - Attendance workflow · Self-check-in and admin override derive worked and overtime time.
app/Services/AttendanceServices.php - Attendance and shifts
app/Models/Attendance.php - Calendar exceptions · Applies holidays, events, and leave exclusions.
app/Services/CalendarServices.php - Payroll workflow · Combines salary, attendance, evaluations, additions, and deductions.
app/Services/PayrollServices.php - Payroll records
app/Models/Payroll.php - Employee requests · Leave and complaint submission, decision, and response workflow.
app/Services/RequestServices.php - Request records
app/Models/Request.php - Activity audit log · Cross-cutting activity history exposed to administrators.
config/activitylog.php
Data and background runtime
- PostgreSQL · Stores application, permission, audit, and queue data.
- Laravel scheduler · Cron invokes daily attendance and monthly payroll tasks.
app/Console/Kernel.php - Database queue worker · Processes queued notifications and payroll work.
database/migrations/2023_07_24_101801_create_jobs_table.php - SMTP mail delivery · Delivers credentials, request status, and payroll approval email.
Connections 30
- Employee/admin browser → Laravel entry: visits
- Laravel entry → Web and auth routes: dispatches
- Web and auth routes → Identity, isolation and locale: passes through
- Identity, isolation and locale → Auth flows: auth endpoints
- Identity, isolation and locale → Employee lifecycle: authorized requests
- Identity, isolation and locale → Attendance workflow: authorized requests
- Identity, isolation and locale → Payroll workflow: authorized requests
- Identity, isolation and locale → Employee requests: authorized requests
- Employee lifecycle → Organization and employees: manages
- Attendance workflow → Attendance and shifts: records
- Attendance workflow → Organization and employees: uses assignments
- Attendance workflow → Calendar exceptions: applies exceptions
- Payroll workflow → Payroll records: generates
- Payroll workflow → Organization and employees: uses salary
- Payroll workflow → Attendance and shifts: uses outcomes
- Employee requests → Request records: updates
- Organization and employees → PostgreSQL: persists
- Attendance and shifts → PostgreSQL: persists
- Payroll records → PostgreSQL: persists
- Request records → PostgreSQL: persists
- Activity audit log → PostgreSQL: persists events
- Laravel scheduler → Attendance workflow: daily absence processing
- Laravel scheduler → Payroll workflow: monthly generation
- Database queue worker → PostgreSQL: uses jobs table
- Employee lifecycle → SMTP mail delivery: credentials email
- Employee requests → SMTP mail delivery: status email
- Payroll workflow → SMTP mail delivery: approval email
- Vue Inertia UI → Inertia Blade shell: mounts in
- Inertia Blade shell → Vite build assets: loads
- Identity, isolation and locale → Vue Inertia UI: Inertia page props