# SoftSuite Company Management CMS / ERP

Production-oriented Laravel 13 application scaffold for SoftSuite Technologies. The project follows the approved specification: Laravel/PHP modular monolith, Blade UI, Alpine.js interactivity, MySQL, strict employee/intern separation, server-side IP-restricted attendance, projects/tasks, leave, payroll, stipends, expenses, assets, announcements, roles/permissions and audit logging.

## Included now
- Custom authentication and seeded roles
- Founder/management dashboard
- Separate `/employee` and `/intern` portals
- Separate Employee and Intern database tables and lifecycle fields
- Offices, shifts and multiple IP/CIDR whitelist rules
- Server-side attendance punch service with invalid-IP rejection log
- Attendance regularization data model
- Clients, projects, many-to-many project allocation, workload fields
- Tasks, collaborators, status history and work logs
- Leave types/requests
- Effective-dated employee salary revisions and payroll batch calculator
- Separate intern stipend batch/items schema
- Expense/reimbursement model with approval fields
- Assets, announcements and append-style audit logs
- Responsive Blade + Alpine.js UI foundation
- PHPUnit tests for IP/CIDR matching, rejected attendance and portal separation

## Install
```bash
cp .env.example .env
composer install
php artisan key:generate
# Set MySQL credentials in .env
php artisan migrate --seed
npm install
npm run build
php artisan serve
```

For local development with SQLite, set `DB_CONNECTION=sqlite` and `DB_DATABASE=/absolute/path/database/database.sqlite`, then create that file before migration.

## Seed accounts
All seeded users use password `Password@123` and are for local/demo environments only.
- Founder: `founder@softsuite.local`
- HR: `hr@softsuite.local`
- Finance: `finance@softsuite.local`
- Engineering manager: `lead@softsuite.local`
- Employee: `employee@softsuite.local`
- Intern: `intern@softsuite.local`

**Immediately replace/remove seeded credentials before any real deployment.**

## Attendance IP security
Attendance decisions are made in `app/Services/AttendanceService.php`. The backend loads the user's Employee/Intern profile, assigned office and active IP rules, logs every attempt, blocks unauthorized networks without creating an attendance record, prevents duplicate punches, and writes audit events.

The seeded whitelist contains `127.0.0.1` only for local testing. Add your real office **public** IP/CIDR to `office_ip_rules` in production.

If the application is behind Cloudflare, Nginx, a load balancer or another reverse proxy, configure Laravel/Symfony trusted proxies correctly before relying on `Request::ip()`. Never blindly trust arbitrary forwarded headers.

## Important production work still expected before go-live
This ZIP is a substantial application foundation and working core, but a real company deployment should still complete UI CRUD screens for every configuration entity, multi-step approval actions, payslip PDF generation, private document uploads, MFA, notifications, backup automation, exhaustive authorization policies, legal payroll/tax rules for your jurisdiction, payroll attendance calculations, browser/device testing and infrastructure hardening.

## Tests
```bash
php artisan test
```

The included tests target the highest-risk boundaries first: network attendance enforcement and Employee/Intern portal isolation.

## Production hardening additions
This build includes employee/intern CRUD, granular permissions and Policies, sequential approvals, advanced attendance policies, payroll adjustments/overtime/unpaid-leave/tax/advance calculations, PDF payslips, stipend batches, intern development, performance reviews, private HR documents, asset lifecycle, offboarding, queued notifications, reports/CSV/PDF exports, password reset, email verification, MFA, backup scheduling, deployment examples, and Playwright E2E tests.

Run `./scripts/verify-production-build.sh` on a CI machine with Composer, Node, MySQL and browser dependencies. For office attendance, configure `TRUSTED_PROXIES` only with your known reverse proxies and configure real office public IP/CIDR rules in Security & Roles.
