ifixkart-admin/docs/architecture/notification_gateway.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- Backend: FastAPI app with all models, services, schemas, routes
- Admin Panel: Next.js dashboard with all modules
  (CRM, POS, repairs, warranties, billing, notifications, etc.)
- Ecommerce: storefront (submodule) + product catalog
- AI Agents: .agents/ skill library for Antigravity IDE
- Docs: architecture, billing, notification gateway markdown
- Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
2026-10-13 12:59:47 +05:30

53 lines
3 KiB
Markdown

# 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.