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 byalertService.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-forgetPOST /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:- Fetches each user’s data (tax home, assignments, expenses, credentials, quarterly payments)
- Computes alerts
- Syncs to the database
- 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_overdueresolves - Upload tax home docs →
missing_docsresolves - Record a quarterly payment →
quarterly_overdueresolves
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 the relevant page for action:| Alert | Links To |
|---|---|
| stipend_risk, itinerant_risk, visit_overdue, property_rented_out, missing_docs | /tax-home |
| long_assignment | /assignments |
| gsa_exceeds | /assignments |
| credential_expiring | /credentials |
| quarterly_overdue, quarterly_due | /tax-estimate |