- 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
3 KiB
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:
- Zero Browser Key Exposure: Sensitive API keys (
Zoho-enczapikey, OpenWA keys) never leak to the Next.js frontend. - Strict Idempotency: Prevents accidental duplicate dispatches using unique deterministic keys.
- Data Parity and Security: Recipient details (emails, phone numbers) are resolved securely on the backend, preventing cross-tenant or cross-customer data leakage.
- Resilience: Features an explicit 5-attempt exponential backoff retry policy before routing to a Dead Letter Queue (DLQ).
High-Level Architecture Flow
-
Frontend Trigger: The Next.js client calls
POST /api/v1/notifications/dispatch-entitywith: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)
-
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 ifentity.tenant_id != current_user.tenant_id. - Recipient contact details (
customer.email,customer.phone) are resolved server-side.
- The backend validates the JWT to extract the
-
Idempotency Check & Dual-Record Splitting:
- The system checks for existing records with
(tenant_id, idempotency_key). - If
channelisBOTH, the payload is split into two distinct database records (one for EMAIL, one for WHATSAPP) to track delivery status independently.
- The system checks for existing records with
-
Template Compilation:
EmailTemplateServicecompiles rich, responsive HTML snapshots containing exact point-in-time data (pricing, line items, GST split, warranty terms).
-
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_notificationstable 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.