# NGBVD v3 Revamp Notes

## Scope implemented

This package refactors the attached NGBVD v3 codebase toward maintainable Laravel practice without introducing a full rewrite.

### Backend structure

Added a cleaner separation of responsibilities:

- `app/Http/Requests/DataEntry/*` for form validation
- `app/Services/DataEntry/CaseIntakeService.php` for guarded case-save workflows
- `app/Services/DataEntry/ReferenceDataService.php` for dropdown/reference-data loading and case listing
- `app/Services/Api/ApiTokenService.php` for API token issuance/validation
- `app/Services/Api/ExternalIncidentService.php` for external system incident submission
- `app/Repositories/BaseRepository.php` with standard methods:
  - `getAll()`
  - `paginate()`
  - `getById()`
  - `save()`
  - `update()`
  - `delete()`

### Defensive save behaviour

All critical case-entry saves are now routed through `CaseIntakeService`, and each workflow uses `DB::transaction()` and `saveOrFail()` through the repository. If any insert fails in a multi-record operation, Laravel rolls back the transaction.

### Controllers shortened

`DataEntryController` and `ApiController` were refactored to delegate validation, reference-data loading, business rules and saving to request/service classes.

### UI/UX revamp

Added:

- `public/assets/css/ngbvd-modern.css`
- `resources/views/components/page-header.blade.php`

Updated:

- `resources/views/layouts/app.blade.php`
- `resources/views/dataentry/index.blade.php`
- `resources/views/dataentry/update.blade.php`

The revamp improves login layout, form focus states, buttons, page cards, tabs, tables and general government-grade visual consistency while keeping the existing Blade structure.

### API readiness

API logic is now separated from the controller into services. Token handling is safer because plain tokens are not stored. The process-data endpoint validates after token validation and uses the same guarded case-intake service.

## UUID primary-key migration

Added:

- `app/Models/Concerns/UsesUuidPrimaryKey.php`
- `config/ngbvd.php`
- `database/migrations/2026_06_02_000001_convert_core_ngbvd_tables_to_uuid_primary_keys.php`

The UUID trait is disabled by default. Keep this in `.env` until migration is completed:

```env
NGBVD_UUID_PRIMARY_KEYS=false
```

After successful UUID migration on a backup/restored database, enable:

```env
NGBVD_UUID_PRIMARY_KEYS=true
```

## Important UUID warning

Do not run the UUID migration directly on production. The attached SQL dump is large and includes historical/copy tables. The migration intentionally targets live application workflow tables, not archive tables.

Recommended sequence:

1. Take database backup.
2. Restore backup to staging.
3. Run migration in staging.
4. Compare record counts between old and migrated tables.
5. Test login, data entry, reports and API submission.
6. Only then plan a production maintenance window.

## Test first

After applying the package:

```bash
composer dump-autoload
php artisan optimize:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan migrate --pretend
```

Then test:

1. Login page loading and login submission
2. Dashboard page loading
3. Data entry page loading
4. Survivor save
5. Incident save
6. Perpetrator save
7. Witness save
8. Action/services save
9. Case status save
10. API token issue
11. API incident submission
12. API incident statistics

## Known intentional decisions

- Existing Blade forms were not replaced with a SPA because that would be over-engineering for this government system.
- Existing workflow routes were preserved.
- External system publishing should remain out of normal UI save flows. API and integration services should handle Sauti/GBV Portal data exchange.
- UUID conversion is staged and configuration-controlled to avoid breaking existing integer-key deployments before migration.