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

3 KiB

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.