Skip to main content

Project Structure

The HRMS consists of two separate repositories: hrms-api (backend) and hrms-web (frontend).

Backend (hrms-api)​

app/
├── Http/
│   ├── Controllers/
│   │   ├── AuthController.php              # Login / logout
│   │   └── Api/
│   │       ├── MeController.php            # Current user profile
│   │       ├── EntityController.php        # Entities CRUD + export
│   │       ├── DepartmentController.php    # Departments CRUD + manager/TL sync
│   │       ├── EmployeeController.php      # Employees CRUD + profile picture
│   │       ├── Employee*Controller.php     # Sub-resources (contact, emergency, etc.)
│   │       ├── RoleController.php          # Roles CRUD + permission sync
│   │       ├── PermissionController.php    # List permissions
│   │       ├── KpiTemplateController.php   # KPI templates CRUD
│   │       ├── KpiTemplateItemController.php   # Template items + sync + reorder
│   │       ├── KpiCycleController.php      # Cycles CRUD + publish + dashboard
│   │       ├── KpiEvaluationController.php # Evaluation workflow actions
│   │       ├── KpiEvaluationEvidenceController.php # Evidence upload/download
│   │       ├── ProbationEvaluationController.php   # Probation workflow
│   │       ├── NotificationController.php  # Notifications list + read
│   │       ├── NotificationSettingController.php   # Channel settings
│   │       ├── ActionableItemController.php # Actionable items
│   │       └── ImportController.php        # Bulk imports + error reports
│   ├── Requests/                           # 47 FormRequest validation classes
│   └── Resources/                          # 25 API resource transformers
├── Models/                                 # 24 Eloquent models
├── Policies/                               # 7 authorization policies
├── Services/
│   ├── KpiCyclePublisher.php               # Cycle publish logic
│   ├── KpiEvaluationWorkflowService.php    # KPI evaluation state machine
│   ├── ProbationEvaluationWorkflowService.php  # Probation state machine
│   ├── InternalNotificationService.php     # Notification dispatch
│   ├── ActionableItemService.php           # Actionable item queries
│   ├── NotificationChannelSettingsService.php  # Channel resolution
│   └── Imports/
│       ├── EmployeeImportService.php       # Employee CSV/Excel import
│       ├── KpiTemplateImportService.php    # KPI template import
│       ├── TabularImportReader.php         # CSV/XLSX file reader
│       ├── ImportErrorBag.php              # Error accumulator
│       └── ImportErrorReportStore.php      # Error report storage
├── Notifications/
│   └── InternalSystemNotification.php      # Laravel notification class
├── Traits/
│   └── ApiResponse.php                     # JSON response helpers
└── Providers/
config/
├── cors.php                                # CORS for SPA
├── sanctum.php                             # Stateful domain config
├── permission.php                          # Spatie config
└── notifications.php                       # Event/channel definitions
routes/
├── api.php                                 # All API routes (auth:sanctum)
└── web.php                                 # Login/logout routes
database/
├── migrations/                             # 34 migration files
├── seeders/                                # Role/permission + test data seeders
└── factories/                              # Model factories for testing
tests/
└── Feature/Api/                            # 28 feature test files (392 tests)
docs/                                       # Project documentation (source material)

Key Conventions​

  • Controllers are thin orchestrators; business logic lives in Services.
  • FormRequests handle all input validation and authorization checks.
  • Resources shape all JSON responses consistently.
  • Policies centralize permission checks using Spatie's can() method.
  • Services encapsulate workflow logic with database transactions and pessimistic locking.

Frontend (hrms-web)​

app/
├── layout.tsx                              # Root layout (AuthProvider, Toaster)
├── page.tsx                                # Redirects to /dashboard
├── login/page.tsx                          # Login page
└── dashboard/
    ├── layout.tsx                           # Authenticated layout (sidebar)
    ├── page.tsx                             # Dashboard summary cards
    ├── entities/page.tsx                    # Entities list + CRUD
    ├── departments/page.tsx                 # Departments + manager/TL sync
    ├── employees/
    │   ├── page.tsx                         # Employee list with filters
    │   ├── new/page.tsx                     # Create employee (8-tab wizard)
    │   └── [id]/
    │       ├── page.tsx                     # Employee detail view
    │       └── edit/page.tsx                # Edit employee wizard
    ├── kpi-templates/page.tsx               # KPI templates + items editor
    ├── kpi-cycles/
    │   ├── page.tsx                         # KPI cycles list
    │   └── [id]/dashboard/page.tsx          # Cycle dashboard
    ├── kpi-evaluations/
    │   ├── page.tsx                         # Evaluation list (scoped tabs)
    │   └── [id]/page.tsx                    # Evaluation workflow detail
    ├── probation-reviews/
    │   ├── page.tsx                         # Probation list + trigger
    │   └── [id]/page.tsx                    # Probation detail + actions
    ├── roles/page.tsx                       # Role CRUD + permissions
    ├── profile/page.tsx                     # User profile + password
    ├── notification-settings/page.tsx       # Channel settings (Admin/HR)
    └── actionable-items/page.tsx            # Actionable work queue
src/
├── context/auth.tsx                        # Auth state + permission helpers
├── lib/
│   ├── api.ts                              # Centralized API client (100+ functions)
│   ├── avatar.ts                           # Avatar initials helper
│   ├── lookups.ts                          # Country list
│   └── permission-labels.ts                # Human-readable permission names
├── types/index.ts                          # TypeScript interfaces (all API types)
└── components/
    ├── app-sidebar.tsx                      # Permission-aware navigation
    ├── page-header.tsx                      # Page header with notification bell
    ├── confirm-dialog.tsx                   # Reusable confirmation dialog
    ├── employees/                           # Employee wizard + tabs
    ├── kpi/                                 # KPI dialogs (template, cycle)
    ├── notifications/                       # Notification bell dropdown
    └── roles/                              # Role/permission dialogs
components/
└── ui/                                     # shadcn/ui primitives (18 components)

Key Conventions​

  • All pages use "use client" (client-side rendering).
  • API calls go through the centralized api.ts client with credentials: "include".
  • AuthProvider context provides can() and hasRole() for permission gating.
  • Forms use useState for state management; validation errors come from the API (422 responses).
  • All list pages follow the same pattern: filters, debounced search, paginated table, dialog-based CRUD.