Module 13: Notifications
⛔ SUPERSEDED 2026-06-11 — Sprig-era feature spec (pre-pivot). The authoritative current design is the locked schema in docs/SCHEMA.md, the module's entry in docs/PROJECT_DECISIONS.md, and the responsibility/seam maps in docs/MODULE_INDEX.md + docs/CROSS_MODULE_CONTRACTS.md. This file is retained for historical feature context only; do NOT treat its scope/table/feature claims as current (it predates the nursery→generic pivot, the HR-out-of-scope cut, the identity/payments/integrations/files extractions, and the schema locks). Superseded note added 2026-06-11.
Status: ✅ Locked for v1.0
Schema: notifications
Feature count: 128 features in v1.0
Build estimate: Strategic spec only — implementation effort TBD
Last updated: 2026-05-12
Overview
Notifications is the cross-cutting "send things to people" infrastructure module. It owns email, SMS, push, in-app, web push, Slack, and webhook delivery; templates; customer/staff preferences; compliance enforcement; multi-channel orchestration; deliverability monitoring; campaign management; and analytics.
Other modules emit notification-triggering events; Notifications decides how, when, and where to deliver them based on tenant configuration, customer preferences, compliance rules, and rate limits.
Notifications is consumed by every module via event subscription. Notifications depends on Module 5 (CRM) for customer preferences, Module 10 (Admin) for tenant configuration, and external providers (Resend, Twilio, FCM/APNS) for actual delivery.
Routing note (Architecture Redesign 2026-05-13): External delivery providers (Resend, Twilio, FCM, APNS) are owned and configured via the Integrations module (Core & Platform Layer). They follow the unified connector pattern. Notifications still owns orchestration, templates, multi-channel routing, compliance enforcement (CAN-SPAM/TCPA/GDPR), audit log, and analytics; Integrations owns the provider connectors (API client, authentication, delivery API calls, webhook receivers for delivery status). The line: Notifications decides what to send, when, to whom, and in what shape; Integrations executes the delivery against a specific provider's API.
Target Customer Profile
- Mid-size growth-stage retail nursery, $500K–$5M revenue
- Sends 1,000–10,000 transactional notifications per month
- Sends 5,000–50,000 marketing notifications per month at peak season
- Mix of customer-facing and tenant-staff-facing notifications
- Email + SMS + push for customer communications
- Email + in-app for staff alerts
- Spring-weighted notification volume (3x normal in March-May)
Architecture Principles
Multi-channel orchestration
Same notification can be sent via multiple channels with deduplication. Channel priority and fallback configured per notification type.
Compliance-first
CAN-SPAM, TCPA, GDPR consent enforcement is built into the dispatch layer. Notifications that would violate compliance are blocked, not sent.
Configurability
Every channel, template, schedule, rate limit, and policy is configurable per tenant via the Owner Dashboard (Module 10).
Tier Behavior
| Tier |
Notifications capability |
| Starter |
Email channel only; transactional + basic marketing; built-in templates; basic analytics |
| Pro |
All channels (email, SMS, push, in-app, web push); custom templates; A/B testing; predictive send-time; analytics |
| Enterprise |
All Pro + Slack channel + webhook channel + custom From/Reply-To + provider failover + approval workflows + dedicated sender reputation + advanced compliance monitoring |
Feature Hierarchy (128 features across 15 groups)
Group 1: Notification Channels (8 features)
| # |
Feature |
Notes |
| 1.1 |
Email channel |
Resend integration; built-in for all tenants |
| 1.2 |
SMS channel |
Twilio integration; Pro+ tier feature |
| 1.3 |
Push notification channel (mobile) |
FCM (Android), APNS (iOS) |
| 1.4 |
In-app notification channel |
Real-time within app |
| 1.5 |
Web push channel |
For tenants using web admin |
| 1.6 |
Slack channel (Enterprise) |
Tenant Slack workspace integration |
| 1.7 |
Webhook channel (Enterprise) |
External system notifications |
| 1.8 |
Multi-channel orchestration |
Same notification delivered via multiple channels with deduplication |
Group 2: Email Notifications (12 features)
| # |
Feature |
Notes |
| 2.1 |
Transactional email (receipts, confirmations) |
Always delivered (not subject to marketing opt-out) |
| 2.2 |
Marketing email (campaigns, offers) |
Subject to opt-out |
| 2.3 |
Email templates per tenant |
Branded with tenant logo, colors |
| 2.4 |
Email template versioning |
Multiple template versions per notification type |
| 2.5 |
Email scheduling |
Send at specific time |
| 2.6 |
Email A/B testing |
Test variants (Pro+) |
| 2.7 |
Email open tracking |
Pixel-based; respects DNT |
| 2.8 |
Email click tracking |
Link-based; respects DNT |
| 2.9 |
Email bounce handling |
Hard bounces → mark email invalid; soft bounces tracked separately |
| 2.10 |
Email unsubscribe handling |
One-click unsubscribe per CAN-SPAM |
| 2.11 |
Email authentication (SPF, DKIM, DMARC) |
Configurable per tenant for deliverability |
| 2.12 |
Custom From address & Reply-To address per tenant |
"info@nursery-name.com" instead of generic Vrida address |
Group 3: SMS Notifications (10 features)
| # |
Feature |
Notes |
| 3.1 |
Transactional SMS (order ready, etc.) |
Pro+ tier; Twilio |
| 3.2 |
Marketing SMS (offers, campaigns) |
Requires explicit opt-in per TCPA |
| 3.3 |
SMS templates per tenant |
Branded sender ID where possible |
| 3.4 |
SMS character limits |
160 char standard; long messages split |
| 3.5 |
SMS scheduling |
Delivery at specific time |
| 3.6 |
SMS opt-in management |
Reply YES to subscribe; verify before sending |
| 3.7 |
SMS opt-out management |
Reply STOP to unsubscribe; immediate respect |
| 3.8 |
SMS delivery status tracking |
Sent/delivered/failed states |
| 3.9 |
SMS link tracking |
Short URL with tracking |
| 3.10 |
Two-way SMS conversation |
Customer replies → routed to staff |
Group 4: Push Notifications (8 features)
| # |
Feature |
Notes |
| 4.1 |
Push registration on customer app |
App requests permission, registers with backend |
| 4.2 |
Push opt-in management |
User can opt-in/out per category |
| 4.3 |
Push delivery scheduling |
Send at specific time |
| 4.4 |
Push notification badges |
App icon shows unread count |
| 4.5 |
Push notification deep-linking |
Tap notification → opens specific app screen |
| 4.6 |
Push delivery status |
Successful/failed; reasons for failure |
| 4.7 |
Push notification categories |
Plant care / orders / loyalty / promotions — opt-in per category |
| 4.8 |
Push notification analytics |
Open rate, action rate |
Group 5: In-App Notifications (6 features)
| # |
Feature |
Notes |
| 5.1 |
In-app notification feed |
Bell icon shows unread count; click to see all |
| 5.2 |
In-app notification persistence |
Notifications saved per user |
| 5.3 |
Mark as read |
User dismisses individual or all |
| 5.4 |
Notification categories in-app |
Same as push categories |
| 5.5 |
Real-time delivery |
WebSocket/SSE for instant arrival |
| 5.6 |
Notification action buttons |
"View order", "Mark resolved", "Snooze" buttons |
Group 6: Notification Templates & Customization (12 features)
| # |
Feature |
Notes |
| 6.1 |
Template library |
Pre-built templates for common notifications |
| 6.2 |
Custom template creation |
Tenant builds custom notification templates |
| 6.3 |
Template variables |
Inject customer name, order details, etc. |
| 6.4 |
Multi-language templates |
Per-customer language preference |
| 6.5 |
Template preview |
See rendered template before sending |
| 6.6 |
Template branding |
Logo, colors, fonts per tenant |
| 6.7 |
Template versioning |
Edit history; rollback |
| 6.8 |
Template approval workflow (Enterprise) |
Marketing manager approves before tenant uses |
| 6.9 |
Template AI assistance |
AI suggests copy, subject lines, content |
| 6.10 |
Template performance tracking |
Open/click rates per template version |
| 6.11 |
Multi-step journeys with branching logic |
"If open → SMS reminder; if not → second email" — automated workflows |
| 6.12 |
Dynamic content blocks |
Same email, different content per segment (e.g., "Annuals section" for one segment, "Trees section" for another) |
Group 7: Customer-Facing Notifications (10 features)
| # |
Feature |
Notes |
| 7.1 |
Receipt email |
Sale receipt to customer |
| 7.2 |
Order confirmation email |
Reservation/order created |
| 7.3 |
Order ready notification |
Customer notified plant is ready for pickup |
| 7.4 |
Order modified notification |
Order changes communicated |
| 7.5 |
Order cancellation notification |
With reason |
| 7.6 |
Plant care reminder |
Personalized to customer's plants |
| 7.7 |
Loyalty status notification |
Tier change, anniversary, promotion |
| 7.8 |
Marketing campaign notification |
Spring sale, new arrivals, etc. |
| 7.9 |
Customer service response |
Tenant's reply to customer message |
| 7.10 |
Payment receipt |
Confirmation of payment received |
Group 8: Tenant-Facing Notifications (10 features)
| # |
Feature |
Notes |
| 8.1 |
Operational alert |
Low stock, A/R aging, security events |
| 8.2 |
Financial alert |
Daily sales summary, weekly P&L |
| 8.3 |
Customer alert |
New review, complaint, large purchase |
| 8.4 |
Vendor alert |
PO confirmations, late deliveries |
| 8.5 |
System alert |
Maintenance, downtime, version updates |
| 8.6 |
Compliance alert |
Tax filing due, certification expiring |
| 8.7 |
Security alert |
Suspicious activity, unauthorized access |
| 8.8 |
Tier limit alert |
"Approaching SKU limit" |
| 8.9 |
Subscription alert |
Trial ending, charge failed |
| 8.10 |
Performance alert |
Site capacity, system performance issues |
Group 9: Notification Scheduling & Delivery (13 features)
| # |
Feature |
Notes |
| 9.1 |
Real-time delivery |
Notification fires immediately on event |
| 9.2 |
Scheduled delivery |
"Send this at 10am Saturday" |
| 9.3 |
Recurring delivery |
Weekly digest, monthly summary |
| 9.4 |
Delivery time-of-day preferences |
Respect customer's preferred time |
| 9.5 |
Delivery frequency limits |
Max per day; rate limiting per customer |
| 9.6 |
Delivery deduplication |
Same notification not sent twice |
| 9.7 |
Delivery retry on failure |
Failed delivery retries up to N times |
| 9.8 |
Delivery batching |
Multiple notifications batched into digest |
| 9.9 |
Notification quotas per tenant |
Track SMS, email volume against tenant limits |
| 9.10 |
Notification quota auto-purchasing or overage |
Tenant runs out → automatic purchase or overage charge |
| 9.11 |
Notification quiet hours (per customer) |
"Don't send between 10pm-7am customer local time" |
| 9.12 |
Notification predictive send-time (AI) |
AI predicts best time to send per customer |
| 9.13 |
Notification expiration / time-sensitivity |
Time-sensitive notifications expire; e.g., "ready for pickup" only valid 4 hours |
Group 10: Notification Preferences & Opt-Out (8 features)
| # |
Feature |
Notes |
| 10.1 |
Customer notification preferences (granular) |
Per-channel, per-category opt-in/out |
| 10.2 |
Tenant staff notification preferences |
What staff wants alerted on |
| 10.3 |
Global opt-out (no notifications at all) |
User completely opts out |
| 10.4 |
Notification preference inheritance |
Default → channel → category → specific |
| 10.5 |
Opt-in verification (TCPA) |
Confirmation before SMS marketing |
| 10.6 |
Opt-out audit trail |
When/who opted out of what |
| 10.7 |
Compliance opt-out enforcement |
Marketing must respect opt-out within 10 days (CAN-SPAM) |
| 10.8 |
Preference center |
User-facing page to manage all preferences |
Group 11: Notification Analytics & Reporting (9 features)
| # |
Feature |
Notes |
| 11.1 |
Delivery success rate |
% delivered vs failed per channel |
| 11.2 |
Engagement rate |
Open + click + action rate |
| 11.3 |
Channel performance |
Which channels work best |
| 11.4 |
Campaign performance |
ROI of marketing notifications |
| 11.5 |
Notification volume by tenant |
How many sent per period |
| 11.6 |
Notification costs (SMS, etc.) |
Tenant sees their notification spend |
| 11.7 |
Notification engagement per customer |
Which customers respond, which don't |
| 11.8 |
Notification disruption (unsubscribe pattern) |
Where do users opt out |
| 11.9 |
Notification spam testing / score prediction |
"This message has X% spam likelihood — review before sending" |
Group 12: Compliance & Regulatory (7 features)
| # |
Feature |
Notes |
| 12.1 |
CAN-SPAM compliance |
Sender info, unsubscribe link, address |
| 12.2 |
TCPA compliance |
SMS opt-in verification, opt-out respect |
| 12.3 |
GDPR consent tracking |
When/how customer consented to marketing |
| 12.4 |
Notification audit log |
All sent notifications tracked |
| 12.5 |
Unsubscribe compliance |
One-click unsubscribe per CAN-SPAM |
| 12.6 |
Sensitive data masking |
PII in notification logs masked |
| 12.7 |
Compliance pre-check |
Before send, system flags CAN-SPAM, TCPA, and opt-in risk indicators. Tenant attests transactional vs marketing intent on flagged sends. Audit log captures the attestation. System does not unilaterally block sends; the tenant is the legal sender. |
Group 13: Multi-Channel Orchestration (6 features)
| # |
Feature |
Notes |
| 13.1 |
Same notification, multiple channels |
Email + SMS + push for same event |
| 13.2 |
Channel priority routing |
"Try email first, fall back to SMS" |
| 13.3 |
Channel cost optimization |
Use cheapest channel for non-urgent |
| 13.4 |
Cross-channel deduplication |
Same user, same notification = once |
| 13.5 |
Cross-channel analytics |
Aggregate response across channels |
| 13.6 |
Per-channel message customization |
Same notification, different copy per channel (email vs SMS vs push) |
Group 14: Notification Operations & Reliability (6 features)
| # |
Feature |
Notes |
| 14.1 |
Provider failover |
If Resend down, fall back to alternative |
| 14.2 |
Rate limiting |
Per-tenant API limits |
| 14.3 |
Queue management |
Pending notifications visible |
| 14.4 |
Bulk notification handling |
High-volume campaigns optimized |
| 14.5 |
Notification health monitoring |
Alerts on provider issues |
| 14.6 |
Sender reputation & deliverability monitoring |
Track sender score, blacklist status, ISP performance |
Group 15: Campaign Management (3 features)
| # |
Feature |
Notes |
| 15.1 |
Notification campaign approval workflow |
Marketing manager approves before tenant sends campaigns (Enterprise) |
| 15.2 |
A/B test winner auto-promotion |
Best-performing variant automatically wins; full send to remaining segment |
| 15.3 |
Notification event aggregation |
Multiple events in short time → single aggregated notification (prevents fatigue) |
Configurable Defaults (Owner Dashboard)
| Configurable |
Default |
| Email channel |
ON for all tenants |
| SMS channel |
OFF (Pro+ feature; opt-in per tenant) |
| Push channel |
ON (customer app) |
| In-app channel |
ON |
| Slack channel |
OFF (Enterprise; opt-in) |
| Webhook channel |
OFF (Enterprise; opt-in) |
| Default delivery frequency limit (per customer per day) |
5 messages max per day |
| Default delivery time-of-day |
8 AM - 8 PM customer local time |
| Marketing notifications opt-in default |
OFF (must opt in) |
| Transactional notifications |
Always ON (cannot opt out) |
| SMS opt-in verification |
Required (TCPA compliance) |
| Email open tracking |
ON |
| Email click tracking |
ON |
| Notification analytics retention |
90 days |
| AI template suggestion |
ON (Pro+) |
| Template A/B testing |
OFF (Pro+; opt-in) |
| Multi-channel deduplication |
ON |
| Channel failover |
OFF (Enterprise feature) |
| Notification queue visibility |
Manager+ |
| Bulk notification batch size |
100 per batch |
| Email authentication required |
Pro+ tier; configurable |
| Custom From address per tenant |
OFF (Pro+) |
| Notification quotas |
Per-tier — Starter: email 1,000/mo (transactional only), SMS 0 (SMS is Pro+); Pro: email 10K/mo, SMS 1,000/mo; Enterprise: email 100K/mo, SMS 10,000/mo |
| Auto-purchase notification overage |
OFF (tenant must opt-in) |
| Notification quiet hours per customer |
ON; default 10pm-7am customer local time |
| AI predictive send-time |
ON (Pro+) |
| Spam score check before send |
ON for marketing campaigns |
| Compliance pre-check before send |
ON (always) |
| Campaign approval workflow |
OFF (Enterprise; opt-in) |
| A/B test winner auto-promotion |
OFF (Enterprise; opt-in) |
| Event aggregation |
OFF (configurable to ON for non-urgent) |
| Sender reputation monitoring |
ON (Pro+) |
AI Features in Notifications
| Feature # |
AI capability |
| 6.9 |
AI template assistance (suggest copy, subjects) |
| 11.7 |
AI customer engagement scoring |
| 11.4 |
AI campaign performance optimization |
| 8.7 |
AI suspicious activity detection in security alerts |
| 2.6 |
AI A/B test results interpretation |
| 13.3 |
AI cost-optimized channel selection |
| 9.12 |
AI predictive send-time (best time to send per customer) |
| 11.9 |
AI spam score prediction |
| 15.3 |
AI event aggregation timing |
All AI features route via AIService (AI / Intelligence module; model-as-config; AWS Bedrock Claude Haiku 4.5 is the default model). Notifications does not call Bedrock directly.
Events Emitted
notifications.email_sentnotifications.email_deliverednotifications.email_openednotifications.email_clickednotifications.email_bouncednotifications.email_blocked (deliverability)notifications.email_authentication_failednotifications.sms_sentnotifications.sms_deliverednotifications.sms_failednotifications.push_sentnotifications.push_deliverednotifications.push_openednotifications.in_app_sentnotifications.in_app_readnotifications.notification_failednotifications.notification_queuednotifications.opt_in_receivednotifications.opt_out_receivednotifications.template_creatednotifications.template_updatednotifications.campaign_startednotifications.campaign_completednotifications.compliance_check_passednotifications.compliance_check_failednotifications.quota_threshold_reachednotifications.quota_exceedednotifications.sender_reputation_alertnotifications.predictive_send_time_calculatednotifications.event_aggregatednotifications.campaign_approval_requestednotifications.campaign_approvednotifications.ab_test_winner_promoted
Events Consumed
All modules emit events that may trigger notifications:
pos.sale_completed → receiptorders.ready_for_pickup → ready notificationinventory.stock_low → low stock alertcrm.churn_risk_detected → re-engagement campaignproduction.lot_ready → "New arrivals" notificationbilling.charge_failed → tenant payment alertaudit.security_event → security alertmulti_loc.site_capacity_alert → tenant alert- All other operational events
API Contract (NotificationsService — public methods)
High-level surface (detailed signatures during implementation):
- Send:
sendEmail, sendSMS, sendPush, sendInApp, sendWebPush, sendSlack, sendWebhook, sendMultiChannel
- Templates:
createTemplate, updateTemplate, previewTemplate, versionTemplate, getTemplateLibrary, setupJourney, addContentBlock
- Compliance:
verifyOptIn, recordOptOut, complianceCheck, getAuditTrail
- Quotas:
getQuotaStatus, purchaseQuota, setQuotaLimits
- Analytics:
getDeliveryStats, getEngagement, getCampaignROI, predictSpamScore, getSenderReputation
- Scheduling:
scheduleNotification, predictSendTime, setQuietHours, expireNotification, aggregateEvents
- Campaigns:
createCampaign, requestApproval, approveCampaign, promoteWinner, analyzePerformance
- Channel orchestration:
setChannelPriority, customizePerChannel, enableFailover
Out of Scope
| Capability |
Why excluded |
| Voice call notifications |
Out of scope |
| Postal mail notifications |
Out of scope |
| Fax notifications |
Out of scope |
| In-store kiosk display notifications |
Out of scope |
| Multi-tenant marketing platform integration (e.g., Marketo) |
Out of scope |
| Native iOS/Android Vrida admin app |
Future v1.5 |
| Custom SMS templates with shortcodes |
Future feature |
| Notification A/B testing for all tiers |
Pro+ only |
| Internal Vrida support notifications |
Out of scope (internal Vrida tool) |
| Email warmup (gradual sending volume increase) |
Handled by Resend |
| Email render testing across clients (Gmail, Outlook) |
Out of scope (specialized tool) |
| Custom IP for sending (multi-IP rotation) |
Handled by Resend |
| Notification ticket integration (auto-create support ticket) |
No ticket system in v1.0 |
| Voice assistant notifications (Alexa, Siri) |
Future v2.0 |
Gaps Identified from Market Research
Source: See docs/MARKET_RESEARCH_GAPS.md for the master gap registry.
Status: All gaps below are Open — pending decision. None have been accepted into scope yet.
| Gap # |
Gap |
What's missing in this module |
Research source |
Possible options |
| 25 |
AI marketing copilot at delivery |
No AI-suggested campaign timing layer yet |
Research §6.3.5 |
Deferred (v1.2) — Coupled with CRM Gap #25 in v1.2 AI bundle. |