# Enterprise Workforce SaaS

Multi-tenant Attendance, Payroll, HRM, and Workforce Management platform scaffold.

## Architecture

- `backend/` Laravel API application structure with tenant-aware routes, migrations, services, and policies.
- `frontend/` Vue 3 + Vite + Tailwind SPA structure for Super Admin and Client portals.
- `device-service/` Node.js service scaffold for ZKTeco cloud/device communication.
- `docker-compose.yml` local cloud-ready services for MySQL, Redis, backend, frontend, and device service.

## Core Capabilities Covered

- SaaS tenants/clients, subscriptions, packages, module feature gates, and usage limits.
- Role and permission-ready API design.
- Branch, department, designation, employee, device, attendance, shift, leave, payroll, finance, task, contract, and disciplinary schemas.
- Attendance and payroll engine service boundaries.
- Dynamic rule engine data model for conditions, actions, priority, and automatic deductions.
- Realtime-ready dashboard contract for attendance logs, devices, and workforce metrics.
- ZKTeco device service API contract for registration, log sync, employee push, and remote restart.

## Local Requirements

Install these before running the application:

- PHP 8.2+
- Composer
- Node.js 20+
- npm
- MySQL 8+
- Redis

## Quick Start

### Local Runnable Preview

This repository currently includes a runnable PHP preview API plus the Vue dashboard.

Start the backend API:

```bash
cd backend
php -S 127.0.0.1:8000 -t public
```

Start the frontend:

```bash
cd frontend
npm install
npm run dev -- --host 127.0.0.1
```

Browse:

- Frontend: `http://127.0.0.1:5173`
- API health: `http://127.0.0.1:8000/api/health`
- Super Admin API: `http://127.0.0.1:8000/api/super-admin/dashboard`
- Client API: `http://127.0.0.1:8000/api/client/dashboard`

On Windows, if `node` or `npm` is installed but not on PATH, run PowerShell commands with:

```powershell
$env:Path = "C:\Program Files\nodejs;$env:Path"
```

### Full Laravel Target

```bash
cd backend
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan serve
```

```bash
cd frontend
npm install
npm run dev
```

```bash
cd device-service
npm install
npm run dev
```

## Production Notes

- Use one database with `tenant_id` isolation for operational simplicity, or replace the tenant resolver with a database-per-tenant strategy for high-compliance clients.
- All tenant-scoped tables include `tenant_id` and should be protected by middleware and global scopes in implementation.
- Use queues for attendance processing, payroll generation, report exports, invoice notifications, and device sync.
- WebSocket events should broadcast dashboard metrics, device status, attendance logs, and payroll progress.
- Device credentials and API tokens must be stored encrypted.
