# Tarnova Filament Migration Plan

This app is currently a custom Blade/controller invoicing product. Filament is not installed yet. The first Composer dry-run showed that PHP `ext-intl` must be enabled before Filament can be installed cleanly.

## Current blocker

Enable PHP Intl for the CLI and web PHP runtime before installing Filament:

```bash
php -m | grep intl
```

On Windows, enable `extension=intl` in the active `php.ini`, then restart the terminal/PHP service and rerun:

```bash
composer require filament/filament --dry-run
```

Do not install Filament with `--ignore-platform-req=ext-intl` for production. That would hide a real runtime requirement.

## Migration approach

Use Filament side-by-side first. Do not replace the current customer/public flows immediately.

Keep these existing custom flows outside Filament until the admin panel is proven:

- Public invoice links and Pay Now
- Public quotation accept/decline
- Public statement acknowledge/query
- PDF rendering
- Email/reminder delivery services
- MFA and session management unless intentionally rebuilt

## Filament navigation groups

The current app navigation has been centralized in `App\Support\Navigation\TarnovaNavigation` so it can later inform Filament resource navigation.

Recommended Filament groups:

### Sales

Initial resources/pages:

- `InvoiceResource`
- `QuotationResource`
- `RecurringInvoiceResource`
- `CreditNoteResource`

Do not expose low-level line item models as top-level sidebar items:

- `InvoiceItem`
- `QuotationItem`
- `RecurringInvoiceItem`

Those should remain relation managers inside their parent documents.

### Finance

Initial resources/pages:

- `PaymentResource`
- Payments & Collections dashboard page
- CSV/report export page if needed

Do not create a separate Tax resource yet. VAT is currently a company setting and document field, not a full tax-rate table.

### Clients

Initial resources/pages:

- `ClientResource`
- Client statement page/action

`ClientStatementResponse` should not be a normal sidebar resource. It is response/audit-style data connected to public statement links.

### Administration

Initial resources/pages:

- `UserResource`
- `AuditLogResource` as read-only
- Security/account pages if intentionally migrated later

### Settings

Initial pages:

- Company settings page
- Branding/logo settings
- Banking details
- Reminder settings
- Theme settings

`CompanySetting` should likely be a single settings page, not a normal CRUD resource.

## Should Vendor or Tax be added?

Not yet.

### Vendor

Add `Vendor` only when Tarnova supports expenses, supplier bills, purchase orders, or accounts payable. Today the app is customer invoicing/receivables-focused, so adding Vendor now would create unused navigation and confusing scope.

### Tax

Add a `TaxRate` or `TaxCode` model only if the app needs multiple VAT rates, exempt/zero-rated items, per-line tax codes, or jurisdiction-specific reporting. Today the app uses one company default VAT rate plus stored document totals, so a sidebar Tax module would be premature.

## First Filament resources to build

Build in this order:

1. `ClientResource`
2. `InvoiceResource` with item relation manager and payment/credit note relation panels
3. `QuotationResource` with conversion action
4. `PaymentResource` with approve/reject EFT actions
5. `CreditNoteResource` with issue/apply actions
6. `RecurringInvoiceResource`
7. `AuditLogResource` read-only
8. Company settings page

## Guardrails

- Keep existing route names working during migration.
- Keep public client routes outside Filament.
- Reuse current services for money logic, delivery, lifecycle, and audit logging.
- Do not duplicate financial rules inside Filament resources.
- Enforce authorization in policies/gates, not only hidden buttons.
- Run existing feature tests after each resource migration.