# Push Notification Integration Plan

## Current state

The codebase already has partial Firebase push support:

- FCM token registration is already handled in [app/Http/Controllers/Api/AuthController.php](app/Http/Controllers/Api/AuthController.php)
- Device tokens are stored in [app/Models/UserDeviceToken.php](app/Models/UserDeviceToken.php)
- Firebase sending is already implemented in [app/Services/PushNotificationService.php](app/Services/PushNotificationService.php)
- Some project and payout events already trigger push messages in:
  - [app/Http/Controllers/Api/App/ProjectController.php](app/Http/Controllers/Api/App/ProjectController.php)
  - [app/Http/Controllers/Api/App/PayoutRequestController.php](app/Http/Controllers/Api/App/PayoutRequestController.php)
  - [app/Http/Controllers/Api/TenantAdmin/ProjectController.php](app/Http/Controllers/Api/TenantAdmin/ProjectController.php)
  - [app/Http/Controllers/Api/TenantAdmin/PayoutRequestController.php](app/Http/Controllers/Api/TenantAdmin/PayoutRequestController.php)
  - [app/Http/Controllers/Api/TenantAdmin/PaymentController.php](app/Http/Controllers/Api/TenantAdmin/PaymentController.php)

## Main gaps

The current implementation sends push messages directly, but it does not yet provide:

1. Notification history storage in the database
2. Notification list API
3. Read/unread status APIs
4. A unified event-to-recipient mapping for tenant-admin and service-user flows
5. A clean, scalable notification service that can support future events

## Proposed architecture

### 1. Database layer

Create a notification table to persist every in-app notification.

Suggested fields:

- id
- tenant_id
- recipient_user_id
- actor_user_id nullable
- event_type
- title
- body
- data json nullable
- is_read boolean default false
- read_at timestamp nullable
- created_at / updated_at

Optional helper table (if needed later):

- notification_recipients

For the first implementation, a single notifications table is enough and keeps the rollout simple.

### 2. Model and service layer

Add:

- [app/Models/Notification.php](app/Models/Notification.php)
- [app/Services/NotificationService.php](app/Services/NotificationService.php)

Responsibilities:

- create a database record
- resolve the correct recipient user IDs
- send push via [app/Services/PushNotificationService.php](app/Services/PushNotificationService.php)
- support read/unread updates
- expose unread count

### 3. API layer

Add shared notification endpoints for both roles.

Suggested routes:

- GET /api/app/notifications
- GET /api/tenant-admin/notifications
- PATCH /api/app/notifications/{id}/read
- PATCH /api/tenant-admin/notifications/{id}/read
- PATCH /api/app/notifications/read-all
- PATCH /api/tenant-admin/notifications/read-all
- GET /api/app/notifications/unread-count
- GET /api/tenant-admin/notifications/unread-count

The response should include:

- id
- title
- body
- event_type
- data
- is_read
- created_at

### 4. Recipient rules

#### Project events

- Service user creates a new project:
  - notify all tenant admins in the tenant
- Tenant admin assigns a project to a service user:
  - notify only the assigned service user
- Project status changes (approved, rejected, completed, etc.):
  - notify the assigned service user and the project creator if different
  - optionally also notify tenant admins for high-priority changes such as approval/rejection

#### Payout events

- Service user creates a payout request:
  - notify all tenant admins
- Tenant admin approves or rejects payout request:
  - notify the requesting service user
- Tenant admin records payment received:
  - notify the assigned service user for that project

#### General rule

Use a single rule engine in NotificationService so the recipient selection is consistent and extendable for future events.

## Recommended implementation steps

1. Create the notifications migration and model
2. Add NotificationService with methods such as:
   - notifyUsers(array $userIds, string $eventType, string $title, string $body, array $data = [])
   - notifyTenantAdmins(int $tenantId, ...)
   - notifyProjectParticipants(Project $project, ...)
3. Replace direct push-only calls in the controllers with NotificationService calls
4. Add notification API controllers and routes
5. Add read/unread support and unread count
6. Add feature tests for:
   - project created -> admin notification
   - project assigned -> assignee notification
   - payout created -> admin notification
   - payout approved/rejected -> service-user notification
   - payment received -> service-user notification
7. Add frontend integration for list display and unread badge

## Suggested event types

- project_created
- project_assigned
- project_approved
- project_rejected
- project_completed
- payout_request_created
- payout_request_approved
- payout_request_rejected
- payment_received
- payment_comment

## Acceptance criteria

- A notification is stored in the database for every important admin/user interaction
- The correct recipient(s) receive the notification
- The mobile app can fetch notification history
- The user can mark notifications as read
- Unread count is available
- Push notification and in-app notification both work from the same event source

## Suggested rollout order

1. Notifications table + model + service
2. Project events
3. Payout/payment events
4. Notification list/read APIs
5. Frontend integration and unread badge