naser
/
libra
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
libra/docs/epics/epic-8-email-notifications.md

8.3 KiB
Raw Blame History

Epic 8: Email Notification System

Epic Goal

Implement a comprehensive email notification system with professional templates, bilingual support, and reliable delivery for all platform communications.

Epic Description

Business Context

Email is the primary communication channel. Clients receive mandatory notifications (no opt-out) for account creation, booking updates, reminders, and timeline updates. Admin receives notifications for new bookings and system events.

Technical Context

  • Sender: no-reply@libra.ps
  • Sender Name: Libra Law Firm / مكتب ليبرا للمحاماة
  • SMTP: Configured via .env
  • Delivery: All mandatory (no opt-out for clients)
  • Templates: Professional with branding

Success Criteria

  • Professional email templates with branding
  • Bilingual emails (based on recipient preference)
  • All 9+ notification types implemented
  • Calendar file attachments
  • Queued delivery for performance
  • Plain text fallback
  • Consistent branding across all emails

Stories

Story 8.1: Email Infrastructure Setup

Description: Configure email sending infrastructure and base template.

Acceptance Criteria:

  • SMTP configuration via .env:
    • MAIL_MAILER
    • MAIL_HOST
    • MAIL_PORT
    • MAIL_USERNAME
    • MAIL_PASSWORD
    • MAIL_ENCRYPTION
    • MAIL_FROM_ADDRESS (no-reply@libra.ps)
    • MAIL_FROM_NAME
  • Base email template with:
    • Libra logo header
    • Navy blue (#0A1F44) and gold (#D4AF37) colors
    • Professional typography
    • Footer with firm contact info
    • Mobile-responsive layout
  • Plain text fallback generation
  • Queue configuration for async sending
  • Email logging for debugging

Technical Notes:

  • Use Laravel Mail with Mailable classes
  • Create base Mailable with shared layout
  • Configure queue connection

Story 8.2: Welcome Email (Account Created)

Description: Email sent when admin creates a new client account.

Acceptance Criteria:

  • Triggered on user creation
  • Content:
    • Personalized greeting (name/company)
    • "Your account has been created"
    • Login credentials (email, password)
    • Login URL link
    • Brief platform introduction
    • Contact info for questions
  • Language based on user's preferred_language
  • Call-to-action button: "Login Now"
  • Security note about changing password (N/A - admin only)

Technical Notes:

  • Mailable: WelcomeEmail
  • Trigger: User created event
  • Queue for performance

Story 8.3: Booking Submitted Confirmation

Description: Email to client confirming their booking request was submitted.

Acceptance Criteria:

  • Triggered on booking submission
  • Content:
    • "Your consultation request has been submitted"
    • Requested date and time
    • Problem summary preview
    • "Pending Review" status note
    • Expected response timeframe (general)
  • Language based on client preference
  • No action required message

Technical Notes:

  • Mailable: BookingSubmittedEmail
  • Trigger: Consultation created with status 'pending'

Story 8.4: Booking Approved Email

Description: Email to client when admin approves their booking.

Acceptance Criteria:

  • Triggered on booking approval
  • Content:
    • "Your consultation has been approved"
    • Confirmed date and time
    • Duration (45 minutes)
    • Consultation type (free/paid)
    • If paid: amount and payment instructions
    • Calendar file (.ics) attached
    • "Add to Calendar" button/link
    • Location/contact information
  • Language based on client preference
  • Professional confirmation tone

Technical Notes:

  • Mailable: BookingApprovedEmail
  • Attach .ics file from Epic 3
  • Trigger: Consultation status changed to 'approved'

Story 8.5: Booking Rejected Email

Description: Email to client when admin rejects their booking.

Acceptance Criteria:

  • Triggered on booking rejection
  • Content:
    • "Your consultation request could not be approved"
    • Original requested date and time
    • Rejection reason (if provided by admin)
    • Invitation to request new consultation
    • Contact info for questions
  • Empathetic, professional tone
  • Language based on client preference

Technical Notes:

  • Mailable: BookingRejectedEmail
  • Optional reason field from admin
  • Trigger: Consultation status changed to 'rejected'

Story 8.6: Consultation Reminder (24 Hours)

Description: Reminder email sent 24 hours before scheduled consultation.

Acceptance Criteria:

  • Scheduled job runs daily
  • Find consultations 24 hours away
  • Content:
    • "Reminder: Your consultation is tomorrow"
    • Date and time
    • Consultation type
    • Payment reminder (if paid and not received)
    • Calendar file link
    • Any preparation notes
  • Skip cancelled/no-show consultations
  • Language based on client preference

Technical Notes:

  • Scheduled command: php artisan reminders:send-24h
  • Run via Laravel scheduler
  • Mailable: ConsultationReminder24Email

Story 8.7: Consultation Reminder (2 Hours)

Description: Reminder email sent 2 hours before scheduled consultation.

Acceptance Criteria:

  • Scheduled job runs hourly
  • Find consultations 2 hours away
  • Content:
    • "Your consultation is in 2 hours"
    • Date and time
    • Final payment reminder (if applicable)
    • Contact info for last-minute issues
  • Skip cancelled/no-show consultations
  • Language based on client preference

Technical Notes:

  • Scheduled command: php artisan reminders:send-2h
  • More frequent checks for accuracy
  • Mailable: ConsultationReminder2hEmail

Story 8.8: Timeline Update Notification

Description: Email to client when admin adds update to their timeline.

Acceptance Criteria:

  • Triggered on timeline update creation
  • Content:
    • "Update on your case: [Case Name]"
    • Case reference number
    • Update content (full or summary)
    • Date of update
    • "View Timeline" button/link
  • Language based on client preference
  • Professional, informative tone

Technical Notes:

  • Mailable: TimelineUpdateEmail
  • Trigger: TimelineUpdate created event
  • Link to client dashboard timeline view

Story 8.9: Admin Notification - New Booking

Description: Email to admin when client submits new booking request.

Acceptance Criteria:

  • Triggered on booking submission
  • Sent to admin email
  • Content:
    • "New Consultation Request"
    • Client name (individual or company)
    • Requested date and time
    • Problem summary (full)
    • Client contact info
    • "Review Request" button/link
  • Admin language preference (or default)
  • Priority indicator in subject line

Technical Notes:

  • Mailable: NewBookingAdminEmail
  • Send to configured admin email
  • Include direct link to booking management

Story 8.10: Admin Notification - System Events

Description: Critical system notifications to admin.

Acceptance Criteria:

  • Email failures notification
  • Scheduled job failures notification
  • Critical errors summary
  • Content:
    • Event type and description
    • Timestamp
    • Relevant details
    • Recommended action (if any)
  • Sent immediately (not queued)
  • Clear subject line indicating urgency

Technical Notes:

  • Use Laravel exception handler
  • Monitor queues and scheduler
  • Consider separate notification channel

Dependencies

Epic Dependency
Epic 1 Base application, user preferences
Epic 2 User creation (welcome email)
Epic 3 Booking events, calendar files
Epic 4 Timeline updates

Risks & Mitigations

Risk Impact Mitigation
Email delivery failures High Queue retry, logging, admin alerts
SMTP configuration issues High Test email feature, validation
Spam filtering Medium Proper SPF/DKIM, professional content
Timezone issues in reminders Medium Store and display in consistent timezone

Definition of Done

  • All stories completed with acceptance criteria met
  • All 9+ email types implemented
  • Emails render correctly (HTML and plain text)
  • Bilingual emails working
  • Branding consistent across all emails
  • Queue processing reliable
  • Reminder jobs scheduled and tested
  • Calendar attachments working
  • Admin notifications delivered
  • Code formatted with Pint