# AI_SUPER_PROMPT.md Date: 2026-03-16 Use this prompt with AI coding tools such as Codex, Copilot, or Claude. --- ## SUPER PROMPT You are working on an existing Laravel ERP project. Your job is to build a **new HR expansion package inside the same project structure** without modifying old planning files and without introducing any Laravel module package. You must follow the existing project architecture and conventions exactly. ### Project Context - Stack: Laravel 12, PHP 8.2, MySQL, Bootstrap, Metronic, Spatie Permission, Spatie Translatable - Company model: one company with multiple branches - HR must use the same branches already used in Finance - Employee can be transferred or seconded between branches - System language style: same as current project (bilingual where required) - HR must integrate with Finance for payroll posting - HR must include Employee Self-Service Portal - HR task management is inside HR only, not a system-wide project manager --- ## Main Goal Build a complete HR system with these domains: 1. HR Setup 2. Recruitment 3. Employee Master 4. Contracts 5. Attendance 6. Leave Requests 7. Permission Requests 8. Loan Requests 9. Bonuses 10. Penalties 11. Deductions 12. Data Correction Requests 13. Complaints 14. Resignation and End of Service 15. Payroll 16. Payroll Posting to Finance 17. Employee Self-Service Portal 18. HR Internal Task Management 19. HR Analytics --- ## Critical Build Rules 1. Do NOT modify old project planning files. 2. Do NOT use nWidart modules or any module package. 3. Use the same layered architecture already used in the project. 4. Controllers must stay thin. 5. All business logic must be in Services. 6. Validation must be in FormRequest classes. 7. Models should mainly contain relationships, casts, scopes only when necessary. 8. Keep naming consistent and clean. 9. Build one step at a time. 10. Stop after each requested step. 11. Do not generate unrelated files. 12. Do not refactor unrelated modules. 13. Do not create tests unless specifically requested. 14. Keep finance integration ready but isolated behind services. 15. All request types should support approval workflow. 16. All configurable types must come from setup tables, not hardcoded enums. 17. Portal users can view their data, but cannot directly edit master employee data. 18. If employee needs profile correction, create a data correction request that goes through approval. 19. Payroll must support monthly salary and a separate free salary screen. 20. Contract renewal alert should trigger 30 days before expiry. 21. Contract PDF generation should be supported. 22. Electronic signature support should be kept ready in structure. 23. Attendance must support: - manual entry - Excel import - biometric-ready integration layer 24. Build with future scalability in mind. --- ## Required Architecture ### Models Use: - app/Models/HR/Setup - app/Models/HR/Recruitment - app/Models/HR/Employee - app/Models/HR/Attendance - app/Models/HR/Requests - app/Models/HR/Payroll - app/Models/HR/Tasks ### Services Use: - app/Services/HR/Setup - app/Services/HR/Recruitment - app/Services/HR/Employee - app/Services/HR/Attendance - app/Services/HR/Requests - app/Services/HR/Payroll - app/Services/HR/Tasks ### Controllers Use: - app/Http/Controllers/Admin/HR - app/Http/Controllers/Portal ### Requests Use: - app/Http/Requests/Admin/HR - app/Http/Requests/Portal ### Views Use: - resources/views/dashboard/hr - resources/views/portal ### Routes Keep routes grouped clearly for: - admin HR routes - employee portal routes --- ## Functional Scope Details ### 1) Recruitment Flow Flow: Job Request → Candidate → Interview → Interview Evaluation → Job Offer → Contract → Employee Onboarding Must support: - HR creates candidates - interview scheduling - interview evaluation form - job offer management - contract generation - convert accepted candidate to employee ### 2) Employee Master File Employee profile must be split into tabs: #### Personal Data - employee number - Arabic and English names - identity / residence number - nationality - gender - birth date - marital status - address - mobile - email - emergency contact #### Job Data - branch - department - designation - grade - direct manager - hire date - employment status - contract type - probation period - transfer / secondment readiness #### Financial Data - basic salary - allowances - earnings - deductions - bank account - cost center optional - payment method #### Attendance Data - shift type - working days - working hours - overtime policy - lateness policy #### Documents - personal photo - ID copy - contract - CV - certificates - other attachments #### History - transfers - secondments - salary changes - contract changes - status changes - audit trail ### 3) Employee Self-Service Portal Employee can: - view own profile - view own attendance - view own payroll - submit requests - track request status - view own tasks - view own bonuses, penalties, deductions - view allowed documents - submit complaint - submit resignation - submit data correction request Employee cannot directly edit profile master data. ### 4) Requests and Approval Workflow Request workflow: Employee → Direct Manager → Higher Manager Level → HR Manager → Final Approval This workflow must be configurable by request type. Request types: - leave request - permission request - loan request - data correction request - complaint request - resignation request - bonus request if approved flow is needed ### 5) Attendance Support: - manual records - Excel import batches - biometric-ready structure - attendance status - late minutes - overtime - absence - early leave ### 6) Leaves and Permissions These must be setup-driven. Leave types examples: - annual - sick - emergency - unpaid - others Rules: - some leave types affect payroll - some leave types have balance - some are unpaid - permissions may be hourly ### 7) Loans / Bonuses / Penalties / Deductions All types must come from setup tables. Loan request: - amount - installment count - deduction start date - approval flow - payroll deduction integration Bonus: - fixed or variable - optionally payroll-linked Penalty: - warning or financial penalty - optionally payroll-linked Deductions: - manual - absence-based - penalty-based - loan-based ### 8) Contracts Support: - multiple contract types - start/end dates - manual renewal - renewal alert before 30 days - contract PDF generation - electronic signature ready structure ### 9) Payroll Payroll lifecycle: Draft → Reviewed → Approved → Posted to Finance → Paid Support: - monthly payroll - free salary screen - salary profile - allowances - earnings - deductions - loans - unpaid leave deduction - penalties - bonuses - payroll line items - finance posting ### 10) Finance Integration Payroll posting must be service-based and configurable. Need posting profile support for: - basic salary account - allowance accounts - earning accounts - deduction accounts - payroll payable account - loan receivable account - EOS account - bank/cash account Do not hardcode accounting mappings. ### 11) Resignation and End of Service Support: - employee resignation request - HR service termination - last working day - approval flow - settlement - end of service calculation - clearance checklist structure if needed ### 12) Complaints Support: - complaint submission - optional confidentiality flag - status tracking - response handling - closing complaint ### 13) HR Internal Tasks This is HR-only task management, not a full project tool. Support: - task creation - assign to one employee - priority - due date - comments - attachments - status changes Statuses: - new - in_progress - on_hold - completed - cancelled ### 14) Analytics Support dashboard and reporting for: - employee counts - branch distribution - department distribution - attendance statistics - leave statistics - payroll cost - contract expiry alerts - resignation and turnover indicators --- ## Recommended Database Groups ### Setup Tables - hr_departments - hr_designations - hr_grades - hr_contract_types - hr_leave_types - hr_permission_types - hr_loan_types - hr_bonus_types - hr_penalty_types - hr_earning_types - hr_deduction_types - hr_request_workflows - hr_request_workflow_steps - hr_payroll_posting_profiles ### Recruitment Tables - hr_job_requests - hr_candidates - hr_candidate_documents - hr_interviews - hr_interview_evaluations - hr_job_offers ### Employee Tables - hr_employees - hr_employee_contracts - hr_employee_documents - hr_employee_salary_profiles - hr_employee_allowances - hr_employee_deductions - hr_employee_bank_accounts - hr_employee_transfers - hr_employee_secondments - hr_employee_status_histories ### Request Tables - hr_leave_requests - hr_permission_requests - hr_loan_requests - hr_data_change_requests - hr_bonus_requests - hr_complaint_requests - hr_resignation_requests - hr_request_attachments - hr_approvals - hr_approval_steps ### Attendance Tables - hr_attendance_records - hr_attendance_import_batches - hr_overtime_records - hr_absence_records ### Payroll Tables - hr_payroll_periods - hr_payroll_runs - hr_payroll_lines - hr_payroll_line_items - hr_salary_payments - hr_payroll_postings - hr_end_of_service_settlements ### Task Tables - hr_tasks - hr_task_comments - hr_task_attachments --- ## Permission Naming Convention Use: module.resource.action Examples: - hr.employees.view - hr.employees.create - hr.contracts.renew - hr.attendance.import - hr.leaves.approve - hr.loans.approve - hr.payroll.post - portal.profile.view - portal.requests.create - hr.tasks.assign --- ## Data and UX Rules 1. Use tabs for employee profile screens. 2. Use filters on all index pages. 3. Use status badges consistently. 4. Use upload handling for documents and request attachments. 5. Use audit/history for critical employee changes. 6. Use approval status timeline where possible. 7. Employee portal must be simple and read-focused. 8. Salary and payroll screens must show line items clearly. 9. Do not expose finance posting internals directly to employee portal. 10. Support future localization and translation. --- ## Development Approach Always work in this order: 1. migrations 2. models 3. services 4. form requests 5. controllers 6. views 7. permissions 8. route wiring 9. report/dashboard queries Do NOT jump randomly. --- ## Response Format Required From AI Tool For every requested step: 1. State what files will be created 2. Generate only those files 3. Do not continue to the next step 4. Wait for the next instruction --- ## First Build Instruction Start with this exact step only: Create Laravel migrations for the following setup tables: - hr_departments - hr_designations - hr_grades - hr_contract_types - hr_leave_types - hr_permission_types - hr_loan_types - hr_bonus_types - hr_penalty_types - hr_earning_types - hr_deduction_types Rules: - use snake_case - include timestamps - include active status where relevant - use JSON name fields if translation support is needed - add indexes where appropriate - do not generate models, controllers, or views yet - stop after migrations