# Master Architectural Specification: iFixKart Unified Commerce, CRM & Repair ERP Suite ## Executive Overview This document represents the production-grade, finalized architectural specification for the **iFixKart Unified Suite**. It integrates E-Commerce, CRM, Repair ERP, Inventory, GST Billing, Review Moderation with Audit Trails, SLA Management, Multi-Dashboard Analytics, a **Self-Hosted WhatsApp Web Notification Gateway (OpenWA)**, and a **ZeptoMail / Zoho CPaaS Email Gateway** (`info@trionixsolution.com`), built on a multi-tenant ready schema, Redis Streams event bus, dedicated worker architecture, Dead Letter Queue (DLQ), full observability, and enterprise disaster recovery. --- ## Canonical Enterprise System Architecture ```mermaid flowchart TD subgraph Client_Layer ["Client Layer"] REACT["React Admin Panel"] STOREFRONT["Next.js Storefront & POS"] end REACT & STOREFRONT -->|HTTPS / WSS| FASTAPI["FastAPI API Gateway\n(JWT Auth + RBAC + Multi-Tenant Context)"] subgraph Domain_Services ["Domain Micro-Services Layer"] CRM["CRM Service\n(Customers, Contacts, Leads, Deals, Segments)"] REPAIR["Repair ERP Service\n(Devices, IMEI Registry, Tickets, Technicians)"] COMMERCE["Commerce & POS Service\n(Products, Inventory, Orders, POS)"] FINANCE["Billing & Finance Service\n(GST Invoices, Payments, Warranty, Refunds)"] end FASTAPI --> CRM & REPAIR & COMMERCE & FINANCE CRM & REPAIR & COMMERCE & FINANCE --> DB[(MySQL 8 Database Cluster)] subgraph Event_Driven_Infrastructure ["Event Bus & Notification Infrastructure"] EVENT_LAYER["Business Event Publisher"] REDIS_STREAMS[("Redis Streams Event Bus")] FINANCE & CRM & REPAIR & COMMERCE --> EVENT_LAYER --> REDIS_STREAMS REDIS_STREAMS --> EMAIL_WORKER["Email Worker Process"] REDIS_STREAMS --> WA_WORKER["WhatsApp Worker Process"] REDIS_STREAMS --> PUSH_WORKER["Push Worker Process"] EMAIL_WORKER --> ZEPTOMAIL["ZeptoMail / Zoho CPaaS Gateway\n(info@trionixsolution.com)"] PUSH_WORKER --> WEBPUSH["Web Push Gateway"] subgraph WA_Gateway_Architecture ["Self-Hosted WhatsApp Gateway"] WA_WORKER --> SESS_REGISTRY["Session Registry Engine"] SESS_REGISTRY --> OPENWA["OpenWA Instance(s)"] OPENWA --> SESS_VOL[("Persistent Session Volume Storage")] end OPENWA --> WA_NET["WhatsApp Network"] WA_WORKER & EMAIL_WORKER & PUSH_WORKER -->|Failed Max Retries| DLQ[("Dead Letter Queue (DLQ)")] end subgraph Observability_Layer ["Observability & System Health"] MONITORING["Monitoring & Telemetry Hub\n(Metrics, Latency, Queue Depth, Connection State)"] HEALTH["Health Endpoints (/health, /health/db, /health/redis, /health/whatsapp)"] end FASTAPI & REDIS_STREAMS & DB & OPENWA --> MONITORING & HEALTH ``` --- ## 1. Multi-Tenant Foundation & Database Architecture ### A. Multi-Tenancy Strategy (`tenant_id`) To ensure future multi-business isolation without requiring schema refactoring later, every core table incorporates a `tenant_id` column from Phase 0. ### B. Tenant-Scoped Unique Constraints All natural key uniqueness constraints are explicitly scoped to `tenant_id` to prevent cross-tenant data collisions: * `UNIQUE(tenant_id, phone)` on `customers` * `UNIQUE(tenant_id, sku)` on `products` * `UNIQUE(tenant_id, invoice_number)` on `invoices` * `UNIQUE(tenant_id, imei)` on `devices` ### C. Core MySQL 8 Database Entities The database schema consists of 23 explicitly defined entities: 1. `tenants`: Multi-tenant organization records. 2. `users`: System users, admins, technicians, and sales reps. 3. `roles`: Role definitions (`Super Admin`, `Admin`, `Technician`, `Sales Rep`, `Store Staff`). 4. `permissions`: Granular permission nodes (e.g. `repairs.create`, `invoices.approve`). 5. `customers`: Master customer profiles (`sales_tier`, `service_tier`, `LTV`, `is_dual_customer`). 6. `contacts`: Customer contact methods and address book entries. 7. `leads`: Inbound lead inquiries, lead scores, and source tracking. 8. `deals`: Sales pipeline deals (Kanban stages, estimated value, probability). 9. `products`: E-Commerce and POS product catalog with SKU, brand, and category. 10. `inventory`: Multi-warehouse stock tracking and low-stock threshold triggers. 11. `warehouses`: Physical store locations and inventory storage hubs. 12. `devices`: Customer device registry (Make, Model, Color, Serial/IMEI). 13. `repairs`: Mobile repair tickets (Diagnostic notes, assigned technician, ticket stage). 14. `repair_items`: Parts allocated and labor charges per repair job. 15. `invoices`: GST-compliant Tax Invoices, Pro-Forma quotes, and Credit Notes. 16. `payments`: Payment transaction ledger (Razorpay, PhonePe, UPI, Cash). 17. `reviews`: Customer reviews and ratings (`is_approved`, `moderated_by`, `moderation_reason`). 18. `notifications`: Outbound notification master records (`event_id`, `channel`, `status`). 19. `notification_attempts`: Individual delivery attempt logs (`attempt_number`, `provider`, `error`). 20. `dead_letter_notifications`: Failed notifications exceeding max retries for manual admin inspection. 21. `whatsapp_sessions`: Session registry credentials and connection states. 22. `audit_logs`: System-wide immutable action audit trail. 23. `business_events`: Event log history published to Redis Streams. ### D. Database Governance & Audit Policies * **Foreign Key Strategy**: Explicit foreign key constraints enforced with `ON DELETE RESTRICT` for financial and inventory safety. * **Indexing Strategy**: Composite indexes on `(tenant_id, created_at)`, `(tenant_id, customer_id)`, and `(tenant_id, status)`. * **Soft Delete Policy**: Soft deletes enforced via `deleted_at DATETIME NULL` on transactional tables. * **Audit Fields Policy**: All applicable business entities contain standard audit fields (`created_at`, `created_by`, `updated_at`, `updated_by`, `deleted_at`); system-generated and technical entities (e.g. `notification_attempts`, `business_events`, `audit_logs`) use system/service/event identifiers where user attribution is not applicable. * **Transaction Boundaries**: Strict database transaction blocks (`db.begin()`, `db.commit()`, `db.rollback()`) around all multi-table updates (e.g., Repair Completion + Inventory Deduction + Invoice Creation). --- ## 2. Database Backup & Disaster Recovery Strategy ### A. MySQL 8 Database Backup & Recovery * **Automated Daily Full Backup**: Daily physical/logical snapshots (`mysqldump` / `Percona XtraBackup`) executed at off-peak hours (02:00 UTC). * **Point-In-Time Recovery (PITR)**: Continuous binary logging (`binlog`) enabling point-in-time restoration down to the exact second. * **Backup Encryption**: All backup files encrypted at rest using AES-256 before storage. * **Off-Server Remote Storage**: Encrypted backups automatically synced to isolated remote cloud storage (AWS S3 / Google Cloud Storage) across separate geographic regions. * **Retention Policy**: 30 days of daily backups, 12 months of monthly archive snapshots. * **Automated Restore Testing**: Monthly automated restoration drills in an isolated staging environment to verify backup integrity and compute Recovery Time Objective (RTO < 1 hour) and Recovery Point Objective (RPO < 5 mins). ### B. Redis Streams Persistence & Recovery * **Hybrid Persistence Strategy**: Configured with combined **RDB snapshots** (every 15 mins) and **AOF (Append-Only File)** synced with `fsync everysec`. * **Disaster Recovery Restart**: In the event of a container crash, Redis automatically reconstructs the stream queue state from AOF on startup without losing unacknowledged business events. ### C. OpenWA Persistent Session Backup * **Session Storage Backup**: Daily automated backup of `/var/lib/openwa/sessions` persistent volume archives. * **Session Encryption**: Session state files encrypted before remote storage to safeguard WhatsApp tokens. * **Fast Session Restore**: Container recovery script mounts the session volume back into new OpenWA container instances, restoring WhatsApp connection state without requiring QR re-scanning. --- ## 3. Notification Infrastructure, Redis Streams & Worker Architecture ### A. Async Worker Architecture (Decoupled & Scalable) Notification triggers bypass synchronous request loops. FastAPI publishes events to **Redis Streams**, where decoupled dedicated worker processes consume and execute notifications asynchronously: ```mermaid flowchart LR FastAPI["FastAPI App"] -->|Publish Event| RedisStreams["Redis Streams"] subgraph Workers ["Independent Worker Scale Set"] RedisStreams --> EmailWorker["Email Worker (ZeptoMail API / SMTP)"] RedisStreams --> WAWorker["WhatsApp Worker (OpenWA Gateway)"] RedisStreams --> PushWorker["Push Worker (Web Push / FCM)"] end EmailWorker --> ZeptoMail["ZeptoMail / Zoho CPaaS (info@trionixsolution.com)"] WAWorker --> OpenWA["OpenWA Notification Gateway"] PushWorker --> WebPush["FCM / Web Push"] ``` ### B. Email Gateway Integration Details (ZeptoMail / Zoho CPaaS) * **Provider**: ZeptoMail / Zoho CPaaS API & SMTP * **Host**: `smtp.zeptomail.in` / `cpaas.zoho.in` * **Ports**: `465 (SSL)` / `587 (TLS)` * **Sender Email**: `info@trionixsolution.com` * **SMTP Username**: `emailapikey` * **API REST Endpoint**: `https://cpaas.zoho.in/v1.1/email` * **Auth Header**: `Authorization: Zoho-enczapikey ` ### C. Delivery Safety, Circuit Breakers & Dead Letter Queue (DLQ) * **Rate Limiter**: Strict message rate limits per recipient/channel (e.g. Max 5 msgs/min). * **Retry Policy**: Exponential backoff retry policy (Attempts at 0s, 30s, 2m). * **Circuit Breaker**: Automatically trips and pauses queue consumption if OpenWA or ZeptoMail reports service unavailability. * **Dead Letter Queue (DLQ)**: If a notification fails all 3 attempts, it is moved to `dead_letter_notifications` for manual admin inspection and one-click resend. ### D. Normalized Notification Log Schemas #### 1. `notifications` (Master Notification Record) | Field | Type | Description | | :--- | :--- | :--- | | `id` | `VARCHAR(36)` | Unique ULID (`NOT-10292`) | | `tenant_id` | `VARCHAR(36)` | Multi-tenant ID | | `event_id` | `VARCHAR(36)` | Source Business Event ID | | `recipient` | `VARCHAR(255)` | Target Phone / Email / User ID | | `channel` | `ENUM` | `WHATSAPP`, `EMAIL`, `WEB_PUSH` | | `template_id` | `VARCHAR(100)` | Template reference ID | | `status` | `ENUM` | `PENDING`, `QUEUED`, `SENDING`, `SENT`, `DELIVERED`, `READ`, `FAILED`, `CANCELLED` | | `created_at` | `DATETIME` | Event creation timestamp | | `completed_at` | `DATETIME` | Final resolution timestamp | #### 2. `notification_attempts` (Granular Delivery Attempts) | Field | Type | Description | | :--- | :--- | :--- | | `id` | `VARCHAR(36)` | Unique ULID (`ATT-5011`) | | `notification_id` | `VARCHAR(36)` | Foreign Key to `notifications.id` | | `attempt_number` | `INT` | 1, 2, or 3 | | `provider` | `VARCHAR(50)` | `OpenWA`, `ZeptoMail`, `FCM` | | `request_id` | `VARCHAR(100)` | External Gateway Message ID | | `status` | `ENUM` | `SUCCESS`, `FAILED` | | `error_log` | `TEXT` | Diagnostic exception stack trace | | `created_at` | `DATETIME` | Execution timestamp | --- ## 4. OpenWA WhatsApp Gateway Architecture & Session Registry ### A. Multi-Session Registry Architecture To support single or multiple WhatsApp numbers per business tenant, FastAPI manages a **Session Registry**: ``` FastAPI Gateway │ ▼ WhatsApp Service Router │ ▼ Session Registry │ ├── Tenant A Session 1 (OpenWA Container Instance 1) └── Tenant A Session 2 (OpenWA Container Instance 2) │ ├── Session Storage (/var/lib/openwa/sessions/tenant_a_1) ├── QR Manager (Base64 QR Stream to Admin Panel) ├── Connection Monitor (Ping health check every 30s) └── Event Manager (Capture ACK, SENT, DELIVERED) ``` ### B. Secure Server-Side Proxy Isolation The React Admin Panel **never** exposes OpenWA master API keys or direct container ports. The browser connects exclusively to FastAPI endpoints via JWT-authenticated HTTPS/WSS routes: ```mermaid flowchart LR ReactAdmin["React Admin Panel"] -->|HTTPS / WSS (User JWT)| FastAPIProxy["FastAPI Proxy Router"] FastAPIProxy -->|Authenticated Internal REST (Master Key)| OpenWA["OpenWA Instance"] OpenWA -->|WhatsApp Web Protocol| WANet["WhatsApp Network"] ``` --- ## 5. Secrets Management & Production Configuration All sensitive keys are strictly managed via environment variables and production secrets key vaults (Docker Secrets / HashiCorp Vault). Secrets are **never** committed to Git or exposed in client bundles. ``` Secrets Hierarchy ├── JWT_SECRET (User session signing) ├── OPENWA_MASTER_KEY (Internal gateway authorization) ├── DATABASE_PASSWORD (MySQL 8 credentials) ├── REDIS_CREDENTIALS (Redis Streams password) ├── EMAIL_SENDER_ADDRESS ("info@trionixsolution.com") ├── ZEPTOMAIL_HOST ("smtp.zeptomail.in" / "cpaas.zoho.in") ├── ZEPTOMAIL_API_KEY (Zoho enczapikey token) └── ENCRYPTION_KEYS (Field-level customer PII encryption) ``` --- ## 6. Configurable Capacity Ratios & Review Moderation Audit ### A. Configurable VIP Capacity Ratio (`booking_capacity_config`) Rather than hard-coding VIP capacity limits, ratios are stored in system configuration: ```json { "general_capacity_percentage": 80, "priority_capacity_percentage": 20 } ``` Admins can adjust capacity ratios dynamically (e.g. `70/30` or `90/10`) from the Admin Settings dashboard without code redeployment. ### B. Strict Review Moderation Audit Trail Every review submission follows a strict moderation lifecycle with full auditing: * **Moderation States**: `PENDING` ➔ `APPROVED` (Visible on Storefront) OR `REJECTED` (Hidden). * **Audit Fields**: - `moderated_by`: User ID of approving/rejecting admin or sales manager. - `moderated_at`: Timestamp of moderation action. - `moderation_reason`: Mandatory notes field explaining why a review was rejected (e.g., *"Spam"*, *"Profanity"*, *"Irrelevant"*). --- ## 7. System Observability & Health Monitoring The system exposes structured telemetry and dedicated health check endpoints for uptime monitoring tools (Prometheus, Grafana, Datadog): ### A. System Health Endpoints * `/health`: Overall system status. * `/health/db`: MySQL database connection pool health & latency. * `/health/redis`: Redis Streams connection and queue depth. * `/health/email`: ZeptoMail API / SMTP gateway status. * `/health/whatsapp`: OpenWA gateway session state (`CONNECTED`, `DISCONNECTED`, `BATTERY_LEVEL`). ### B. Monitored Telemetry Metrics * Application logs (JSON structured logging). * Error rates & stack traces. * API response latency (P95, P99). * Redis queue depth & worker consumer lag. * Email & WhatsApp message success / failure / delivery rates. --- ## 8. Master 8-Phase Implementation Roadmap ```mermaid gantt title iFixKart Master Implementation Roadmap dateFormat YYYY-MM-DD section Phase 0 & Core Phase 0 — Foundation & Architecture :p0, 2026-10-01, 7d Phase 1 — CRM Core Engine :p1, after p0, 10d section Operations & ERP Phase 2 — Repair ERP & IMEI Management :p2, after p1, 12d Phase 3 — Inventory & E-Commerce POS :p3, after p2, 10d Phase 4 — Billing & GST Finance :p4, after p3, 8d section Gateways & Analytics Phase 5 — WhatsApp (OpenWA) & ZeptoMail:p5, after p4, 8d Phase 6 — Review Moderation System :p6, after p5, 6d Phase 7 — Multi-Dashboard Suite :p7, after p6, 8d ``` ### Detailed Phase Breakdown: * **Phase 0 — Foundation Infrastructure**: - Multi-tenant JWT Authentication, Role-Based Access Control (RBAC), Audit Log framework, Business Event Publisher, Redis Streams setup, Notification Worker base, Secrets management (ZeptoMail / OpenWA), System `/health` endpoints, Backup scripts. * **Phase 1 — CRM Core Engine**: - Customer profiles (`sales_tier`, `service_tier`, `LTV`), Contact hierarchy, Leads engine, Deals Kanban pipeline, Customer 360 view. * **Phase 2 — Repair ERP & IMEI Management**: - Device catalog, IMEI/Serial registry, Repair Tickets lifecycle, Diagnostic checklists, Technician dispatch, Status tracking, Repair Estimates, QC testing, Warranty records. * **Phase 3 — Inventory + E-Commerce POS**: - Products catalog, Spare parts stock management, Multi-warehouse inventory, Suppliers, Purchase orders, Order fulfillment, POS interface, Stock movement ledger. * **Phase 4 — Billing & GST Finance**: - GST Tax Invoices (Line item IMEI & SAC/HSN tax), Payment ledgers, Refunds, Credit Notes, Warranty vouchers, Bulk Quotation engine. * **Phase 5 — Self-Hosted WhatsApp Gateway (OpenWA) & Email Gateway (ZeptoMail)**: - OpenWA container microservice, ZeptoMail API/SMTP Integration (`info@trionixsolution.com`), FastAPI proxy router, QR Pairing UI (`/admin/whatsapp-gateway`), Session Storage volume backup, Session Registry, Worker consumers, Rate limiter, Circuit breaker, Dead Letter Queue (DLQ), `notifications` & `notification_attempts` audit tables. * **Phase 6 — Review & Reputation System**: - Submission endpoints, Moderation approval queue with audit fields (`moderated_by`, `moderation_reason`), Public storefront sync, Rating analytics, Negative feedback rescue workflow. * **Phase 7 — Multi-Dashboard Analytics Suite**: - CRM Dashboard, Repair ERP Dashboard, Inventory Dashboard, Sales Dashboard, Finance Dashboard, Review Dashboard, Technician Dashboard.