# HRMS SaaS Platform - Laravel 12

Multi-tenant HRMS (Human Resource Management System) built with Laravel 12, single-database tenancy, and modular architecture.

## Tech stack
- **Laravel 12**
- **MySQL**
- **Laravel Sanctum** (API auth)
- **Spatie Laravel Permission** (roles/permissions – optional; schema uses `roles`, `permissions`, `role_user`, `permission_role`)
- **Blade + Inertia** (Inertia installed; Blade used for minimal web routes)
- **REST API**

## Multi-tenancy
- **Single database**: one app, one DB, all tenant data in the same schema.
- **Tenant = Company**: each tenant is a row in `companies`.
- **Scoping**: tenant data is scoped by `company_id` via:
  - **CompanyScope** (global scope on models)
  - **CompanyResolver** (resolves current company from authenticated user)
  - **TenantMiddleware** (sets tenant context on API requests)
- Non–super-admin users only see data for `auth()->user()->company_id`.

## Super admin
- Users with `is_superadmin = 1` can:
  - Manage companies (CRUD, suspend)
  - Manage subscription plans
  - View platform analytics
  - Manage payments (via `payment_transcations` and related logic)
- Super admins are not restricted by `company_id` for platform resources.

## Setup

### 1. Install dependencies
```bash
composer install
```

### 2. Environment
```bash
cp .env.example .env
php artisan key:generate
```
Configure `.env` with your MySQL database (e.g. `DB_DATABASE=kiyohr_live_sass`).

### 3. Database
**Option A – Use existing schema (SQL dump)**  
Import your existing database (e.g. `kiyohr_live_sass.sql`). Migrations are written to skip creating tables that already exist, so you can still run:

```bash
php artisan migrate
```

**Option B – Fresh install**  
Run migrations only:

```bash
php artisan migrate
```

### 4. Seed (optional)
```bash
php artisan db:seed
```
Seeds roles, permissions, subscription plans, and default leave types.

## Project structure

### App
- **Models**: `App\Models` – User, Company, Role, Permission, Attendance, Leave, Payroll, etc., with `BelongsToCompany` and `CompanyScope` where needed.
- **Services**: `App\Services\CompanyResolver` – resolves current company for the request.
- **Middleware**: `TenantMiddleware`, `EnsureSuperAdmin`, and (in SaaS module) `CheckSubscriptionActive`.

### Modules (under `Modules/`)
- **Attendance** – Clock in/out, work durations, `AttendanceService`.
- **Employees** – Employee CRUD (tenant-scoped).
- **Leave** – Leave applications and listing.
- **Payroll** – Payroll listing and “my payslip”.
- **SaaS** – Subscription status, `CheckSubscriptionActive`, and Super Admin: companies, subscription plans, analytics.

Each module can contain (or be extended with) Controllers, Models, Services, Repositories, Policies, and Form Requests.

## API

- **Auth**: `POST /api/auth/login`, `POST /api/auth/logout`, `GET /api/auth/user`.
- **Employees**: `GET/POST /api/employees`, `GET/PUT/DELETE /api/employees/{id}` (tenant-scoped).
- **Attendance**: `GET /api/attendance/today`, `POST /api/attendance/clock-in`, `POST /api/attendance/clock-out`, `GET /api/attendance`, `GET /api/attendance/{id}`.
- **Leaves**: `GET/POST /api/leaves`, `GET/PUT/DELETE /api/leaves/{id}`.
- **Payroll**: `GET /api/payroll`, `GET /api/payroll/my-payslip`, `GET /api/payroll/{id}`.
- **Subscription**: `GET /api/subscription/status` (tenant + subscription middleware).
- **Super Admin**: use the web UI under `/superadmin/*` (companies, plans, payments, etc.).

All relevant routes use `auth:sanctum` and, where applicable, `tenant` and `subscription` or `superadmin` middleware.

See **docs/API.md** for full API documentation. For end-user workflows (leave, payroll, tax, offboarding), see **docs/USER_GUIDE.md**.

## Security
- **Policies**: Can be added per resource (e.g. LeavePolicy, PayrollPolicy).
- **Form Requests**: Use for validation in controllers (e.g. StoreLeaveRequest).
- **Tenant isolation**: Enforced by `CompanyScope` and `TenantMiddleware`; super admin is the only exception for platform-wide data.
- **Rate limiting**: Can be applied to API routes via Laravel’s throttle middleware.

## Background work (no queues)

- This app **does not use Laravel jobs or queues**. Notifications and post-request side effects run via `App\Support\AfterResponse` (`defer()` after the HTTP response).
- Prefer `QUEUE_CONNECTION=sync` so nothing is accidentally enqueued.
- Scheduled work uses Artisan commands (e.g. `leads:send-due-followup-reminders`), not queue jobs.

## Tests
```bash
composer test
# or
./vendor/bin/phpunit
```
Feature tests include auth (login, profile). Add more tests for attendance, leave, payroll, and subscriptions as needed.

## Scalability
- Single-database design is suitable for thousands of companies with proper indexing on `company_id` and connection pooling.
- Use Redis for cache in production if needed.
- Consider read replicas and splitting heavy reporting to dedicated tables as the dataset grows.

## License
MIT.