Local Setup

This guide walks you through setting up the HRMS backend (API), frontend (web), and documentation site on your local machine.

Prerequisites

Software	Minimum Version	Purpose
PHP	8.2+	Laravel backend runtime
Composer	2.x	PHP dependency manager
PostgreSQL	15+	Database
Node.js	20+	Frontend and docs build
npm	10+	Frontend package manager

Recommended tools:

• Laragon (Windows) — bundles PHP, PostgreSQL, Apache/Nginx
• TablePlus or pgAdmin — database GUI
• VS Code — editor

---

Backend Setup (hrms-api)

1. Install dependencies

cd c:\laragon\www\hrms-api
composer install

2. Create the database

CREATE DATABASE "hrms-db";

3. Configure environment

cp .env.example .env
php artisan key:generate

Update these values in .env:

APP_URL=http://localhost:8000

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=hrms-db
DB_USERNAME=postgres
DB_PASSWORD=your_password_here

SESSION_DRIVER=cookie
SESSION_DOMAIN=localhost

SANCTUM_STATEFUL_DOMAINS=localhost:3000,127.0.0.1:3000
FRONTEND_URL=http://localhost:3000

# Email (smtp4dev for local testing)
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS=hrms@local.test
MAIL_FROM_NAME="HRMS Local"
NOTIFICATIONS_EMAIL_ENABLED=true

4. Run migrations and seed data

php artisan migrate:fresh --seed

This creates all tables, seeds roles/permissions, and creates test users.

5. Create storage symlink

php artisan storage:link

Required for serving uploaded files (profile pictures, attachments).

6. Start the backend

php artisan serve

The API runs at http://localhost:8000.

7. Verify

curl http://localhost:8000/sanctum/csrf-cookie -v
# Should return 204 No Content with Set-Cookie headers

---

Frontend Setup (hrms-web)

1. Install dependencies

cd c:\laragon\www\hrms-web
npm install

2. Configure environment

Create .env.local:

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

3. Start the frontend

npm run dev

The frontend runs at http://localhost:3000.

---

Running Both Services

Both must be running simultaneously in separate terminals:

Terminal	Command	URL
Terminal 1	cd hrms-api && php artisan serve	http://localhost:8000
Terminal 2	cd hrms-web && npm run dev	http://localhost:3000

Verify the full setup

1. Open http://localhost:3000 in your browser.
2. Log in with a test account (see below).
3. You should see the Dashboard with statistics cards.

---

Seeded Test Accounts

Email	Password	Role
admin@local.test	Password123!	Admin
hr@local.test	Password123!	HR
manager@local.test	Password123!	Manager
teamlead@local.test	Password123!	TeamLead
employee@local.test	Password123!	Employee

All accounts belong to the seeded entity Hayo Pvt Ltd. A second entity Slick Solutions is also seeded with sample departments and employees.

---

Local Email Testing (smtp4dev)

1. Install and start smtp4dev.
2. Ensure the backend .env has MAIL_HOST=127.0.0.1, MAIL_PORT=2525, and NOTIFICATIONS_EMAIL_ENABLED=true.
3. Clear the config cache and restart:

php artisan config:clear
php artisan serve

4. Trigger notification events (create employee, assign reviewer, submit review, etc.).
5. Check the smtp4dev web UI for received emails.

---

Running Tests

Backend (PHPUnit)

cd hrms-api
php artisan test

Tests use an in-memory SQLite database for speed and isolation. Current suite: 392 passing tests.

Frontend (Vitest)

cd hrms-web
npm run test

---

Environment Variables Reference

Backend (.env)

Variable	Required	Description
APP_URL	Yes	Backend base URL
DB_CONNECTION	Yes	pgsql
DB_HOST / DB_PORT / DB_DATABASE	Yes	PostgreSQL connection
DB_USERNAME / DB_PASSWORD	Yes	Database credentials
SESSION_DRIVER	Yes	cookie
SESSION_DOMAIN	Yes	localhost
SANCTUM_STATEFUL_DOMAINS	Yes	Frontend origins (comma-separated)
FRONTEND_URL	Yes	Frontend URL for CORS
MAIL_MAILER	Yes	smtp
MAIL_HOST / MAIL_PORT	Yes	SMTP server
MAIL_FROM_ADDRESS / MAIL_FROM_NAME	Yes	Sender identity
NOTIFICATIONS_EMAIL_ENABLED	Yes	Enable/disable email notifications

Frontend (.env.local)

Variable	Required	Description
NEXT_PUBLIC_API_BASE_URL	Yes	Backend API URL (e.g., http://localhost:8000)

---

API Documentation (Auto-Generated)

With the backend running, visit:

http://localhost:8000/docs/api

This provides an interactive Swagger-style interface powered by Dedoc Scramble. The OpenAPI 3.1 JSON spec is available at /docs/api.json.