ifixkart-admin/docs/architecture/iFixKart_Unified_Suite_Master_Plan.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

18 KiB

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

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:

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 <password_token>

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:

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:

{
  "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

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.