🚀 Backend Implementation Plan

Date: November 1, 2025
Focus: PDF Integration, Event Handlers, Backend Tests
Estimated Time: 12-16 hours

---

📊 CURRENT STATUS

What Already Exists ✅

Communication System:

• ✅ Communications service with channel adapters (Email, SMS, WhatsApp)
• ✅ Template renderer service
• ✅ Attachment handler service
• ✅ Rate limiter service
• ✅ Webhook controller (basic)
• ✅ Event handlers (low stock alerts, invites)
• ✅ Queue system
• ✅ Repositories and database layer

PDF System:

• ✅ Complete PDF generation infrastructure
• ✅ Puppeteer-based PDF generator
• ✅ Handlebars template renderer
• ✅ File system storage
• ✅ 13+ document templates (invoices, receipts, etc.)
• ✅ Template management system

Testing:

• ✅ Jest configuration exists
• ✅ Some spec files exist (service.spec.ts)
• ⚠️ Tests need to be written/completed

---

🎯 WHAT NEEDS TO BE IMPLEMENTED

1. PDF Integration for Communications (4-6 hours)

A) Communication PDF Templates (2h)

Create HTML templates for common communication types:

• Invoice communication (with invoice details)
• Payment confirmation
• Order confirmation
• General announcement letter

Files to Create:

apps/backend/src/pdf/infrastructure/templates/
  ├── communication-invoice.html
  ├── communication-payment.html
  ├── communication-order.html
  └── communication-general.html

B) PDF Attachment Service (2h)

Enhance attachment handler to:

• Generate PDFs on-demand for communications
• Attach generated PDFs to emails
• Store PDFs in file system
• Return PDF URLs for frontend download

Files to Enhance:

apps/backend/src/communications/application/services/
  └── attachment-handler.service.ts (enhance)

Files to Create:

apps/backend/src/communications/application/use-cases/
  ├── generate-communication-pdf.use-case.ts
  └── attach-pdf-to-communication.use-case.ts

C) Integration Points (1-2h)

• Connect PDF service to communication service
• Add PDF generation to send-communication flow
• Add PDF download endpoint

Files to Enhance:

apps/backend/src/communications/
  ├── communications.service.ts
  └── interfaces/communications.controller.ts

---

2. Event Handlers (3-4 hours)

A) Provider Webhook Handlers (2h)

Handle real-time events from providers:

SendGrid Webhooks:

• Email delivered
• Email opened
• Email clicked
• Email bounced
• Email dropped

Twilio Webhooks:

• SMS delivered
• SMS failed
• SMS status update

WhatsApp (Twilio) Webhooks:

• Message delivered
• Message read
• Message failed

Files to Enhance:

apps/backend/src/communications/interfaces/
  └── webhooks.controller.ts (enhance with all providers)

Files to Create:

apps/backend/src/communications/application/services/
  ├── sendgrid-webhook-handler.service.ts
  ├── twilio-webhook-handler.service.ts
  └── whatsapp-webhook-handler.service.ts

B) System Event Handlers (1-2h)

Handle internal system events:

Events to Handle:

• Communication sent → Update stats
• Communication failed → Trigger retry logic
• Communication delivered → Update customer last contact
• Queue job completed → Clean up resources
• Template used → Update usage stats

Files to Create:

apps/backend/src/communications/application/events/
  ├── on-communication-sent.handler.ts
  ├── on-communication-failed.handler.ts
  ├── on-communication-delivered.handler.ts
  └── on-queue-job-completed.handler.ts

C) Event Tracking Service (1h)

Centralized event tracking and logging:

Files to Create:

apps/backend/src/communications/application/services/
  └── event-tracking.service.ts

---

3. Backend Tests (5-6 hours)

A) Unit Tests (3h)

Test individual services and components:

Services to Test:

• communications.service.ts
• template-renderer.service.ts
• attachment-handler.service.ts
• rate-limiter.service.ts
• Channel adapters (email, sms, whatsapp)

Files to Complete:

apps/backend/src/communications/application/
  ├── communications.service.spec.ts (complete)
  ├── services/template-renderer.service.spec.ts (complete)
  ├── services/attachment-handler.service.spec.ts (complete)
  ├── services/rate-limiter.service.spec.ts (complete)
  ├── adapters/email-adapter.service.spec.ts (complete)
  ├── adapters/sms-adapter.service.spec.ts (complete)
  └── adapters/whatsapp-adapter.service.spec.ts (complete)

B) Integration Tests (2h)

Test complete flows:

Flows to Test:

1. Send email communication end-to-end
2. Send SMS with retries
3. Generate PDF and attach to email
4. Process queue jobs
5. Handle webhook events

Files to Create:

apps/backend/src/communications/
  └── __tests__/
      ├── send-communication.integration.spec.ts
      ├── pdf-attachment.integration.spec.ts
      ├── queue-processing.integration.spec.ts
      └── webhook-handling.integration.spec.ts

C) E2E Tests (1h)

Test complete user workflows:

Workflows to Test:

1. Create template → Send communication → Track delivery
2. Send bulk communications via queue
3. Webhook received → Status updated → Frontend notified

Files to Create:

apps/backend/test/
  └── communications/
      ├── communication-lifecycle.e2e-spec.ts
      └── bulk-sending.e2e-spec.ts

---

📋 IMPLEMENTATION ORDER

Phase 1: Testing Infrastructure (1h)

Why First: Need solid tests before adding features

1. ✅ Jest config verified
2. ✅ Test utilities created
3. ✅ Mock data helpers created
4. ✅ Test database setup

Phase 2: Backend Tests (4h)

Why Second: Understand existing code, ensure stability

1. Complete unit tests for existing services
2. Write integration tests for key flows
3. Add E2E tests for critical paths
4. Result: Confidence in existing code

Phase 3: Event Handlers (3h)

Why Third: Foundation for PDF and webhook integration

1. Enhance webhook controller
2. Create provider-specific handlers
3. Add system event handlers
4. Add event tracking
5. Result: Real-time status updates

Phase 4: PDF Integration (4h)

Why Last: Builds on stable, tested foundation

1. Create PDF templates
2. Enhance attachment service
3. Add PDF generation use cases
4. Add download endpoints
5. Result: PDF attachments working

---

🎯 PRIORITY MATRIX

Feature	Priority	Impact	Effort	Order
Backend Tests	🔴 CRITICAL	Very High	5h	1
Event Handlers	🔴 HIGH	High	3h	2
PDF Integration	🟡 MEDIUM	Medium	4h	3

---

📊 SUCCESS CRITERIA

PDF Integration ✅

• Can generate PDF from communication template
• PDF automatically attached to email
• PDF accessible via download endpoint
• 4+ communication PDF templates created
• Tests passing

Event Handlers ✅

• SendGrid webhooks fully handled
• Twilio webhooks fully handled
• WhatsApp webhooks fully handled
• System events tracked
• Real-time status updates working
• Tests passing

Backend Tests ✅

• 80%+ code coverage
• All critical paths tested
• Integration tests passing
• E2E tests passing
• CI/CD ready

---

🚀 QUICK START

Option 1: Start with Tests (Recommended)

cd /Users/luisrangel/devLR/rpa/flowpos-workspace/apps/backend

# Run existing tests
pnpm test

# Run in watch mode
pnpm test:watch

# Check coverage
pnpm test:cov

Option 2: Start with Event Handlers

# Check existing webhook controller
cat src/communications/interfaces/webhooks.controller.ts

# Enhance with provider-specific handlers

Option 3: Start with PDF Integration

# Check PDF infrastructure
ls -la src/pdf/

# Check existing templates
ls -la src/pdf/infrastructure/templates/

---

📁 FILE STRUCTURE

apps/backend/src/communications/
├── application/
│   ├── adapters/
│   │   ├── email-adapter.service.ts ✅
│   │   ├── email-adapter.service.spec.ts (complete)
│   │   ├── sms-adapter.service.ts ✅
│   │   ├── sms-adapter.service.spec.ts (complete)
│   │   ├── whatsapp-adapter.service.ts ✅
│   │   └── whatsapp-adapter.service.spec.ts (complete)
│   ├── events/
│   │   ├── on-communication-sent.handler.ts (NEW)
│   │   ├── on-communication-failed.handler.ts (NEW)
│   │   ├── on-communication-delivered.handler.ts (NEW)
│   │   └── on-queue-job-completed.handler.ts (NEW)
│   ├── services/
│   │   ├── attachment-handler.service.ts ✅ (enhance)
│   │   ├── sendgrid-webhook-handler.service.ts (NEW)
│   │   ├── twilio-webhook-handler.service.ts (NEW)
│   │   ├── whatsapp-webhook-handler.service.ts (NEW)
│   │   └── event-tracking.service.ts (NEW)
│   └── use-cases/
│       ├── generate-communication-pdf.use-case.ts (NEW)
│       └── attach-pdf-to-communication.use-case.ts (NEW)
├── interfaces/
│   └── webhooks.controller.ts ✅ (enhance)
└── __tests__/
    ├── send-communication.integration.spec.ts (NEW)
    ├── pdf-attachment.integration.spec.ts (NEW)
    ├── queue-processing.integration.spec.ts (NEW)
    └── webhook-handling.integration.spec.ts (NEW)

apps/backend/src/pdf/infrastructure/templates/
├── communication-invoice.html (NEW)
├── communication-payment.html (NEW)
├── communication-order.html (NEW)
└── communication-general.html (NEW)

apps/backend/test/communications/
├── communication-lifecycle.e2e-spec.ts (NEW)
└── bulk-sending.e2e-spec.ts (NEW)

---

🎯 ESTIMATED TIME

Task	Estimated	Actual	Status
Testing Infrastructure	1h	—	☐
Unit Tests	3h	—	☐
Integration Tests	2h	—	☐
E2E Tests	1h	—	☐
Webhook Handlers	2h	—	☐
System Event Handlers	1-2h	—	☐
Event Tracking	1h	—	☐
PDF Templates	2h	—	☐
PDF Service Integration	2h	—	☐
PDF Endpoints	1h	—	☐
TOTAL	15-17h	—	☐

---

🎉 NEXT STEPS

Choose your starting point:

A) Tests First (Recommended)

• Build confidence in existing code
• Catch bugs early
• Set up CI/CD foundation
• Start: Complete existing .spec.ts files

B) Event Handlers First

• Get real-time updates working
• Foundation for monitoring
• Improve user experience
• Start: Enhance webhooks.controller.ts

C) PDF Integration First

• Most visible feature
• Direct user value
• Uses existing PDF infrastructure
• Start: Create communication PDF templates

---

📚 RESOURCES

Documentation

• SendGrid Webhook Docs: https://docs.sendgrid.com/for-developers/tracking-events/event
• Twilio SMS Callbacks: https://www.twilio.com/docs/sms/api/message-resource#message-status-values
• Twilio WhatsApp Status: https://www.twilio.com/docs/whatsapp/api#message-status-values
• Jest NestJS Testing: https://docs.nestjs.com/fundamentals/testing
• Puppeteer PDF Generation: https://pptr.dev/#?product=Puppeteer&version=v21.0.0&show=api-pagepdfoptions

Existing Code to Reference

• PDF Generation: apps/backend/src/pdf/
• Communication Services: apps/backend/src/communications/application/
• Existing Tests: Look for .spec.ts files

---

✅ COMPLETION CHECKLIST

PDF Integration

• 4 PDF templates created
• PDF generation service working
• PDF attachment to emails working
• PDF download endpoint working
• Tests written and passing

Event Handlers

• SendGrid webhooks handled
• Twilio SMS webhooks handled
• WhatsApp webhooks handled
• System events tracked
• Event logging working
• Tests written and passing

Backend Tests

• All existing spec files completed
• Unit tests at 80%+ coverage
• Integration tests passing
• E2E tests passing
• CI/CD pipeline configured

---

Document Version: 1.0
Last Updated: November 1, 2025
Status: 📋 READY TO IMPLEMENT