# Dashboard & Notifications

This guide explains how the **customer dashboard** stays consistent and how **in-app notifications** are generated.

## Dashboard “single read model” (`/api/me/status`)

To keep business logic out of the frontend, the Portal uses a single BFF endpoint:

- **Endpoint**: `GET /api/me/status`
- **Purpose**: Return a consistent snapshot of the customer’s current state (summary + tasks + gating signals).
- **Domain type**: `@customer-portal/domain/dashboard` → `meStatusSchema`

The response includes:

- **`summary`**: Same shape as `GET /api/me/summary` (stats, next invoice, activity).
- **`internetEligibility`**: Internet eligibility status/details for the logged-in customer.
- **`residenceCardVerification`**: Residence card verification status/details.
- **`paymentMethods.totalCount`**: Count of stored payment methods (or `null` if unavailable).
- **`tasks[]`**: A prioritized list of dashboard tasks (invoice due, add payment method, order in progress, eligibility pending, IDV rejected, onboarding).

Portal UI maps task `type` → icon locally; everything else (priority, copy, links) is computed server-side.

## In-app notifications

In-app notifications are stored in Postgres and fetched via the Notifications API. Notifications use domain templates in:

- `packages/domain/notifications/schema.ts`

### Where notifications are created

- **Eligibility / Verification**:
  - Triggered from Salesforce events (Account fields change).
  - Created by the Salesforce events handlers.

- **Orders**:
  - **Approved / Activated / Failed** notifications are created during the fulfillment workflow:
    - `apps/bff/src/modules/orders/services/order-fulfillment-orchestrator.service.ts`
  - The notification `sourceId` uses the Salesforce Order Id to prevent duplicates during retries.

- **Cancellations**:
  - A “Cancellation scheduled” notification is created when the cancellation request is submitted:
    - Internet: `apps/bff/src/modules/subscriptions/internet-management/services/internet-cancellation.service.ts`
    - SIM: `apps/bff/src/modules/subscriptions/sim-management/services/sim-cancellation.service.ts`

- **Invoice due**:
  - Created opportunistically when the dashboard status is requested (`GET /api/me/status`) if an invoice is due within 7 days (or overdue).

### Dedupe behavior

Notifications dedupe is enforced in:

- `apps/bff/src/modules/notifications/notifications.service.ts`

Rules:

- For most types: dedupe is **type + sourceId within 1 hour**.
- For “reminder-style” types (invoice due, payment method expiring, system announcement): dedupe is **type + sourceId within 24 hours**.

### Action URLs

Notification templates use **authenticated Portal routes** (e.g. `/account/orders`, `/account/services`, `/account/billing/*`) so clicks always land in the correct shell.