# iFixKart Notification Gateway Architecture ## Overview The iFixKart Notification Gateway provides a unified, secure, and idempotent backend abstraction for dispatching notifications across multiple channels (Email via ZeptoMail, WhatsApp via OpenWA). By centralizing notification logic on the backend, the architecture guarantees: 1. **Zero Browser Key Exposure**: Sensitive API keys (`Zoho-enczapikey`, OpenWA keys) never leak to the Next.js frontend. 2. **Strict Idempotency**: Prevents accidental duplicate dispatches using unique deterministic keys. 3. **Data Parity and Security**: Recipient details (emails, phone numbers) are resolved securely on the backend, preventing cross-tenant or cross-customer data leakage. 4. **Resilience**: Features an explicit 5-attempt exponential backoff retry policy before routing to a Dead Letter Queue (DLQ). --- ## High-Level Architecture Flow 1. **Frontend Trigger**: The Next.js client calls `POST /api/v1/notifications/dispatch-entity` with: - `channel` (`EMAIL`, `WHATSAPP`, `BOTH`) - `notification_type` (e.g., `QUOTATION`, `INVOICE`) - `entity_id` (e.g., `SQ-2026-001`) - `idempotency_key` (Client-generated, e.g., `QUOTATION:SQ-2026-001:BOTH:1759321900`) 2. **Tenant Verification & Data Resolution**: - The backend validates the JWT to extract the `tenant_id`. - The entity (e.g., `CrmBulkQuotation`) is fetched. Access is strictly denied if `entity.tenant_id != current_user.tenant_id`. - Recipient contact details (`customer.email`, `customer.phone`) are resolved server-side. 3. **Idempotency Check & Dual-Record Splitting**: - The system checks for existing records with `(tenant_id, idempotency_key)`. - If `channel` is `BOTH`, the payload is split into two distinct database records (one for EMAIL, one for WHATSAPP) to track delivery status independently. 4. **Template Compilation**: - `EmailTemplateService` compiles rich, responsive HTML snapshots containing exact point-in-time data (pricing, line items, GST split, warranty terms). 5. **Dispatch & Lifecycle Management**: - Providers: ZeptoMail for emails, OpenWA for WhatsApp. - Delivery Lifecycle: `QUEUED` -> `PROCESSING` -> `ACCEPTED` (ZeptoMail) / `SENT` (OpenWA). - Failures trigger the Retry Policy (`+30s`, `+2m`, `+10m`, `DLQ`). --- ## Reusable Email Template Engine The `EmailTemplateService` serves as the single source of truth for responsive HTML formatting. It guarantees uniform iFixKart branding and dynamic data injection for: - Quotations (`quotation_email`) - Invoices (`invoice_email`) - Repair Tickets (`repair_ticket_email`) - Lead Qualifications (`lead_qualification_email`) --- ## Error Handling & Reliability - **Dead Letter Queue (DLQ)**: Failed notifications that exhaust their 4 retries are logged into the `dead_letter_notifications` table for manual review and resolution by administrators. - **Provider-Aware Statuses**: Status pipelines strictly map to provider capabilities, avoiding premature "DELIVERED" states based merely on HTTP 200 API acceptance.