ADR-005: Notification Preferences
Status: Deferred Owner: @bilal @deen Date: 2025-12-06
Context
Envo sends notifications via SMS, email, and WhatsApp at various points (issue created, vendor assigned, issue completed, SLA breach). Currently no mechanism to configure channel preferences, frequency, quiet hours, or per-event opt-out.
Problems
- Notification fatigue — High-volume landlords get spammed
- Missed urgent alerts — Wrong channel, message ignored
- No user control — Can’t opt out of non-critical notifications
- Cost inefficiency — SMS when email would suffice
Decision
Deferred — Document requirements, implement when notification system is built.
Proposed Schema
notification_preferences— Per-user, per-org settings: default/urgent channel, digest frequency, quiet hours, event overrides (JSONB)organisation_notification_defaults— Org-level defaults
Resolution Logic
- Check user’s preferences for this org
- Fall back to organisation defaults
- Fall back to system defaults (email normal, SMS urgent)
- Apply quiet hours filter
- If digest enabled and not urgent, queue for digest
Event Types
| Event | Default Channel | Urgency | Digest-able? |
|---|---|---|---|
issue_created | normal | yes | |
issue_status_changed | normal | yes | |
vendor_assigned | normal | yes | |
vendor_accepted | sms | normal | no |
issue_completed | normal | yes | |
sla_breach | sms | high | no |
emergency_issue | sms | urgent | no |
Consequences
Positive
- Users control their notification experience
- Cost savings (email over SMS where appropriate)
- Supports digest for non-urgent updates
Negative
- More complexity in notification logic
- Users may misconfigure and miss important alerts
Risks
- Quiet hours applied to emergencies. Mitigated by bypassing quiet hours for
urgency = 'emergency'.