# ahmed-fawzy99/hr-management-system architecture

> Architecture diagram of the GitHub repository ahmed-fawzy99/hr-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-fawzy99/hr-management-system
- Repository: https://github.com/ahmed-fawzy99/hr-management-system

## Overview

#### 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: [`app/Http/Middleware/FilterOnlyUserDataMiddleware.php`](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Http/Middleware/FilterOnlyUserDataMiddleware.php) (Identity, isolation and locale), [`app/Services/PayrollServices.php`](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/PayrollServices.php) (Payroll workflow), [`app/Services/AttendanceServices.php`](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/AttendanceServices.php) (Attendance workflow), [`app/Models/Employee.php`](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Employee.php) (Organization and employees)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser SPA"]
  node_browser(("Employee/admin browser"))
  node_vue["Vue Inertia UI<br/>frontend<br/>[app.js]"]
  node_shell["Inertia Blade shell<br/>presentation<br/>[app.blade.php]"]
  node_assets["Vite build assets<br/>static assets"]
end

subgraph group_http["Laravel HTTP boundary"]
  node_entry["Laravel entry<br/>PHP entrypoint<br/>[index.php]"]
  node_routes["Web and auth routes<br/>routing<br/>[web.php]"]
  node_middleware["Identity, isolation and locale<br/>HTTP middleware"]
  node_auth["Auth flows<br/>auth controllers"]
end

subgraph group_domains["Domain workflows"]
  node_employee["Employee lifecycle<br/>controller + service"]
  node_employee_data[("Organization and employees<br/>Eloquent aggregate<br/>[Employee.php]")]
  node_attendance["Attendance workflow<br/>controller + service"]
  node_attendance_data[("Attendance and shifts<br/>Eloquent records<br/>[Attendance.php]")]
  node_calendar["Calendar exceptions<br/>calendar service"]
  node_payroll["Payroll workflow<br/>controller + service"]
  node_payroll_data[("Payroll records<br/>Eloquent records<br/>[Payroll.php]")]
  node_requests["Employee requests<br/>controller + service"]
  node_request_data[("Request records<br/>Eloquent model<br/>[Request.php]")]
  node_audit["Activity audit log<br/>audit trail<br/>[activitylog.php]"]
end

subgraph group_runtime["Data and background runtime"]
  node_database[("PostgreSQL<br/>primary datastore")]
  node_scheduler["Laravel scheduler<br/>scheduled orchestration<br/>[Kernel.php]"]
  node_queue["Database queue worker<br/>async worker"]
  node_smtp["SMTP mail delivery<br/>external mail"]
end

node_browser -->|"visits"| node_entry
node_entry -->|"dispatches"| node_routes
node_routes -->|"passes through"| node_middleware
node_middleware -->|"auth endpoints"| node_auth
node_middleware -->|"authorized requests"| node_employee
node_middleware -->|"authorized requests"| node_attendance
node_middleware -->|"authorized requests"| node_payroll
node_middleware -->|"authorized requests"| node_requests
node_employee -->|"manages"| node_employee_data
node_attendance -->|"records"| node_attendance_data
node_attendance -->|"uses assignments"| node_employee_data
node_attendance -->|"applies exceptions"| node_calendar
node_payroll -->|"generates"| node_payroll_data
node_payroll -->|"uses salary"| node_employee_data
node_payroll -->|"uses outcomes"| node_attendance_data
node_requests -->|"updates"| node_request_data
node_employee_data -->|"persists"| node_database
node_attendance_data -->|"persists"| node_database
node_payroll_data -->|"persists"| node_database
node_request_data -->|"persists"| node_database
node_audit -->|"persists events"| node_database
node_scheduler -->|"daily absence processing"| node_attendance
node_scheduler -->|"monthly generation"| node_payroll
node_queue -->|"uses jobs table"| node_database
node_employee -.->|"credentials email"| node_smtp
node_requests -.->|"status email"| node_smtp
node_payroll -.->|"approval email"| node_smtp
node_vue -->|"mounts in"| node_shell
node_shell -->|"loads"| node_assets
node_middleware -->|"Inertia page props"| node_vue

click node_vue "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/resources/js/app.js"
click node_shell "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/resources/views/app.blade.php"
click node_entry "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/public/index.php"
click node_routes "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/routes/web.php"
click node_middleware "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Http/Middleware/FilterOnlyUserDataMiddleware.php"
click node_employee "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/EmployeeServices.php"
click node_employee_data "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Employee.php"
click node_attendance "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/AttendanceServices.php"
click node_attendance_data "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Attendance.php"
click node_calendar "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/CalendarServices.php"
click node_payroll "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/PayrollServices.php"
click node_payroll_data "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Payroll.php"
click node_requests "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/RequestServices.php"
click node_request_data "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Request.php"
click node_audit "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/config/activitylog.php"
click node_scheduler "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Console/Kernel.php"
click node_queue "https://github.com/ahmed-fawzy99/hr-management-system/blob/main/database/migrations/2023_07_24_101801_create_jobs_table.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_vue,node_shell,node_assets toneBlue
class node_entry,node_routes,node_middleware,node_auth toneAmber
class node_employee,node_employee_data,node_attendance,node_attendance_data,node_calendar,node_payroll,node_payroll_data,node_requests,node_request_data,node_audit toneMint
class node_database,node_scheduler,node_queue,node_smtp toneRose
```

## Components

### Browser SPA

- **Employee/admin browser**: browser
- [Vue Inertia UI](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/resources/js/app.js): frontend · Server-driven pages, forms, layouts, and tables. · `resources/js/app.js`
- [Inertia Blade shell](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/resources/views/app.blade.php): presentation · `resources/views/app.blade.php`
- **Vite build assets**: static assets

### Laravel HTTP boundary

- [Laravel entry](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/public/index.php): PHP entrypoint · `public/index.php`
- [Web and auth routes](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/routes/web.php): routing · `routes/web.php`
- [Identity, isolation and locale](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Http/Middleware/FilterOnlyUserDataMiddleware.php): HTTP middleware · Authenticates, scopes user data, supplies Inertia props, and sets locale. · `app/Http/Middleware/FilterOnlyUserDataMiddleware.php`
- **Auth flows**: auth controllers · Registration, recovery, and email verification.

### Domain workflows

- [Employee lifecycle](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/EmployeeServices.php): controller + service · Creates, searches, archives, and manages employee records. · `app/Services/EmployeeServices.php`
- [Organization and employees](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Employee.php): Eloquent aggregate · Employees relate to branches, departments, positions, salaries, managers, and shifts. · `app/Models/Employee.php`
- [Attendance workflow](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/AttendanceServices.php): controller + service · Self-check-in and admin override derive worked and overtime time. · `app/Services/AttendanceServices.php`
- [Attendance and shifts](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Attendance.php): Eloquent records · `app/Models/Attendance.php`
- [Calendar exceptions](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/CalendarServices.php): calendar service · Applies holidays, events, and leave exclusions. · `app/Services/CalendarServices.php`
- [Payroll workflow](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/PayrollServices.php): controller + service · Combines salary, attendance, evaluations, additions, and deductions. · `app/Services/PayrollServices.php`
- [Payroll records](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Payroll.php): Eloquent records · `app/Models/Payroll.php`
- [Employee requests](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Services/RequestServices.php): controller + service · Leave and complaint submission, decision, and response workflow. · `app/Services/RequestServices.php`
- [Request records](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Models/Request.php): Eloquent model · `app/Models/Request.php`
- [Activity audit log](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/config/activitylog.php): audit trail · Cross-cutting activity history exposed to administrators. · `config/activitylog.php`

### Data and background runtime

- **PostgreSQL**: primary datastore · Stores application, permission, audit, and queue data.
- [Laravel scheduler](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/app/Console/Kernel.php): scheduled orchestration · Cron invokes daily attendance and monthly payroll tasks. · `app/Console/Kernel.php`
- [Database queue worker](https://github.com/ahmed-fawzy99/hr-management-system/blob/main/database/migrations/2023_07_24_101801_create_jobs_table.php): async worker · Processes queued notifications and payroll work. · `database/migrations/2023_07_24_101801_create_jobs_table.php`
- **SMTP mail delivery**: external mail · Delivers credentials, request status, and payroll approval email.

## Connections

- 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