# Tailor Shop Management System – Production Documentation

**Project path:** `C:\Users\manus\Voters Rights Foundation\tailor`  
**Laravel:** 11.x | **PHP:** 8.2+ (8.3 recommended)

---

## 1. Installation Steps

### 1.1 Requirements

- PHP 8.2+ (8.3+ recommended; **PHP 7.4 will cause parse errors** in vendor packages)
- Composer 2.x
- Node.js 18+ and npm
- MySQL 8+ (or MariaDB equivalent)

### 1.2 Clone / extract and install dependencies

```bash
cd "C:\Users\manus\Voters Rights Foundation\tailor"
composer install
```

If the default `php` on your system is below 8.2, use your PHP 8.3 binary:

```powershell
& "C:\php\php-8.3-nts\php.exe" "C:\path\to\composer.phar" install
```

### 1.3 Laravel Breeze (Blade + Tailwind + Alpine)

```bash
php artisan breeze:install blade
```

Choose **Blade** when prompted. This adds `routes/auth.php`, login/register views, and Tailwind/Alpine.

### 1.4 Spatie Laravel Permission

```bash
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
```

### 1.5 Environment and database

```bash
copy .env.example .env
php artisan key:generate
```

Edit `.env`:

- `DB_CONNECTION=mysql`
- `DB_DATABASE=tailor_shop`
- `DB_USERNAME=...`
- `DB_PASSWORD=...`

Create the database, then:

```bash
php artisan migrate
```

### 1.6 Seeders

```bash
php artisan db:seed
```

Or seed only roles/permissions:

```bash
php artisan db:seed --class=RolePermissionSeeder
```

### 1.7 Storage link and frontend

```bash
php artisan storage:link
npm install
npm run dev
```

For production: `npm run build`.

### 1.8 Run the application

```bash
php artisan serve
```

Visit `http://localhost:8000`. Log in with the seeded Super Admin (see Seeders section).

---

## 2. Package List

| Package | Purpose |
|--------|---------|
| **laravel/framework** ^11.31 | Core framework |
| **laravel/tinker** ^2.9 | REPL |
| **spatie/laravel-permission** ^6.4 | Roles and permissions |
| **laravel/breeze** * (dev) | Auth scaffolding (Blade) |
| **fakerphp/faker** ^1.23 (dev) | Fake data for seeders |
| **laravel/pint** ^1.13 (dev) | Code style |
| **phpunit/phpunit** ^11 (dev) | Testing |

Optional (not in default composer.json; add if needed):

- **maatwebsite/excel** – Excel export for reports
- **barryvdh/laravel-dompdf** – PDF generation for invoices/job cards

---

## 3. Setup Instructions

### 3.1 After Breeze install

Breeze may overwrite `routes/web.php`. Ensure `routes/web.php` includes:

- Dashboard, settings, reports, trials, alterations, deliveries, orders, customers, branches, users, masters (garment categories, garment types, services, add-on services, urgent charges), and portal routes. See `routes/web.php` in the project.

### 3.2 Auth route

If you use Breeze’s auth routes, keep:

```php
if (file_exists($auth = __DIR__.'/auth.php')) {
    require $auth;
}
```

in `routes/web.php`.

### 3.3 Portal guest redirect

Unauthenticated visits to `/portal/*` redirect to the customer portal login. Configured in `bootstrap/app.php` via `redirectGuestsTo`.

### 3.4 Settings (shop name, currency, etc.)

After first login, go to **Settings** and configure shop name, logo, contact, address, prefixes, currency, tax, default delivery/trial days, invoice footer, and terms. Stored in `settings` table; see `app/Services/SettingsService.php` and `app/Http/Controllers/SettingsController.php`.

---

## 4. Seeder Instructions

### 4.1 Main seeder

```bash
php artisan db:seed
```

Runs `Database\Seeders\DatabaseSeeder`, which typically calls:

- `RolePermissionSeeder` – roles and permissions
- Other seeders (e.g. Phase seeders for branches, users, garment types, services, etc.) if registered

### 4.2 Role and permission seeder only

```bash
php artisan db:seed --class=RolePermissionSeeder
```

Creates:

- Permissions: user, branch, customer, measurement, order, trial, alteration, delivery, billing, payments, expenses, inventory, reports, settings
- Roles: Super Admin, Shop Owner, Branch Manager, Receptionist, Tailor, Delivery Staff, Accountant, Customer
- Super Admin user: `admin@tailorshop.com` / `password`

### 4.3 Demo data

Run the demo data seeder to create a main branch (if missing), sample customers, orders with items, and sample trials/alterations/deliveries:

```bash
php artisan db:seed --class=DemoDataSeeder
```

File: `database/seeders/DemoDataSeeder.php`. Requires at least one GarmentType and Service (from Phase3Seeder). Optionally add `$this->call(DemoDataSeeder::class);` in `DatabaseSeeder` to run it with `php artisan db:seed`.

### 4.4 Customer portal passwords

Customers need a `password` (and `remember_token`) to log into the portal. Either:

- Set passwords manually in the database or via an admin “Set portal password” action, or
- Implement a “set password” flow (e.g. token-based) and seed some customers with a known password for testing.

---

## 5. Queue Setup Instructions

The application does not require queues for basic operation. If you add queues later (e.g. for exports or emails):

### 5.1 Driver

In `.env`:

```env
QUEUE_CONNECTION=database
```

Or `redis` if you use Redis.

### 5.2 Database driver

```bash
php artisan queue:table
php artisan migrate
```

### 5.3 Worker

```bash
php artisan queue:work
```

For production, use a process manager (Supervisor) to keep the worker running.

### 5.4 Clearing dashboard cache

Dashboard metrics are cached for 5 minutes. To clear:

```php
app(\App\Services\DashboardMetricsService::class)->clearCache();
```

Or clear all cache: `php artisan cache:clear`.

---

## 6. PDF / Export Package Usage

### 6.1 Current state

- **PDF:** Not bundled by default. Job card and invoice PDFs can be implemented with **barryvdh/laravel-dompdf** or similar.
- **Excel:** Not bundled. Reports can be exported using **maatwebsite/laravel-excel** once installed.

### 6.2 Adding DomPDF (example)

```bash
composer require barryvdh/laravel-dompdf
```

Publish config (if provided):

```bash
php artisan vendor:publish --provider="Barryvdh\DomPDF\ServiceProvider"
```

In a controller, e.g. for invoice PDF:

```php
use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('invoices.pdf', compact('order', 'invoice'));
return $pdf->stream('invoice-' . $invoice->id . '.pdf');
```

Use the same filtered data as the report or invoice view to keep consistency.

### 6.3 Adding Laravel Excel (example)

```bash
composer require maatwebsite/excel
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config
```

Create an export class (e.g. `app/Exports/OrdersExport.php`) and in the report controller add an `export` parameter or button that returns the export. Reuse the same query/scopes as the report for consistency.

---

## 7. Key File Paths

| Purpose | Path |
|--------|------|
| Admin layout | `resources/views/layouts/admin.blade.php` |
| Sidebar | `resources/views/layouts/partials/sidebar.blade.php` |
| Navbar | `resources/views/layouts/partials/navbar.blade.php` |
| Reusable components | `resources/views/components/` (alert, badge, card, empty-state, stat-card, confirm-button) |
| Dashboard view | `resources/views/dashboard.blade.php` |
| Dashboard metrics (cached) | `app/Services/DashboardMetricsService.php` |
| Settings | `app/Http/Controllers/SettingsController.php`, `app/Services/SettingsService.php`, `app/Models/Setting.php` |
| Reports | `app/Http/Controllers/ReportController.php`, `app/Services/ReportService.php` |
| Orders (branch isolation) | `app/Http/Controllers/OrderController.php` – `authorizeOrderBranch()` |
| File upload validation | `app/Http/Requests/StoreOrderAttachmentRequest.php` |
| Portal auth | `app/Http/Controllers/PortalAuthController.php`, `app/Http/Controllers/CustomerPortalController.php` |
| Auth config (customer guard) | `config/auth.php` |
| Guest redirect (portal) | `bootstrap/app.php` – `redirectGuestsTo` |
| Performance indexes | `database/migrations/2025_03_24_000001_add_performance_indexes.php` |
| Roles & permissions seeder | `database/seeders/RolePermissionSeeder.php` |

---

## 8. Future Enhancement Notes

- **Order policy:** Add `App\Policies\OrderPolicy` and register in `AuthServiceProvider` for consistent view/update/delete and optional branch scoping at policy level.
- **Invoicing module:** Full invoice CRUD, PDF generation, and link to payments.
- **Expense module:** CRUD and reporting (per branch, category, date).
- **Inventory/stock:** If applicable, add stock tracking and low-stock alerts.
- **Customer portal:** “Set password” flow from admin; optional email verification.
- **Exports:** Implement Excel/PDF exports in report controllers using the same filters as the UI.
- **Queue:** Use queues for heavy report exports and notification emails.
- **Audit log:** Optional logging of order status changes and sensitive actions.
- **Multi-currency:** If needed, extend settings and store currency per order or branch.
- **API:** If a mobile app or third-party integration is needed, add `routes/api.php` and sanctum or API tokens.

---

## 9. QA Checklist (Summary)

- **Modules:** Dashboard, Branches, Users, Customers, Measurement Templates, Measurement Profiles, Garment Categories, Garment Types, Services, Add-on Services, Urgent Charges, Orders, Trials, Alterations, Deliveries, Reports, Settings, Customer Portal.
- **Menus:** Sidebar links point to correct routes (`dashboard`, `branches.index`, `users.index`, `customers.index`, `measurement-templates.index`, `orders.index`, `trials.index`, `alterations.index`, `deliveries.index`, `reports.index`, `settings.edit`, `portal.login`).
- **Permissions:** All relevant controllers use `$this->authorize(...)`; branch-restricted users are limited by `authorizeOrderBranch` or equivalent and query scopes.
- **Validation:** Form requests used for order, customer, user, branch, settings, order attachment, order note, etc.; Trial/Alteration/Delivery use inline validation (can be moved to form requests).
- **Empty states:** List views can use `<x-empty-state>` for empty tables.
- **Destructive actions:** Delete order (and similar) can use `<x-confirm-button>` for confirmation.

---

*Last updated for production polish and Laravel 11 Tailor Shop.*