# NGO ERP (SenedERP)

Multi-tenant NGO operations software: grants and budgets as the hub, HR (leave, attendance, payroll), procurement, approvals, travel, hiring, and workspace settings.

**Backend:** Laravel (REST API under `routes/api.php`).  
**Web UI:** **Laravel Blade** + **Tailwind CSS v4** via **Vite** at the repository root (`package.json`). Session auth is under `routes/web.php` (`/login`, `/me`, `/dashboard`, and module stubs from `config/web_surfaces.php`).

**Arabic product guide** (workflows, forms, modules): see [README.ar.md](README.ar.md).

## Repository layout

| Path | Purpose |
|------|---------|
| `app/`, `routes/`, `database/` | Laravel application, APIs, migrations, seeders |
| `resources/views/`, `resources/css/`, `resources/js/` | Blade UI, Tailwind, Vite entry |
| `config/web_surfaces.php` | Registers many GET routes mirrored from the former SPA URLs |
| `config/payroll/rules/` | Country payroll rulesets (YAML), e.g. Türkiye `TR_2026.yaml` |
| `packages/` | Optional Composer packages (e.g. scoped RBAC scaffold) |

## Requirements

- PHP 8.2+, [Composer](https://getcomposer.org/)
- Node.js 20+ for **root** `npm ci` / `npm run dev` / `npm run build` (Vite + Tailwind for Blade)
- MySQL or SQLite for local development

## Quick start (local)

1. **Environment**

   ```bash
   cp .env.example .env
   php artisan key:generate
   composer install
   ```

   Set **`APP_URL`** (e.g. `http://localhost:8000`). **`FRONTEND_URL`** defaults to the same URL and is still used where the app emits absolute links for invitations, etc.; keep it aligned with **`APP_URL`**.

2. **Database**

   ```bash
   php artisan migrate
   ```

3. **Web assets (Blade)**

   ```bash
   npm ci
   npm run dev
   ```

   Or for production builds: **`npm run build`** (writes to `public/build`, gitignored).

4. **Run the app**

   ```bash
   php artisan serve
   ```

   Open **`APP_URL`**, sign in at **`/login`**, employee home at **`/me`** (session guard).

Adjust `.env` for your database and mail settings as needed.

## Scheduled tasks (production)

Laravel’s scheduler runs background jobs defined in `bootstrap/app.php`. **Production** must invoke it every minute, for example:

```bash
* * * * * cd /path/to/ngoerp && php artisan schedule:run >> /dev/null 2>&1
```

**Local development:** run `php artisan schedule:work` in a separate terminal to process scheduled commands continuously.

Included jobs:

| Command | Schedule | Purpose |
|---------|----------|---------|
| `procurement:monitor-match-sla` | Hourly | Escalates overdue supplier-invoice 3-way match exceptions and sends throttled reminders |

After pulling procurement NGO-gap migrations, run:

```bash
php artisan migrate
```

When RBAC is enabled, grant **Procurement — Vendors** (read/update) to functional roles that manage purchasing (demo seeders assign these to finance/procurement roles; existing tenants get vendor privileges via migration `2026_06_09_120020_assign_procurement_vendor_privileges_to_procurement_roles.php` when their role already has purchase-request view).

## Security

Do not commit `.env` or production secrets. This repository’s `.gitignore` excludes common sensitive paths.

## License

Application code is provided as-is for this project; third-party frameworks retain their respective licenses.
