> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taxhomebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> 10 alert types with severity levels, email digest, and auto-resolution.

TaxHomeBase monitors your compliance status and sends alerts when action is needed. Notifications are available on all plans.

## Alert Types

| Type                  | Severity       | Triggers When                                         |
| --------------------- | -------------- | ----------------------------------------------------- |
| `stipend_risk`        | Danger         | Tax home compliance issues jeopardize stipends        |
| `itinerant_risk`      | Info           | Stipend eligibility at 4/6 criteria (borderline)      |
| `property_rented_out` | Warning        | Tax home property is rented to tenants                |
| `long_assignment`     | Warning        | Any assignment exceeds 45 weeks                       |
| `visit_overdue`       | Warning        | >30 days since last tax home visit                    |
| `missing_docs`        | Info           | Tax home documents not uploaded                       |
| `gsa_exceeds`         | Warning        | Assignment stipends exceed GSA per diem limits        |
| `credential_expiring` | Warning/Danger | Credential expiring within 90 days or already expired |
| `quarterly_overdue`   | Danger         | Quarterly payment past due date                       |
| `quarterly_due`       | Warning        | Quarterly payment due within 14 days                  |

## Severity Levels

| Level       | Color | Meaning                                    |
| ----------- | ----- | ------------------------------------------ |
| **Danger**  | Red   | Immediate action required — financial risk |
| **Warning** | Amber | Action needed soon                         |
| **Info**    | Blue  | For your awareness                         |

## How Notifications Are Generated

Notifications are computed by `alertService.js` — a pure function that evaluates your data and produces a list of alerts. Sync happens in two ways:

### On Login

When you sign in, a fire-and-forget `POST /notifications/sync` runs in the background. This ensures your alerts are current every time you open the app.

### Daily Background Job

A cron job runs at 8am daily for all users:

1. Fetches each user's data (tax home, assignments, expenses, credentials, quarterly payments)
2. Computes alerts
3. Syncs to the database
4. Sends an email digest to users with email notifications enabled

## Auto-Resolution

When the underlying issue is fixed, the alert auto-resolves on the next sync. For example:

* Update your visit date → `visit_overdue` resolves
* Upload tax home docs → `missing_docs` resolves
* Record a quarterly payment → `quarterly_overdue` resolves

## Deduplication

The notification service deduplicates by `(user_id, type)`. If you already have an active `visit_overdue` alert, syncing won't create a duplicate — it updates the existing one.

## Notification Center

Access notifications via the **bell icon** in the header:

* Unread count badge on the bell
* Dropdown panel with severity-colored rows
* Mark individual notifications as read
* Mark all as read
* Dismiss (soft-delete) individual notifications

## Email Digest

Users who opt in receive a daily email summary of active alerts. Toggle email notifications on the **Profile** page.

## Where Alerts Link

Each alert type links to a specific section on the relevant page. When you tap an action item on the Dashboard, the app navigates to the target page, smooth-scrolls to the section, and flashes an amber highlight for 1.5 seconds.

| Alert                     | Links To                                                                                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stipend_risk`            | Varies by failing check — `/tax-home#stipend-eligibility`, `/assignments#location-duration`, `/assignments#gsa`, `/map`, `/expenses`, `/mileage`, or `/tax-home#docs` |
| `itinerant_risk`          | `/tax-home#stipend-eligibility`                                                                                                                                       |
| `visit_overdue`           | `/tax-home#strength`                                                                                                                                                  |
| `property_rented_out`     | `/tax-home#stipend-eligibility`                                                                                                                                       |
| `missing_docs`            | `/tax-home#docs`                                                                                                                                                      |
| `long_assignment`         | `/assignments#location-duration`                                                                                                                                      |
| `gsa_exceeds`             | `/assignments#gsa`                                                                                                                                                    |
| `distance_below_50`       | `/map`                                                                                                                                                                |
| `credential_expiring`     | `/credentials`                                                                                                                                                        |
| `quarterly_overdue`       | `/tax-estimate#quarterly-payments`                                                                                                                                    |
| `quarterly_due`           | `/tax-estimate#quarterly-payments`                                                                                                                                    |
| `paycheck_discrepancy`    | `/assignments#assignment-list`                                                                                                                                        |
| `assignment_gap_upcoming` | `/assignments#assignment-list`                                                                                                                                        |

### Fallback Action Items

When no server alerts are active, the Dashboard shows contextual items:

| Item                    | Links To                       |
| ----------------------- | ------------------------------ |
| View Tax Estimate       | `/tax-estimate#tax-summary`    |
| Assignment ending soon  | `/assignments#assignment-list` |
| Review audit readiness  | `/tax-home#strength`           |
| Audit ready — no issues | `/tax-home#strength`           |