Architecture Overview

The HRMS is a two-tier web application consisting of a Laravel API backend and a Next.js frontend, communicating over REST JSON APIs with cookie-based session authentication.

System Diagram

┌──────────────────────────────┐         ┌──────────────────────────────┐
│        HRMS Frontend         │         │        HRMS Backend          │
│        (hrms-web)            │  HTTP   │        (hrms-api)            │
│                              │◄───────►│                              │
│  Next.js 16 (App Router)    │  JSON   │  Laravel 12                  │
│  React 19 + TypeScript 5    │         │  PHP 8.2+                    │
│  Tailwind CSS v4             │         │  PostgreSQL                  │
│  shadcn/ui Components        │         │  Spatie RBAC                 │
│                              │         │  Laravel Sanctum             │
│  http://localhost:3000       │         │  http://localhost:8000       │
└──────────────────────────────┘         └──────────┬───────────────────┘
                                                    │
                                         ┌──────────▼───────────────────┐
                                         │        PostgreSQL            │
                                         │        hrms-db               │
                                         └─────────────────────────────┘

Technology Stack

Layer	Technology	Version
Backend Framework	Laravel	12.x
Backend Language	PHP	8.2+
Database	PostgreSQL	15+
Authentication	Laravel Sanctum	4.x
Authorization (RBAC)	Spatie Laravel Permission	6.x
API Documentation	Scramble (Dedoc)	0.13.x
Backend Testing	PHPUnit	11.x
Frontend Framework	Next.js (App Router)	16.x
Frontend UI Library	React	19.x
Frontend Language	TypeScript	5.x
CSS Framework	Tailwind CSS	4.x
UI Component Library	shadcn/ui	Latest

Key Architecture Decisions

Decision	Choice	Rationale
API Style	RESTful JSON API	Simple, well-understood, suitable for CRUD-heavy operations
Authentication	Cookie-based SPA via Sanctum	Secure, no token management on frontend, CSRF protection built in
RBAC	Spatie Laravel Permission	Industry-standard role + permission model with middleware support
Frontend Rendering	Client-side (CSR)	SPA-style with cookie auth; no SSR needed for internal admin dashboard
Component Library	shadcn/ui	Copy-paste components, fully customizable, Tailwind-native
Database	PostgreSQL	Production-grade, supports advanced queries, JSON columns
Separate repositories	hrms-api + hrms-web	Independent deployment, clear separation of concerns

Data Flow

Browser → Frontend (Next.js, port 3000)
    ↕ Cookie-based auth (Sanctum session cookie)
API Server (Laravel, port 8000)
    ↕ Eloquent ORM
PostgreSQL Database (hrms-db)

1. The frontend is a client-side rendered SPA.
2. All API calls use credentials: "include" to send session cookies automatically.
3. The backend validates the session cookie on every request via Sanctum middleware.
4. Authorization is enforced by Laravel Policies backed by Spatie permissions.
5. The frontend reads the user's permissions from GET /api/me and conditionally renders UI elements.

Core Design Patterns

Pattern	Where Used
Form Request validation	All mutation endpoints (47 FormRequest classes)
Policy authorization	All controllers (7 policy classes)
API Resource transformers	All responses (25 resource classes)
Service layer	Workflow logic (KPI, Probation, Notifications)
Transaction + pessimistic locking	All workflow mutations
Snapshot pattern	KPI evaluations and probation records preserve historical data
Polymorphic audit trail	All workflow actions logged to audit_events
Consistent response envelope	{ data, message, meta? } across all endpoints