motovaultpro/backend/src/features/notifications

Notifications Feature Capsule

Quick Summary

Email and toast notification system for maintenance due/overdue items and expiring documents. Uses Resend for email delivery and provides admin-editable email templates. User-scoped data with per-entry email notification toggles.

API Endpoints

User Endpoints

• GET /api/notifications/summary - Get notification summary (counts for login toast)
• GET /api/notifications/maintenance - Get due/overdue maintenance items
• GET /api/notifications/documents - Get expiring/expired documents

Admin Endpoints

• GET /api/admin/email-templates - List all email templates
• GET /api/admin/email-templates/:key - Get single email template
• PUT /api/admin/email-templates/:key - Update email template
• POST /api/admin/email-templates/:key/preview - Preview template with sample variables

Structure

• api/ - HTTP endpoints, routes, validators
• domain/ - Business logic, services, types
• data/ - Repository, database queries
• migrations/ - Feature-specific schema
• tests/ - All feature tests

Email Templates

Predefined Templates (4 total)

1. maintenance_due_soon - Sent when maintenance is due within 30 days or 500 miles
2. maintenance_overdue - Sent when maintenance is past due
3. document_expiring - Sent when document expires within 30 days
4. document_expired - Sent when document has expired

Template Variables

Templates use {{variableName}} syntax for variable substitution.

Maintenance templates:

• userName, vehicleName, category, subtypes, dueDate, dueMileage

Document templates:

• userName, vehicleName, documentType, documentTitle, expirationDate

Dependencies

Internal

• core/auth - Authentication plugin
• core/logging - Structured logging
• core/config - Database pool and secrets

External

• resend - Email delivery service

Database

• Tables: email_templates, notification_logs
• FK: maintenance_schedules(email_notifications), documents(email_notifications)

Business Rules

Notification Triggers

Maintenance Due Soon:

• Next due date within 30 days OR
• Next due mileage within 500 miles of current odometer

Maintenance Overdue:

• Next due date in the past OR
• Current odometer exceeds next due mileage

Document Expiring Soon:

• Expiration date within 30 days

Document Expired:

• Expiration date in the past

Email Notification Toggle

• Per-entry toggle on maintenance_schedules.email_notifications
• Per-entry toggle on documents.email_notifications
• Default: false (opt-in)

Login Toast Summary

• Shows count of maintenance items requiring attention
• Shows count of documents requiring attention
• Displayed once per session on successful login

Security Requirements

1. All queries user-scoped (filter by user_id)
2. Prepared statements (never concatenate SQL)
3. User endpoints require JWT authentication
4. Admin endpoints require admin role
5. Template editing restricted to admins
6. Email logs track all sent notifications

Email Service Configuration

Environment Variables

• RESEND_API_KEY - Resend API key (required, stored in secrets)
• FROM_EMAIL - Sender email address (default: noreply@motovaultpro.com)

Email Delivery

• Uses Resend API for transactional emails
• Converts plain text templates to HTML with line breaks
• Tracks all sent emails in notification_logs table
• Logs failures with error messages for debugging

Testing

# Run feature tests
npm test -- features/notifications

Future Enhancements

• Batch notification processing (scheduled job)
• Notification frequency controls (daily digest, etc.)
• User preference for notification types
• SMS notifications (via Twilio or similar)
• Push notifications (via FCM or similar)