Notification updates

backend/src/features/notifications/README.md

@@ -0,0 +1,121 @@
+# 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
+
+```bash
+# 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)